GrooveContacts.Search Operation

Article
01/20/2015

Applies to: SharePoint Workspace 2010 | Visual Studio 2008

In this article
HTTP Post URL
Input Message Header
Input Message Parameters
Output Message Header
Return Value

The Search operation searches for contacts in a Groove Server Manager or in Public Workspace Contact Directory.

HTTP Post URL

The HTTP Post URL targets the service for the account. This URI is returned by the GrooveAccounts.Read2 operation in the Contacts parameter.

Input Message Header

GrooveRequestHeader specifies information common to all Groove Web Services, including the Groove Identity URL and the Groove Request key.

Input Message Parameters

<CallbackURI />
<TimeToLive />
<Query />
<Directory />

Element	Data type	Description
CallbackURI	xs:anyURI	URI used to automatically create a subscription. This URI identifies the client creating the subscription. The CallbackURI is a locator beginning with dpp://localhost. Note that Groove Web Services only use the CallbackURI as an identifier and do not try to resolve it to an actual Internet address. Typically the last field of the locator used in the CallbackURI identifies the SOAP client, but it should also include a unique ID so that two instances of the SOAP client have separate event queues, such as dpp://localhost/Fetch_test_2.5_client3982a83l. Note that if multiple subscriptions specify the same CallbackURI, a call to GrooveEvents.Read will read events from all these subscriptions.
TimeToLive	xs:int	Number of hours that the subscription should remain active if not deleted or updated.
Query	xs:string	String that is used to search for a substring match in any of the contact text fields.
Directory	xs:anyURI	Specifies the directory. This directory identifier is provided by the ReadAvailableDirectories operation in the ContactDirectory.ID element. If you do not specify a directory, the operation uses the Public Workspace Contact Directory.

Output Message Header

GrooveResponseHeader specifies the Response key.

Return Value

<SearchResult />

Element	Data type	Description
SearchResult	xs:string	Subscription ID used to identify events or to update or delete the subscription.

Remarks

To gain access to contacts, you can use GrooveContacts.ReadAvailableDirectories, Search, and GrooveContacts.Fetch. You can use Search to perform a text search of contacts listed in a directory. For each match in the directory, Search returns a directory entry identifier and summary information about the contact, such as the contact's FullName. Search does not by itself make the contacts accessible.

The Search operation returns its results indirectly by creating an event subscription and then returning the results in an event. This operation uses the event mechanism to return their events because the operation communicates with a server, and the time required to get the information can be dependent on network traffic. The subscription created for Search will receive a single event, which contains the results of the operation. After you call Search, you can access the subscription with the GrooveEvents.Read, GrooveSubscriptions.Delete, and GrooveSubscriptions.Update operations.

The Search operation return event contains a list of contact summaries, each of which contains the directory entry unique identifier. You can use the unique identifiers returned by Search to create a list that you can use as an input parameter to Fetch.

The Search operation return event has an event class of urn:groove-net:ContactDirectoryEvent and an event type of ContactSearchResultsEventData. The Search return data consists of a Status and a ContactSummaryList. The status can be "Succeeded", "Failed", "No matches found", or "More matches found". If the status is "Succeeded", all matches will be returned in the ContactSummaryList. If the status is "More matches found", a subset of the matches will be returned. There is no mechanism for getting the remaining matches, but you can refine the query and repeat the call to Search. If the status is "Failed" or "No matches found", the ContactSummaryList will not be returned.

There is an efficiency cost in making large numbers of contacts accessible. Consequently, you should minimize the number of contacts that you make accessible. If a Search operation returns a large number of contacts, you can reduce the number by either only selecting a subset of the returned contact summaries to add to the URI list or by repeating the Search with a more restrictive query.

You should call GrooveEvents.Read for the subscription created by Search until you get the one event. After this point, there is no need to continue polling the queue and you should delete the subscription. The CallbackURI specifies the event queue that will be used for these events. Because these operations return only a single event, you should not use the same queue for Search that you use for a subscription that requires continuous polling. Reusing one of these queues provides little advantage and adds programming complexity.

Note

Some contacts may not be associated with a SharePoint Workspace user and may only contain descriptive information, such as name and e-mail address. You cannot use an e-mail-only contact to send an invitation or instant message. If you attempt to use an e-mail-only contact to send a workspace invitation with the GrooveMembers.Create operation, the operation will fail.