Physical Address
304 North Cardinal St.
Dorchester Center, MA 02124
ISO/IEC 29341-18-13 — UPnP ContentDirectory v2 服务
UPnP AV 架构 — 媒体内容浏览、搜索和元数据发现
ContentDirectory v2 服务简介
ISO/IEC 29341-18-13 标准定义了 ContentDirectory v2 服务（CDS），这是 UPnP AV 架构的基础组件，提供了浏览、搜索和枚举 UPnP 媒体服务器上可用内容的标准化机制。ContentDirectory 服务充当多媒体内容的虚拟文件系统，将媒体项目（音频曲目、视频文件、图像、播放列表）及其相关元数据以分层集合的形式暴露给 UPnP 控制点。通过该服务，控制点可以实现诸如”查找所有爵士乐专辑”或”浏览最近添加的视频”等内容发现功能，从而为用户提供丰富的内容浏览体验。
可以将 ContentDirectory 服务理解为”媒体数据库 API”，它允许控制点发现媒体服务器上有哪些内容可用，探索其组织结构，检索详细的元数据，并获取通过 AVTransport 服务进行实际媒体播放所需的 URI。
ContentDirectory v2 在 v1 的基础上引入了多项重要增强功能，包括支持丰富的元数据查询、多条件搜索能力、通过 CreateObject 和 DestroyObject 动作实现容器更新的功能，以及基于 XPath 语法的完整 Search 动作。v2 规范还增加了对外部元数据源的支持和改进的标签能力，使其适用于需要高效搜索和浏览的大型媒体收藏（超过 10,000 个项目）。
面向对象的内容层次结构
ContentDirectory 服务将媒体内容建模为按两种基本类型组织的对象层次结构：容器和项目。容器是逻辑分组（类似于文件系统目录），可以包含项目和子容器。项目代表单个媒体资源（一首歌、一个视频、一张照片）。每个对象由唯一的 ObjectID 字符串标识，并带有由 UPnP AV 的 DIDL-Lite（数字项目声明语言）模式定义的一组属性。
| UPnP 类 | 示例属性 | 用例 |
|---|---|---|
| object.item.audioItem.musicTrack | dc:title, upnp:artist, upnp:album, upnp:originalTrackNumber, dc:duration | 数字图书馆中的音乐曲目 |
| object.item.videoItem.movie | dc:title, upnp:genre, upnp:longDescription, upnp:rating, res:resolution | 电影和视频内容 |
| object.item.imageItem.photo | dc:title, dc:date, upnp:album, res:resolution | 数字照片 |
| object.container.album.musicAlbum | dc:title, dc:creator, upnp:artist, upnp:album | 音乐曲目的逻辑分组 |
在设计大型收藏的 ContentDirectory 实现时，请使用 Browse 动作的 “BrowseDirectChildren” 标志，并利用 Filter 参数仅请求控制点实际需要的属性。这可以显著减小响应负载大小并提高浏览性能。
搜索能力与工程模式
v2 ContentDirectory 服务提供了强大的 Search 动作，接受 SearchCriteria 字符串参数。搜索查询语法基于 XPath 的子集，支持布尔运算符（and, or, not）、比较运算符（=, !=, <, >）以及用于子字符串匹配的 contains 函数。例如，搜索 “dc:creator contains ‘贝多芬’ and upnp:class = ‘object.item.audioItem.musicTrack'” 将返回贝多芬的所有音乐曲目。控制点还可以组合多个搜索条件，实现复杂的内容发现查询。
SortCriteria 参数允许服务器按一个或多个属性对结果进行排序，这对于处理能力有限的移动控制点尤为重要。排序语法使用 “+” 表示升序、”-” 表示降序，多个条件以逗号分隔。例如 “+dc:title,-upnp:artist” 表示按标题升序、艺术家降序排列。此外，v2 规范中的 SearchCapabilities 状态变量允许服务器广告支持搜索的元数据属性，帮助控制点定制其搜索 UI。
在资源有限的嵌入式系统上实现 Search 动作的完整 XPath 解析可能会消耗大量资源。考虑将搜索限制为仅支持预索引属性（dc:title, dc:creator, upnp:class），并对不支持的搜索条件返回相应的错误。标准允许服务器拒绝过于复杂的搜索。
另一个重要的工程模式是 CreateObject 动作，它使控制点能够在媒体服务器上创建新的内容对象。这对于创建播放列表、将照片组织到相册或使用自定义元数据标记内容等应用至关重要。v2 规范增加了 CreateReference 动作，可以从一个容器创建指向现有对象的引用（软链接），使内容无需复制即可出现在多个逻辑位置。
ContentDirectory 服务的 Search 动作如果接受未经处理的用户输入，可能存在注入攻击风险。控制点和服务器实现都必须对搜索条件进行适当的转义和验证，防止恶意构造的 XPath 查询导致信息泄露或服务异常。建议在服务器端实施搜索白名单机制，限制可搜索的属性和运算符。
此外，SystemUpdateID 和 ContainerUpdateIDs 机制在管理动态内容库时特别有用。控制点可以订阅这些事件变量，在收到变更通知后仅刷新受影响的容器，而无需重新浏览整个内容树。这种增量更新模式对于电视直播频道列表、网络电台目录等频繁变化的内容源至关重要，可以显著降低网络带宽消耗和控制点处理负载。
常见问题
问：Browse 和 Search 动作有什么区别？
答：Browse 导航分层容器结构（类似于浏览文件系统），而 Search 跨多个容器同时执行基于内容的查询。浏览始终可用，而搜索能力取决于服务器实现。
答：Browse 导航分层容器结构（类似于浏览文件系统），而 Search 跨多个容器同时执行基于内容的查询。浏览始终可用，而搜索能力取决于服务器实现。
问：ContentDirectory v2 中的分页如何工作？
答：使用 Browse 或 Search 动作的 StartingIndex 和 RequestedCount 参数。响应中包含 NumberReturned（实际返回的项目数）和 TotalMatches（匹配查询的项目总数）字段，支持增量获取。
答：使用 Browse 或 Search 动作的 StartingIndex 和 RequestedCount 参数。响应中包含 NumberReturned（实际返回的项目数）和 TotalMatches（匹配查询的项目总数）字段，支持增量获取。
问：一个内容项能否出现在多个容器中？
答：可以，通过 v2 中的 CreateReference 动作实现。这会创建一个指向原始对象的引用（类似于符号链接），而无需复制底层数据或元数据。这种方法节省存储空间并确保所有引用始终指向最新版本的内容。
答：可以，通过 v2 中的 CreateReference 动作实现。这会创建一个指向原始对象的引用（类似于符号链接），而无需复制底层数据或元数据。这种方法节省存储空间并确保所有引用始终指向最新版本的内容。
问：ContentDirectory v2 如何处理大量收藏的性能问题？
答：标准建议使用分页浏览（StartingIndex 和 RequestedCount 参数），并利用 Filter 参数仅请求必要的属性。此外，服务器应实现数据库索引以加速频繁查询的属性。v2 规范中的 SystemUpdateID 机制允许控制点高效检测内容变更，避免完整的重新浏览。
答：标准建议使用分页浏览（StartingIndex 和 RequestedCount 参数），并利用 Filter 参数仅请求必要的属性。此外，服务器应实现数据库索引以加速频繁查询的属性。v2 规范中的 SystemUpdateID 机制允许控制点高效检测内容变更，避免完整的重新浏览。
