IContentDirectory::BrowseChildren (Windows CE 5.0)

  • Article

Send Feedback

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.

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 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 Values

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.

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

Requirements

OS Versions: Windows CE 5.0 and later.
Header: Av_upnp.h.
Link Library: Av_upnp.lib.
C++ Namespace: av_upnp.

See Also

IContentDirectory | parser | parser::GetFirstObject | UPnPAVError

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.