ISO/IEC IEC 29341-16-10:2011 — UPnP AV内容目录服务

ContentDirectory服务概述

ISO/IEC 29341-16-10:2011定义了ContentDirectory:2服务，这是负责组织、浏览和搜索UPnP AV媒体服务器上媒体内容的组件。ContentDirectory服务呈现可用媒体项目——音乐、视频、图像和播放列表——的分层视图，以容器和项目的树结构组织。该服务是控制点发现可用内容并检索启动媒体播放所需的元数据和资源信息的主要接口。

该服务的正式标识为urn:schemas-upnp-org:service:ContentDirectory:2，并维护包括SystemUpdateID（系统更新ID）、ContainerUpdateIDs（容器更新ID）、SearchCapabilities（搜索能力）、SortCapabilities（排序能力）和FeatureList（功能列表）在内的状态变量。SystemUpdateID是一个单调递增的整数，当内容层次结构发生任何变化时递增。控制点缓存此值并与本地副本比较，以确定自上次浏览操作以来内容目录是否已更改。ContainerUpdateIDs变量通过列出已修改的特定容器及其各自的更新ID，提供更细粒度的变更通知。

ContentDirectory:2版本相比版本1引入了重要增强，包括：支持项目内的片段（允许引用媒体资源中的章节或时间范围）、用于添加新内容的CreateObject()动作、用于内容管理的DeleteObject()和UpdateObject()动作、带有更广泛搜索类别的增强搜索能力，以及用于广告高级能力（如扩展查询语言支持）的FeatureList状态变量。

内容层次结构与对象模型

CDS使用容器和项目的树结构组织内容。容器类似于文件系统中的目录——它们可以包含其他容器和项目。项目代表单个媒体资源，不能包含其他对象。树中的每个对象由持久的ObjectID字符串唯一标识。根容器的预定义ID为0。标准定义了一组upnp:class值来对对象进行分类：object.container用于容器，object.item用于项目，并具有专门的子类如object.item.audioItem.musicTrack、object.item.videoItem.movie和object.item.imageItem.photo。

每个对象携带来自都柏林核心（dc:title、dc:creator、dc:date）、UPnP特定属性（upnp:artist、upnp:genre、upnp:albumArtURI）以及资源描述符（res@protocolInfo、res@bitrate、res@duration、res@size、res@resolution）的元数据属性。res元素尤其重要，因为它们包含可获取媒体内容的实际URL。每个项目可以有多个res元素，表示相同内容的不同格式、比特率或分辨率，无需在内容树中创建多个项目即可实现自适应流传输和格式协商。

Browse()（浏览）动作是导航内容树的主要机制。它接受七个参数：ObjectID（对象ID）、BrowseFlag（浏览标志，BrowseDirectChildren或BrowseMetadata）、Filter（过滤）、StartingIndex（起始索引）、RequestedCount（请求数量）、SortCriteria（排序标准）和Filter（过滤）。BrowseFlag决定响应包含指定容器的直接子项还是仅包含容器本身的元数据。Filter参数是一个逗号分隔的属性名称列表，表示控制点感兴趣的属性——服务器应只返回请求的属性以最小化响应大小。StartingIndex和RequestedCount参数支持大型结果集的分页，这对于内存缓冲区有限的客户端和优化网络利用率至关重要。

搜索能力与元数据过滤

Search()（搜索）动作扩展了浏览功能，允许控制点使用结构化搜索条件查询内容树。搜索语法遵循属性 操作符 值模式，带有布尔组合符AND和OR。SearchCapabilities状态变量广告哪些属性支持搜索操作。典型的可搜索属性包括dc:title、dc:creator、upnp:artist、upnp:genre和upnp:class。比较操作符包括contains、derivedfrom、exists、=、!=、<、>等。搜索条件可以使用括号嵌套以构建复杂的布尔表达式。

示例搜索条件：upnp:class derivedfrom "object.item.audioItem" and dc:title contains "交响乐"。此查询返回标题包含”交响乐”的所有音频项目。搜索按惯例不区分大小写，但标准未强制要求——实现应记录其大小写敏感性行为。SortCriteria参数支持按多个属性排序，指定为逗号分隔的列表，带有可选的方向限定符（:asc或:desc）。SortCapabilities状态变量列出支持排序的属性。

Filter参数值得实现者特别注意。当控制点指定Filter列表时，服务器应只返回请求的属性。这是一项性能优化，在带宽受限的无线网络上对于移动控制点来说至关重要。当控制点只需要每个项目的标题、类和资源URL时，一个实现良好的CDS服务器可以将响应大小减少60-80%，相比于返回所有可用元数据。标准允许特殊值：*表示返回所有属性，@表示只返回ID和类。

ContentDirectory实现的工程要点

实现高性能ContentDirectory:2服务需要仔细的架构决策。对象数据库应支持事务性更新，以维护SystemUpdateID和各个容器更新ID之间的一致性。当内容发生变化时——无论通过UPnP动作还是外部修改——CDS必须原子地更新内容树并递增相关的更新计数器。未能维护一致性会导致控制点接收到过时数据或错过内容变更通知。

ImportResource和ExportResource动作支持设备之间的内容传输。这些动作与ConnectionManager服务协作，建立用于内容迁移的数据通道。CDS通过TransferProgress和TransferStatus变量跟踪传输进度。工程挑战：传输可能因网络故障或设备重启而中断。实现定期保存传输状态的检查点机制，允许从最后一个检查点恢复，而不是从头重新开始。标准定义了包括NotStarted、InProgress、Cancelled、Completed和Error在内的传输状态。

另一个关键实现细节是处理容器上的@childCount（子项计数）属性。此属性报告容器内的直接子项数量。服务器必须高效地统计子项而不枚举所有条目——维护一个持久化的子项计数，当添加或删除对象时增量更新。对于非常大的容器，子项计数应存储为预计算的值而不是实时计算。Browse()动作还应支持用于排序子结果的SortCriteria参数，这需要索引排序以避免大型容器上的性能退化。

常见问题