cmc_look_up

The cmc_look_up function looks up addressing information in a directory provided by a specified service provider.

Quick Info

CMC_return_code cmc_look_up (

Parameters

session

[in] Opaque session handle that represents a MAPI session object that represents a session with a message service. If the session handle is invalid, the cmc_look_up function returns the cmc_e_invalid_session_id error value.

recipient_in

[in] Pointer to an array of CMC_recipientHLUJFI structures containing recipient data. The cmc_look_up function interprets the array depending on the flags that the client application has set using the look_up_flags parameter. Possible interpretations are as following:

    If the client application has set one of the flags for name resolution, cmc_look_up obtains the name to resolve from the name member of the first structure in the array. The function checks the corresponding name-type member to discover what resolution should be performed. The cmc_look_up function ignores all recipient structures except the first in the array.

    If the client application has set the CMC_LOOKUP_DETAILS_UI flag, the information in the array must resolve to only one recipient. If it does not, cmc_look_up returns Cmc_e_ambiguous_recipient. The cmc_look_up function ignores all recipient structures except the first in the array.

    If the client application has set the CMC_LOOKUP_ADDRESSING_UI flag, cmc_look_up displays the recipients specified in the recipient array in the address-list dialog box.

look_up_flags

[in] Bitmask of flags. The following flags can be set:

CMC_COUNTED_STRING_TYPE

The string type the calling application or provider uses for CMC interactions is a CMC_counted_string. If this flag is not set, the function treats all strings as null-terminated strings.

CMC_ERROR_UI_ALLOWED

Displays a dialog box on encountering recoverable errors. If this flag is not set, cmc_look_up does not display a dialog box and returns an error value instead.

CMC_LOGON_UI_ALLOWED

Displays a dialog box to prompt for logon if required. If this flag is not set, cmc_look_up does not display a dialog box and returns an error value if the user does not supply enough information.

CMC_LOOKUP_ADDRESSING_UI

Displays a dialog box to allow creation of a recipient list for addressing a message and general directory browsing. The recipient list passed to the function is the original recipient list for the dialog box. The function returns the list of recipients created by the user. This flag is optional for implementations to support.

CMC_LOOKUP_DETAILS_UI

Displays a details dialog box for the recipient pointed to in the recipient_in parameter. This dialog box only acts on the first recipient in the list. If the recipient name indicated resolves to more than one address, cmc_look_up does not display the details dialog box and returns cmc_e_ambiguous_recipient.

CMC_LOOKUP_RESOLVE_IDENTITY

Returns a recipient record for the identity of the current user of the message service. If no unique identity can be determined, the implementation carries out ambiguous name resolution to determine the address of the current user.

CMC_LOOKUP_RESOLVE_PREFIX_SEARCH

The search method should be by prefix. In a prefix search, all names matching the prefix string, beginning at the first character of the name, are considered matches. If this flag is not set, the search method should be exact-match. CMC implementations must support simple prefix searching. The availability of wildcard or substring searches is optional.

CMC_LOOKUP_RESOLVE_UI

Attempts to resolve ambiguous names by presenting a name-resolution dialog box to the user. If this flag is not set, resolutions that do not result in a single name return the error value CMC_E_AMBIGUOUS_RECIPIENT for message services that require names to resolve to a single address. Message services that can return multiple addresses can return a list of addresses if the count parameter is non-null. The name_type field in the recipient_out parameter can also be set on input as a hint to aid in resolution of the name. Some CMC implementations might not support this flag. The CMC_LOOKUP_RESOLVE_UI flag is set only when the CMC_LOOKUP_RESOLVE_PREFIX_SEARCH flag is also set.

ui_id

[in] Handle of a dialog box for cmc_look_up to present to help resolve processing questions.

count

[in or out] Contains a maximum name count. On input, this parameter specifies a pointer to the maximum number of names for which cmc_look_up can find addressing information. A value of zero indicates no maximum.

On output, the count parameter specifies the location to which cmc_look_up writes the number of names that it actually writes to the location indicated by the recipient_out parameter. If no names are written, cmc_look_up writes zero to the count parameter.

recipient_out

[out] Pointer to the location to which cmc_look_up writes an array of one or more CMC_recipientHLUJFI structures containing addressing details for the recipients in the array passed in the recipient_in parameter.

look_up_extensions

[in, out] Pointer to an array of CMC_extensionWY87UR structures specifying function extensions. On input, this array contains MAPI extensions to the standard cmc_look_up function. A value of NULL for the look_up_extensions parameter indicates that the client application has no extensions for cmc_look_up and is expecting no extensions.

On output, cmc_look_up writes to the array new information about the lookup operation. It writes NULL if it generates no output extensions.

Return Values

CMC_E_AMBIGUOUS_RECIPIENT

The recipient name was ambiguous. Multiple matches were found.

CMC_E_FAILURE

There was a general failure that does not fit the description of any other return value.

CMC_E_INSUFFICIENT_MEMORY

Insufficient memory was available to complete the requested operation.

CMC_E_INVALID_FLAG

A flag set using a flags parameter was invalid.

CMC_E_INVALID_PARAMETER

A function parameter was invalid.

CMC_E_INVALID_SESSION_ID

The specified session handle is invalid or no longer valid (for example, after logging off).

CMC_E_INVALID_UI_ID

The specified user-interface identifier is invalid or no longer valid.

CMC_E_LOGON_FAILURE

The service, user name, or password specified was invalid, so logon cannot be completed.

CMC_E_NOT_SUPPORTED

The current implementation does not support the operation requested.

CMC_E_RECIPIENT_NOT_FOUND

One or more of the specified recipients were not found.

CMC_E_UNSUPPORTED_DATA_EXT

The current implementation does not support the data extension requested.

CMC_E_UNSUPPORTED_FLAG

The current implementation does not support the flag requested.

CMC_E_UNSUPPORTED_FUNCTION_EXT

The current implementation does not support the function extension requested.

CMC_E_USER_CANCEL

The operation was canceled by the user.

CMC_E_USER_NOT_LOGGED_ON

The user was not logged on and the CMC_LOGON_UI_ALLOWED flag was not set.

Remarks

A client application calls the cmc_look_up function to resolve a display name to a messaging address or to prompt the user to choose among multiple resolved names. A client can also use this function to display a dialog box for creation of recipient lists or to display recipient details.

The cmc_look_up function can write multiple addresses. Before it writes addressing information, it must allocate memory for the structure array to contain the information. When this memory is no longer needed, the client application should free the entire array with a call to cmc_free1RMW6IO.

See Also