IRTCUserSearch::ExecuteSearch

  • Article

The ExecuteSearch method execute a user search, using a provided user search query object. Search results are returned asynchronously via the IRTCUserSearchResultsEvent interface, which is available when the RTCE_USERSEARCH event fires.

HRESULT ExecuteSearch(IRTCUserSearchQuery*pQuery,
IRTCProfile*pProfile,
LONG_PTRlCookie);

Parameters

  • pQuery
    [in] Pointer to the IRTCUserSearchQuery interface on a user search query object created with IRTCUserSearch::CreateQuery.
  • pProfile
    [in] Pointer to the IRTCProfile interface that is to be used to request the search. The search request is sent to the registrar server specified in the profile. If the server challenges the request, the username and password specified in the profile are used to authenticate the user. The profile does not need to be enabled. If this parameter is NULL, the RTC Client API attempts to find a suitable profile from the list of enabled profiles.
  • lCookie
    [in] An application-supplied cookie that identifies this request. This value is generated and maintained by the application, and is used to synchronize search requests and results returned by an RTCE_USERSEARCH event. The application is responsible for ensuring the uniqueness of the cookie.

Return Values

RTC methods may return an RTC_E_ constant.

Value Meaning
RTC_E_NO_PROFILE The pProfile parameter is NULL or the profile is not suitable for the search.
RTC_E_CLIENT_NOT_INITIALIZED The client object is not initialized.
RTC_E_UDP_NOT_SUPPORTED The current profile specifies the UDP transport for the registrar server. The user search is not allowed when the UDP transport is specified in the registrar server.
E_OUTOFMEMORY Insufficient memory to perform this operation.
E_POINTER The pProfile or pQuery parameter is not a valid pointer.
RTC_E_PLATFORM_NOT_SUPPORTED
Windows Me/98:  This method is not supported.
RTC_E_NO_PROFILE The pProfile parameter is NULL and the RTC Client API is unable to find a suitable profile for the search.

Remarks

The user search is not allowed if the registrar server or the service provider specified in the profile uses the UDP transport. The application should display an error message or disable user search functionality.

To execute a user search, a profile that has PC-PC capabilities specified in the session type settings must be currently enabled. A profile can be created with the IRTCClientProvisioning::GetProfile method and then enabled using the IRTCClientProvisioning::EnableProfile method.

Requirements

Redistributable: Requires Rtcdll.dll on Windows 2000, Windows XP, and Windows Server 2003.
Header: Declared in Rtccore.h.
Library: Included as a resource in Rtcdll.dll.
GUID: IID_IRTCUserSearch is defined as B619882B-860C-4db4-BE1B-693B6505BBE5.

See Also

IRTCUserSearch, IRTCUserSearchQuery, Create and Send a Search Request