2.2.2.15 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.1.

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.149

Store

Request and Response

section 2.2.3.167.2

Name

Request

section 2.2.3.113.2

Query

Request

section 2.2.3.132

And

Request

section 2.2.3.10

Or

Request

section 2.2.3.119

FreeText

Request

section 2.2.3.76

airsync:Class

Request and Response

section 2.2.3.27.4

airsync:CollectionId

Request and Response

section 2.2.3.30.4

ConversationId

Request

section 2.2.3.35.2

GreaterThan

Request

section 2.2.3.81

email:DateReceived

Request

section 2.2.3.52

Value

Request

section 2.2.3.185

LessThan

Request

section 2.2.3.90

EqualTo

Request

section 2.2.3.60

documentlibrary:LinkId

Request

section 2.2.3.48

Options

Request

section 2.2.3.118.4

airsync:MIMESupport

Request

section 2.2.3.103.2

Range

Request and Response

section 2.2.3.133.2

UserName

Request

section 2.2.3.182.2

Password

Request

section 2.2.3.125.2

DeepTraversal

Request

section 2.2.3.41

RebuildResults

Request

section 2.2.3.134

Picture

Request

section 2.2.3.128.2

MaxSize

Request

section 2.2.3.98.2

MaxPictures

Request

section 2.2.3.97.2

Status

Response

section 2.2.3.166.12

Response

Response

section 2.2.3.143.6

Result

Response

section 2.2.3.145.2

LongId

Response

section 2.2.3.92.3

Properties

Response

section 2.2.3.131.2

gal:DisplayName

Response

section 2.2.3.47.6

gal:Phone

Response

section 2.2.3.126

gal:Office

Response

section 2.2.3.114

gal:Title

Response

section 2.2.3.171

gal:Company

Response

section 2.2.3.33

gal:Alias

Response

section 2.2.3.9

gal:FirstName

Response

section 2.2.3.66

gal:LastName

Response

section 2.2.3.89

gal:HomePhone

Response

section 2.2.3.83

gal:MobilePhone

Response

section 2.2.3.107

gal:EmailAddress

Response

section 2.2.3.53.2

gal:Picture

Response

section 2.2.3.128.2

gal:Data

Response

section 2.2.3.39.3

Total

Response

section 2.2.3.173.2

The XML schema for the Search command request is described in section 6.31. The XML schema for the Search command response is described in section 6.32.

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.133.2.

Searching Outside the GAL

Typical Usage

Essentially, search involves the following three phases:

  1. The client issues a request for specific search results.

  2. The client uses subsequent requests to retrieve more results by incrementing the range.

  3. 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).

MS-ASCMD_pict4d4692cb-2564-4ca1-88de-e3c6407def17.png

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.4, 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

X

12.0

X

12.1

X

14.0

X

14.1

X

16.0

X

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, and 16.0.

  • SMS and Notes classes are supported only by protocol versions 14.0, 14.1, and 16.0.

Show: