MAPIAddress

Syntax

MAPIAddress(Session, UIParam, Caption$, EditFields, Label$, Flags, Reserved)

Remarks

Addresses a mail message. With this function, users can create a set of address list entries using the Mail Address Book, a standard address list dialog box. The dialog box cannot be suppressed, but function arguments allow the caller to set characteristics of the dialog box.

The call is made with the recipient list of the current outbound message, which can be empty. Users can add new entries to the set. MAPIAddress returns a handle to a recipient list. Use MAPIQueryRecipientList to retrieve names, addresses, or recipient classes from the recipient list. Use MAPISetRecipient
to copy recipients to the current outbound message.

In addition to choosing names from the Address Book list, users can type names in the Address Book fields. Use MAPIResolveName to resolve these names before sending the message.

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.

Caption$

The caption of the Address Book dialog box.

EditFields

The number of edit controls that should be present in the address list. The values 0 (zero) to 4 are valid. If EditFields is 0 (zero), only address list browsing is allowed. EditFields values of 1 to 3 control the number of edit controls present. Entries selected for the different controls are differentiated by the RecipClass field of the returned recipient list. If EditFields is 4, each recipient class supported by the underlying messaging system has an edit control.

Label$

A string used as an edit control label in the address list dialog
box. This argument is ignored and should be an empty string ("") except when EditFields is 1. An ampersand (&) in the Label$ argument marks the following character as the access key for
the field.

If you want the label to be the default control label "To:", Label$ should be an empty string ("").

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

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. If the session passed in Session is not 0 (zero), this flag is ignored.

Set MAPI_NEW_SESSION to establish a session other than the current one. For instance, if the Mail client application is already running, another MAPI application 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.

Reserved

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


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

Value

Name

Meaning

Positive integer

A handle to a recipient list. MAPIAddress was successful.

–2

MAPI_E_FAILURE

One or more unspecified errors occurred while addressing the mail. No list of entries was returned.

–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. No list of entries was returned.

–5

MAPI_E_INSUFFICIENT_MEMORY

There was insufficient memory to proceed. No list of entries was returned.

–17

MAPI_E_INVALID_MESSAGE

An invalid message ID was used for the MessageID$ argument. No list of entries was returned.

–19

MAPI_E_INVALID_SESSION

An invalid session handle was used for the Session argument. No list of entries was returned.

–24

MAPI_E_INVALID_EDITFIELDS

The value of EditFields was outside the range of 0 (zero) to 4. No list of entries was returned.

–25

MAPI_E_INVALID_RECIPIENTS

One or more of the recipients in the address list were not valid. No list of entries was returned.

–26

MAPI_E_NOT_SUPPORTED

The operation was not supported by the underlying messaging system.

–1

MAPI_USER_ABORT

The user canceled the process. No list of entries was returned.


Example

The following example displays the Address Book dialog box with one edit field. The dialog box title is "Submit Report" and the edit field label is "Manager:". Users can press ALT+M to access the edit field.


Sub MAIN
MAPI_LOGON_UI = 1
Session = MAPILogon(0, "", "", MAPI_LOGON_UI, 0)
RecipList = MAPIAddress(Session, 0, "Submit Report", 1, "&Manager:",\
         0, 0)
result = MAPILogoff(Session, 0, 0, 0)
End Sub