IAddrBook::GetSearchPath

The IAddrBook::GetSearchPath method returns an ordered list of entry identifiers of containers to be included in the name resolution process initiated by the IAddrBook::ResolveName method.

Quick Info

See IAddrBook : IMAPIProp.

HRESULT GetSearchPath(
  ULONG ulFlags,                 
  LPSRowSet FAR * lppSearchPath  
);

Parameters

ulFlags

[in] Bitmask of flags that controls the type of the strings returned in the search path. The following flag can be set:

MAPI_UNICODE: The returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppSearchPath

[out] Pointer to a pointer to an ordered list of container entry identifiers. GetSearchPath stores the ordered list in an SRowSet structure. If there are no containers in the address book hierarchy, zero is returned in the SRowSet structure.

Return Values

S_OK: The search path was successfully retrieved.

Remarks

Clients and service providers call the IAddrBook::GetSearchPath method to get the search path that is used to resolve names with IAddrBook::ResolveName. Typically, clients call the IAddrBook::SetSearchPath method to establish a container search path in the profile before they call GetSearchPath to retrieve it. However, calling SetSearchPath is optional.

If SetSearchPath has never been called, GetSearchPath builds a path by working through the address book's hierarchy tables. The default search path established by GetSearchPath is made up of the following containers in the following order:

The first container with read/write access, usually the personal address book (PAB).
Every container that has its PR_DISPLAY_TYPE property set to DT_GLOBAL. Such a setting indicates that the container holds recipients.
The container designated as the default, if there are no containers that have the DT_GLOBAL flag set in their PR_DISPLAY_TYPE property and the default container is not the same as the first container with read/write access.

If SetSearchPath has been called, GetSearchPath builds a path using the address book containers that have been stored in the profile. GetSearchPath validates this path before returning it to the caller.

After the first call to SetSearchPath, subsequent calls to SetSearchPath must be used to modify the search path returned by GetSearchPath. In other words, the calling client or provider does not receive the default search path after the first call to SetSearchPath.