cmc_look

cmc_look_up

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

Quick Info

Header file:

XCMC.H

CMC_return_code cmc_look_up (
  CMC_session_id session,                 
  CMC_recipient FAR * recipient_in,       
  CMC_flags look_up_flags,                
  CMC_ui_id ui_id,                        
  CMC_uint32 FAR * count,                 
  CMC_recipient FAR * FAR * recipient_out,   
  CMC_extension FAR * look_up_extensions  
)

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_recipient 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_recipient 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_extension 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_free.

cmc_look_up

Quick Info

Parameters

Return Values

Remarks

See Also