Overview
The GalSearch command is a new feature in Exchange 2003 SP2 that will enable devices to perform a search query against the exchange server. This command does an ANR (Ambiguous Name Resolution) lookup to locate a mail-enabled object (Person/Conf Room, etc) from the Active Directory that matches the query string. For e.g.: You can search on alias or first name, etc and the return results would contain all the objects which matches the search query.
Working of GalSearch
Search Request:
The search query is a string which may denote different AD properties like (display name, office, alias, first name, etc). It is used to do a prefix search on ANR indexable properties for all the mail enabled objects on the exchange server. The objects whose ANR indexable properties match the search query are returned as the response results.
The search query is case insensitive and can include spaces, special characters, Unicode characters, etc.
The Exchange ActiveSync command for this feature is ‘Search’. In Exchange 2003 SP2 this command is used to query only the GAL store. Though there is a provision in the protocol to mention any store name, trying to query any other store other than GAL would result in error code response from the server.
The only option currently supported by the command is a range parameter used to limit the search results returned. The range parameter signifies a zero based index, where 0-0 means return the first row and 0-9 means return first 10 rows and so on. The server would respond with an error code if it’s not a zero based index. Also if this parameter is omitted, we will then return all results up to a max that will be defined in the server configuration settings. In Exchange 2003 Sp2, this max value is set at 100.
Result Response:
The response would include all the mail enabled objects (that matched the search query) with the AD properties as below. The following table lists the set of Exchange ActiveSync properties that will be returned by this command along with its corresponding AD property mapping. This set returned is fixed and is not negotiable. We optimize however by only sending the properties that have its corresponding AD attribute set on the object. If all the properties are set on the AD then all of them are returned.
|
Exchange ActiveSync property name |
AD attribute name |
|
Gal:DisplayName |
displayName |
|
Gal:Phone |
telephoneNumber |
|
Gal:Office |
physicalDeliveryOfficeName |
|
Gal:Title |
title |
|
Gal:Company |
company |
|
Gal:Alias |
mailNickName |
|
Gal:FirstName |
givenName |
|
Gal:LastName |
sn |
|
Gal:MobilePhone |
mobile |
|
Gal:EmailAddress |
mail |
Also responses include a command level status code used to indicate errors such as malformed requests or server errors. If the command level status code is success only then will a <Response> node be present. For status code success a command level status code 1 is returned. The Response node also contains a Store level status code indicating any store specific errors such as AD down, etc.
In addition to returning the property set per result, the response will also include the range of results returned in correspondence with the request. Suppose there are say, 20 results for a search query and if the request mentioned the range from 0-9, then the first 10 results are only returned.
Also there is a total value in the response to indicate to the clients if they need to do any additional requests to get the rest of the results.
If no results were found, the response will include an empty </Results> tag.
Different Status code
We have different status error codes embedded in the responses. For success we get back a status code 1. For protocol errors we get back a status code 2.
SEARCH_STATUS_CODE_SUCCESS 1
SEARCH_STATUS_CODE_PROTOCOL 2
SEARCH_STATUS_CODE_SERVER 3
Some of the cases where we would get a status code error 2 are:
- Invalid Store name (anything other than GAL)
- Empty query string
- Invalid Range for e.g.: (without a zero based index, exceeding range max value of 9999)
- Exceeding the search query string max length of 256 characters
- Sundar Sethuraman
