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.
The client issues a request to find specific emails that are returned by the server with preview text.
The client uses subsequent requests to retrieve more results by incrementing the range.
The client can use the ServerId element and CollectionId element to determine if an email item was previously synced.
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.
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 |