MAPIResolveName

Syntax

MAPIResolveName(Session, UIParam, RecipName$, Address$, Flags, Reserved)

Remarks

Displays a dialog box to resolve an ambiguous recipient name. This function resolves a mail recipient's name (as entered by a user) to an unambiguous address list entry. MAPIResolveName prompts the user to choose between ambiguous entries, if necessary. A recipient list containing fully resolved information about the entry is allocated and returned.

Some RecipName$ strings cannot be resolved. Some strings may produce too many matches or no matches at all, or the user can cancel the Resolve Name dialog box.

MAPIResolveName returns a handle to a recipient list.

Argument

Explanation

Session

An opaque session handle whose value represents a session with the messaging system. The session handle is returned by MAPILogon and invalidated by MAPILogoff. If the value is 0 (zero), the messaging system initiates a session from a system default session
(if one exists) or presents a log-in dialog box. In all cases, the messaging system returns to its state before the call.

UIParam

The parent window handle for the dialog box. A value of 0 (zero) specifies that any dialog box displayed is application modal.

RecipName$

A string containing the name to be resolved.


Argument

Explanation

Address$

Provider-specific Mail address of the recipient.

Flags

A bitmask of flags. Unspecified flags should always be set to
0 (zero). Undocumented flags are reserved. The following flags
are defined:

MAPI_LOGON_UI = 1
MAPI_NEW_SESSION = 2
MAPI_DIALOG = 8
MAPI_AB_NOMODIFY = 1024

Set MAPI_LOGON_UI if the function should display a log-in dialog box (if required). When this flag is not set, the function does not display a dialog box and returns an error if the user is not logged in.

Set MAPI_NEW_SESSION if you want to establish a session other than the current one. For instance, if a mail client is already running, another MAPI e-mail client can piggyback on the session created by the mail client application. Do not set this flag if you want the default session (if it still exists). If the session passed in Session is not 0 (zero), this flag is ignored.

Set MAPI_DIALOG if MAPIResolveName should attempt to resolve names by displaying a name resolution dialog box to the user. If this flag is not set, resolutions which do not result in a single name return MAPI_E_AMBIGUOUS_RECIPIENT.

Set MAPI_AB_NOMODIFY if the details of the entry should not be modifiable even if the entry belongs to the personal address book. Part of the resolution dialog box could involve displaying details about the various entries that match the RecipName$ argument. Set this flag if these details should not be modifiable. This flag is ignored if MAPI_DIALOG is not set.

Reserved

Reserved for future use. This argument must be 0 (zero).


The following table lists the possible return values of the MAPIResolveName function and their meanings.

Value

Name

Meaning

–21

MAPI_E_AMBIGUOUS_RECIPIENT

One or more recipients were specified ambiguously. The name was not resolved.

–2

MAPI_E_FAILURE

One or more unspecified errors occurred while addressing the mail. The name was not resolved.


Value

Name

Meaning

–5

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory
to proceed. The name was not resolved.

–3

MAPI_E_LOGIN_FAILURE

There was no default log-in,
and the user failed to log in successfully when the log-in dialog box was displayed. The name was not resolved.

–26

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

–1

MAPI_USER_ABORT

The user canceled the process. The name was not resolved.

Positive integer

A handle to a recipient list.


Example

The following example resolves a name.


Sub MAIN
MAPI_LOGON_UI = 1
MAPI_DIALOG = 8
Session = MAPILogon(0, "", "", MAPI_LOGON_UI, 0)
RecipName$ = "carlos"
Address$ = ""
ResolveList = MAPIResolveName(Session, 0, RecipName$, Address$,\
    MAPI_DIALOG, 0)
If ResolveList > 0 Then MsgBox Address$
result = MAPILogoff(Session, 0, 0, 0)
End Sub