Delen via


2.2.1.2 Find

The Find command uses the Keyword Query Language (KQL) syntax to construct property restriction based searches for entries in a mailbox.

The Find namespace is the primary namespace for this section. Elements referenced in this section that are not defined in the Find namespace use the namespace prefixes defined in section 2.2.4.

The following table lists the elements that are used in Find command requests and responses.

Element name

Scope

Reference

Find

Request and Response

section 2.2.3.69

SearchId

Request

section 2.2.3.160

ExecuteSearch

Request

section 2.2.3.66

MailBoxSearchCriterion

Request

section 2.2.3.99

GALSearchCriterion

Request

section 2.2.3.82

Query

Request

section 2.2.3.142.1

FreeText

Request

section 2.2.3.80.1

airsync:Class

Request and Response

section 2.2.3.27.1

airsync:CollectionId

Request and Response

section 2.2.3.30.1

Options

Request

section 2.2.3.125.1

Range

Request and Response

section 2.2.3.143.1

DeepTraversal

Request

section 2.2.3.41.1

Status

Response

section 2.2.3.177.2

Response

Response

section 2.2.3.153.2

itemoperations:Store

Response

section 2.2.3.178.1

Result

Response

section 2.2.3.155.1

airsync:ServerId

Response

section 2.2.3.166.1

Properties

Response

section 2.2.3.139.1

email:Subject

Response

[MS-ASEMAIL] section 2.2.2.75.1

email:DateReceived

Response          

[MS-ASEMAIL] section 2.2.2.24

email:DisplayTo

Response

[MS-ASEMAIL] section 2.2.2.29

DisplayCc

Response

section 2.2.3.48

DisplayBcc

Response

section 2.2.3.47

email:Importance

Response

[MS-ASEMAIL] section 2.2.2.38

email:Read

Response

[MS-ASEMAIL] section 2.2.2.58

email2:IsDraft

Response

[MS-ASEMAIL] section 2.2.2.42

Preview

Response

section 2.2.3.137

HasAttachments

Response

section 2.2.3.87

email:From

Response

[MS-ASEMAIL] section 2.2.2.36

gal:DisplayName

Response

section 2.2.3.49.2

gal:Phone

Response

section 2.2.3.133.1

gal:Office

Response

section 2.2.3.121.1

gal:Title

Response

section 2.2.3.182.1

gal:Company

Response

section 2.2.3.33.1

gal:Alias

Response

section 2.2.3.9.1

gal:FirstName

Response

section 2.2.3.70.1

gal:LastName

Response

section 2.2.3.95.1

gal:HomePhone

Response

section 2.2.3.89.1

gal:MobilePhone

Response

section 2.2.3.114.1

gal:EmailAddress

Response

section 2.2.3.55.1

gal:Picture

Response

section 2.2.3.135.1

gal:Data

Response

section 2.2.3.39.1

Picture

Request

section 2.2.3.135.1

Total

Response

section 2.2.3.184.1

MaxSize

Request

section 2.2.3.105.1

MaxPictures

Request

section 2.2.3.104.1

The XML schema for the Find command request is described in section 6.7. The XML schema for the Find command response is described in section 6.8.

The Accept-Language header in a Find 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 Find 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 Find 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 Find 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 Find 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 Find command is used in a prefix-string match. For example, if the client performs a Find 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 Find 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 Find 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.

Searching Email Content

Search using the Find command involves the following phases.

  1. The client issues a request to find specific emails that are returned by the server with preview text.

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

  3. The client can use the ServerId element and CollectionId element to determine if an email item was previously synced.

  4. If an email item has not already been synced, the client can issue an ItemOperations command to fetch the item using the CollectionId and ServerId element.

  5. Any other actions on the search results are carried out by using other protocol commands, such SmartReply or SmartForward.

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

12.0

12.1

14.0

14.1

16.0

16.1

Yes