IContentDirectory::BrowseChildren

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method returns DIDL-Lite XML that includes all of the first-level objects under the specified object and the metadata for all returned objects.

Syntax

virtual DWORD BrowseChildren(
  LPCWSTR pszObjectID,
  LPCWSTR pszFilter,
  unsigned long StartingIndex,
  unsigned long RequestedCount,
  LPCWSTR pszSortCriteria,
  wstring* pstrResult,
  unsigned long* pNumberReturned,
  unsigned long* pTotalMatches,
  unsigned long* pUpdateID
) = 0;

Parameters

• pszObjectID
  [in] ID of the object being browsed. The root object in the ContentDirectory service data store has an ID of 0. Corresponds to the A_ARG_TYPE_ObjectID state variable.

• pszFilter
  [in] Filter string that specifies the metadata properties to be returned in the pstrResult parameter. Corresponds to the A_ARG_TYPE_Filter state variable. For more information about the syntax of strings passed in this parameter, see the Content Directory documentation referenced in UPnP AV DCP Documentation.

• StartingIndex
  [in] Index of children to enumerate and return, starting from 0. Corresponds to the A_ARG_TYPE_Index state variable.

• RequestedCount
  [in] Number of children to enumerate and return. To enumerate and return data for all children, set this parameter to 0. Corresponds to the A_ARG_TYPE_Count state variable.

• pszSortCriteria
  [in] Sort string that specifies how the returned children are sorted. To not sort, set this parameter to the empty string. Corresponds to the A_ARG_TYPE_SortCriteria state variable. For more information about the syntax of strings passed in this parameter, see the documentation referenced in UPnP AV DCP Documentation

• pstrResult
  [in, out] Pointer to a string that, upon return, contains DIDL-Lite XML that represents the requested data. Corresponds to the A_ARG_TYPE_Result state variable.

• pNumberReturned
  [in, out] Pointer to an integer allocated by the caller which this method modifies to contain the number of objects returned in pstrResult. Corresponds to the A_ARG_TYPE_Count state variable.

  Note

  Code should validate that this number is correct before using it. For more information, see Do not trust data returned by control points and devices without validation in UPnP Security.

• pTotalMatches
  [in, out] Pointer to an integer allocated by the caller that this method modifies to contain the number of objects in the container specified by pszObjectID (independent of the index specified by StartingIndex). This value is 0 if the ContentDirectory service cannot compute the total number of matches and the number of objects returned is not equal to zero. Corresponds to the A_ARG_TYPE_Count state variable.

  Note

  Code should validate that this number is correct before using it. For more information, see Do not trust data returned by control points and devices without validation in UPnP Security.

• pUpdateID
  [in, out] Pointer to an integer allocated by the caller which this method modifies to contain the ContainerUpdateID of the container, if the pszObjectID parameter refers to a container. Corresponds to the A_ARG_TYPE_UpdateID state variable.

Return Value

Custom implementations can return appropriate error codes. Should return SUCCESS_AV if the method succeeds. Otherwise, should return an error code defined in WinError.h or UPnP.h, or one of the UPnP AV-specific return values specified in UPnPAVError, especially the following errors documented for this action in the ContentDirectory DCP documentation:

• ERROR_AV_UPNP_ACTION_FAILED
• ERROR_AV_UPNP_CD_NO_SUCH_OBJECT
• ERROR_AV_UPNP_CD_BAD_SORT_CRITERIA
• ERROR_AV_UPNP_CD_REQUEST_FAILED (occurs in this specific case if the ContentDirectory service cannot compute the total number of matches and the number of objects returned is 0)

Remarks

This method corresponds to the ContentDirectory service's Browse action with the BrowseFlag parameter set to BrowseDirectChildren. The IContentDirectory::BrowseMetadata method enables browsing metadata of a specific object.

To use the information returned in pstrResult, use the DIDL-Lite functionality provided by the parser class. The parser::GetFirstObject method accepts a DIDL-Lite string, like that returned in pstrResult, to enable iteration over all DIDL-Lite objects represented by the passed XML.

The pszFilter parameter is useful for filtering metadata, instead of filtering content. For example, consider a set of contents X, and each member of X has a set of metadata Y. By using pszFilter properly, this method will return a complete set of contents X with filtered metadata Y, instead of a filtered set of contents X with all metadata Y.

For more information about the actions, and the syntax expected by actions, in the ContentDirectory service, see UPnP AV DCP Documentation.

Requirements

See Also

Reference

IContentDirectory
parser (UPnP AV)
parser::GetFirstObject
UPnPAVError