2.2.1.16 Search
The Search command is used to find entries in an address book, mailbox, or document library (UNC or Windows SharePoint Services).
The Search namespace is the primary namespace for this section. Elements referenced in this section that are not defined in the Search namespace use the namespace prefixes defined in section 2.2.4.
The following table lists the elements that are used in Search command requests and responses.
|
Element name |
Scope |
Reference |
|---|---|---|
|
Search |
Request and Response |
section 2.2.3.159 |
|
Store |
Request and Response |
section 2.2.3.178.3 |
|
Name |
Request |
section 2.2.3.120.2 |
|
Query |
Request |
section 2.2.3.142.2 |
|
And |
Request |
section 2.2.3.10 |
|
Or |
Request |
section 2.2.3.126 |
|
FreeText |
Request |
section 2.2.3.80.2 |
|
airsync:Class |
Request and Response |
section 2.2.3.27.5 |
|
airsync:CollectionId |
Request and Response |
section 2.2.3.30.5 |
|
ConversationId |
Request |
section 2.2.3.35.2 |
|
GreaterThan |
Request |
section 2.2.3.86 |
|
email:DateReceived |
Request |
section 2.2.3.54 |
|
Value |
Request |
section 2.2.3.196 |
|
LessThan |
Request |
section 2.2.3.96 |
|
EqualTo |
Request |
section 2.2.3.62 |
|
documentlibrary:LinkId |
Request |
section 2.2.3.50 |
|
Options |
Request |
section 2.2.3.125.5 |
|
airsync:MIMESupport |
Request |
section 2.2.3.110.2 |
|
Range |
Request and Response |
section 2.2.3.143.3 |
|
UserName |
Request |
section 2.2.3.193.2 |
|
Password |
Request |
section 2.2.3.132.2 |
|
DeepTraversal |
Request |
section 2.2.3.41.2 |
|
RebuildResults |
Request |
section 2.2.3.144 |
|
Picture |
Request |
section 2.2.3.135.3 |
|
MaxSize |
Request |
section 2.2.3.105.3 |
|
MaxPictures |
Request |
section 2.2.3.104.3 |
|
Status |
Response |
section 2.2.3.177.13 |
|
Response |
Response |
section 2.2.3.153.7 |
|
Result |
Response |
section 2.2.3.155.3 |
|
LongId |
Response |
section 2.2.3.98.3 |
|
Properties |
Response |
section 2.2.3.139.3 |
|
gal:DisplayName |
Response |
section 2.2.3.49.7 |
|
gal:Phone |
Response |
section 2.2.3.133 |
|
gal:Office |
Response |
section 2.2.3.121 |
|
gal:Title |
Response |
section 2.2.3.182 |
|
gal:Company |
Response |
section 2.2.3.33 |
|
gal:Alias |
Response |
section 2.2.3.9 |
|
gal:FirstName |
Response |
section 2.2.3.70 |
|
gal:LastName |
Response |
section 2.2.3.95 |
|
gal:HomePhone |
Response |
section 2.2.3.89 |
|
gal:MobilePhone |
Response |
section 2.2.3.114 |
|
gal:EmailAddress |
Response |
section 2.2.3.55.3 |
|
gal:Picture |
Response |
section 2.2.3.135.3 |
|
gal:Data |
Response |
section 2.2.3.39.4 |
|
Total |
Response |
section 2.2.3.184.3 |
The XML schema for the Search command request is described in section 6.34. The XML schema for the Search command response is described in section 6.35.
The Accept-Language header in a Search command request is used to define the locale of the client so that the search is relevant. If the accept language is not specified, the search is conducted by using the server language.
Searching the Global Address List (GAL)
The Search command is used to find contacts and recipients in the GAL, and to retrieve information about them. When a search query matches more than one GAL entry, the Search command MUST return as many entries as requested, up to a total of 100 entries by default.
For each GAL entry that is found, the Search command returns all the non-empty properties that are indexed by the online ambiguous name resolution (ANR) in the global catalog server—for example, email alias, display name, first and last names, company name, and so on.
The client can optionally specify the maximum number of entries to retrieve in the Search command request by specifying the range. The server MUST return entries up to the number that is requested, and MUST also indicate the total number of entries that are found.
The text query string that is provided to the Search command is used in a prefix-string match. For example, if the client performs a Search with a Query element value of "Michael A.", the command returns the entries that contain the search string in any text field, such as "Michael Alexander", "Michael Allen". Because the Search command matches the Query element value against all GAL text properties that are indexed by using ANR, the client can also search by email address, company name, and so on.
The ANR system indexes the following properties:
Display name
Alias
FirstName
LastName
EmailAddress
The Search command results are sorted by the server according to their ordering in the GAL (that is, by the display name property). Because of how the search results are sorted, the client could have to sort the results to display results in a relevant manner to users. For example, a search for "123" might return all GAL entries that have mailing addresses or email addresses that begin with 123. The client can choose to display matching email addresses before mailing addresses, if they know their users use email addresses more frequently than mailing addresses, or mailing addresses before email addresses if mailing addresses are used more frequently.
The Range option is a zero-based index specifier in the form of "m-n". For more details about the meaning of the Range values, see section 2.2.3.143.3.
Searching Outside the GAL
Typical Usage
Essentially, search involves the following three phases:
The client issues a request for specific search results.
The client uses subsequent requests to retrieve more results by incrementing the range.
Any actions on the search results are carried out by using other protocol commands, such as ItemOperations, SmartReply, or SmartForward.
The following figure shows the typical usage of the Search command to retrieve successive result sets from the server and then perform some action based on those results (for example, retrieve the full message body for an email search result).
-
-
-
-
-
Figure 1: Search command process
-
-
-
-
Protocol Versions
The following table specifies the protocol versions that support this command. The client indicates the protocol version being used by setting either the MS-ASProtocolVersion header, as specified in [MS-ASHTTP] section 2.2.1.1.2.6, or the Protocol version field, as specified in [MS-ASHTTP] section 2.2.1.1.1.1, in the request.
|
Protocol version |
Command support |
|---|---|
|
2.5 |
Yes |
|
12.0 |
Yes |
|
12.1 |
Yes |
|
14.0 |
Yes |
|
14.1 |
Yes |
|
16.0 |
Yes |
|
16.1 |
Yes |
All protocol versions support search of an address book. Protocol version 2.5 does not support search of a mailbox or document library (UNC or Windows SharePoint Services).
For a mailbox search, the classes are supported as follows.
Email, Calendar, Contacts, and Tasks are supported by protocol versions 12.0, 12.1, 14.0, 14.1, 16.0, and 16.1.
SMS and Notes classes are supported only by protocol versions 14.0, 14.1, 16.0, and 16.1.