User Search Capabilities

With the RTC Client API 1.2, user search facilities may be easily implemented as part of an RTC client. When CoCreateInstance is called to create an RTC Client object, the interface IRTCUserSearch is created by default and can be retrieved by calling QueryInterface with IID_IRTCUserSearch (B619882B-860C-4db4-BE1B-693B6505BBE5) as the iid.

IRTCUserSearch has two methods implemented on it: IRTCUserSearch::CreateQuery, which generates a query object; and IRTCUserSearch::ExecuteSearch, which takes a query object and performs the search, returning the results as a search results event (RTCE_USERSEARCH).

IRTCUserSearch::ExecuteSearch takes a user-generated cookie as a parameter, which can be used to uniquely identify search results. The cookie is a long integer value, generated and supplied programmatically. It is up to the application author to ensure the uniqueness of the cookie and to maintain the list of all active cookies.

A query object has the IRTCUserSearchQuery interface implemented on it, which allows a number of properties to be set that influence the query behavior and results. Search terms, set with the IRTCUserSearchQuery::put_SearchTerm property, filter the search query based on LDAP user object attributes available in the server user database, such as e-mail address, office number, user name, and others. Each term also has a corresponding search string, which is used as a prefix filter (the supplied string value followed by zero or more characters) for all search terms of a given type. For example, a search term might be set for the the user object attribute with an LDAP name of "telephoneNumber" and a search string of "(425)", which would retrieve all GC user entries that have a phone number whose area code is 425 and formatted with parentheses. The performance of the search is entirely dependent on the server implementation.

Some common user object attribute LDAP names are as follows.

  • User display name—"displayName".
  • User first name—"givenName".
  • User last name—"sn".
  • Company name—"company".
  • User street address—"streetAddress".
  • Last time user logged on—"lastLogon".

Note   Apart from the standard search terms supported in the API, the application could specify certain search terms that are specific to the SIP server that is performing the search operation. For example, the Microsoft® Office Live Communications server matches the value of the search parameter "msRTCURI" against a user's SIP URI, and matches the search term "msRTCMail" against a user's e-mail address.

If an attribute that does not exist on the user object is specified (commonly in the form of a typographic error or incorrectly assumed naming convention), the search will return no results, even if other attributes are correct and viable. For a complete list of user object attributes, please refer to the User Class schema documentation in the Active Directory® topic of the Platform SDK.

Besides search terms, Active Directory domains can be used to filter results, using the IRTCUserSearchQuery::put_SearchDomain property. When the domain is set for a query object, the search will be restricted to GC user objects available in that domain. If no domain is set, the default domain will be the one associated with the client user.

Search preferences can be provided to limit the amount of time the client spends awaiting search results, or the number of results returned to the client. Despite these preferences, a server may continue to search well after the wait time has expired, and it may have results beyond the desired maximum. The IRTCUserSearchQuery::put_SearchPreferences property allows a maximum search wait time to be specified, as well as a ceiling on the number of results returned. The default maximum search time is 30 seconds.

To execute the query, you must pass a pointer to the IRTCUserSearchQuery interface on the query object to ExecuteSearch, which will begin the search and fire a user search results event upon completion. An event handler for this event, RTCE_USERSEARCH, must be enabled through IRTCEventNotification. The results will be available through the IRTCUserSearchResultsEvent interface obtained by calling QueryInterface on the event object returned by a RTCE_USERSEARCH event. The IRTCUserSearchResultsEvent interface will have the following methods available for obtaining and listing the results:

Results are stored as objects with a column name and a value, accessible through the IRTCUserSearchResult interface implemented on them. To retrieve this value, call the IRTCUserSearchResult::get_Value method with the column name as a RTC_USER_SEARCH_COLUMN enumeration value. The value associated with the column will be returned as a BSTR.

If more results than the specified maximum are available on the server, the IRTCUserSearchResultsEvent::get_MoreAvailable Boolean property can be used to determine if the maximum should be increased in a subsequent identical search, or to prompt the user for additional search terms that will refine the search on the server. There may be an enforced result limit set on the server.

The results values can be used to add a Buddy object by passing the column values for RTCUSC_URI and RTCUSC_DISPLAYNAME to the bstrPresentityURI and bstrUserName parameters, respectively, of the IRTCClientPresence2::AddBuddyEx method. A new Watcher object can be created by passing those same values to IRTCClientPresence2::AddWatcherEx. In this way, a search can be used to add new buddies and watchers to the client presence logically and conveniently.

  • Last updated on