IContentDirectory::Search

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method searches for all objects that meet the specified search criteria.

Syntax

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

Parameters

• pszContainerID
  [in] ID of container object in which to execute the search. The root object in the ContentDirectory service data store has ID 0. Corresponds to the A_ARG_TYPE_ObjectID state variable.

• pszSearchCriteria
  [in] Search criteria string that specifies the objects to search for. Corresponds to the A_ARG_TYPE_SearchCriteria state variable. For more information about the syntax of strings passed in this parameter, see the documentation referenced in UPnP AV DCP Documentation.

• 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 which this method modifies to contain the number of objects that match the search criteria in pszSearchCriteria. 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_BAD_SEARCH_CRITERIA
• ERROR_AV_UPNP_CD_BAD_SORT_CRITERIA
• ERROR_AV_UPNP_CD_NO_SUCH_CONTAINER
• 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 Search action.

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 ContentDirectory service does not require that this method be implemented. The IContentDirectoryImpl class therefore overrides this method to return ERROR_AV_UPNP_INVALID_ACTION.

The pszSearchCriteria parameter is a key difference between this method and IContentDirectory::BrowseChildren. The format of the string passed in pszSearchCriteria is described in the section about A_ARG_TYPE_SearchCriteria in the Content Directory documentation, which is in the UPnP AV DCP Documentation. For example, if pszSearchCriteria is set to the string 'upnp:class contains "imageItem"', then this function will return all media contents that have "imageItem" in the associated upnp:class element string.

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

Requirements

See Also

Reference

IContentDirectory
IContentDirectoryImpl
parser (UPnP AV)
parser::GetFirstObject
UPnPAVError