MAPIAddress (VB)

The Visual Basic MAPIAddress function enables users to create or modify a set of recipients. MAPIAddress generates an address-book dialog box that shows the contents of the recipient set and allows the user to select new entries or change existing entries.

Quick Info

Header file:

MAPIVB32.BAS

MAPIAddress(

    Session as Long,
    UIParam as Long,
    Caption as String,
    EditFields as Long,
    Label as String,
    RecipCount as Long,
    Recipients() as MapiRecip,
    Flags as Long,
    Reserved as Long) as Long

Parameters

Session

[in] Session handle that represents a Simple MAPI session or zero. If the value of the Session parameter is zero, MAPI logs on the user and creates a session that exists only for the duration of the call. This temporary session can be an existing shared session or a new one. If necessary, a logon dialog box is displayed.

UIParam

[in] Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If no dialog box is displayed during the call, the UIParam parameter is ignored.

Caption

[in] Caption of the address-list dialog box. If this parameter is an empty string, the default value "Address Book" is used.

EditFields

[in] The number of edit controls that should be present in the address list. The values 0 through 4are valid. If the value of the nEditFields parameter is 4, each recipient class supported by the underlying messaging system has an edit control. If the value of EditFields is zero, only address list browsing is possible. Values of 1, 2, or 3 control the number of edit controls present.

However, if the number of recipient classes in the Recipients parameter is greater than the value of EditFields, the number of classes in Recipients is used to indicate the number of edit controls instead of the value of EditFields. If the value of EditFields is 1 and more than one kind of entry exists in Recipients, then the Labels parameter is ignored.

Entries selected for the different controls are differentiated by the ulRecipClass member in the returned recipient structure.

Label

[in] Edit control label in the address-list dialog box. The Label parameter is ignored and should be an empty string except when the value of the EditFields parameter is 1. If you want a default control label "To:", Label should be an empty string.

RecipCount

[in] The number of entries in the Recipients parameter. If the value of the RecipCount parameter is zero, Recipients is ignored.

Recipients

[in] The initial array of recipient entries to be used to populate edit controls in the address-list dialog box. Recipient entries need not be grouped by recipient class. If the value of the greatest recipient class present is greater than the value of the EditFields parameter, the EditFields and Label parameters are ignored. This array is redimensioned as necessary to accommodate the entries made by the user in the address-list dialog box.

Flags

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

MAPI_LOGON_UI: A dialog box should be displayed to prompt the user to log on if required. When the MAPI_LOGON_UI flag is not set, the client application does not display a logon dialog box and returns an error value if the user is not logged on.
MAPI_NEW_SESSION: An attempt should be made to create a new session rather than acquire the environment's shared session. If the MAPI_NEW_SESSION flag is not set, MAPIAddress uses an existing shared session.

Reserved

Reserved; must be zero.

Return Values

MAPI_E_FAILURE: One or more unspecified errors occurred while building recipient lists or browsing the address book. No list of recipients was returned.
MAPI_E_INSUFFICIENT_MEMORY: There was insufficient memory to proceed. No list of recipients was returned.
MAPI_E_INVALID_EDITFIELDS: The value of the nEditFields parameter was outside the range of 0 through 4. No list of recipients was returned.
MAPI_E_INVALID_RECIPS: One or more of the recipients in the address list was not valid or the Recipients parameter was not a valid array. No list of recipients was returned.
MAPI_E_INVALID_SESSION: An invalid session handle was used for the lhSession parameter. No list of recipients was returned.
MAPI_E_LOGIN_FAILURE: There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No list of recipients was returned.
MAPI_E_NOT_SUPPORTED: The operation was not supported by the underlying messaging system. A list of recipients might have been returned.
MAPI_E_USER_ABORT: The user canceled one of the dialog boxes. No list of recipients was returned.
SUCCESS_SUCCESS: The call succeeded and a list of address entries was returned.

Remarks

The MAPIAddress function makes it possible for users to create or modify a set of address-list entries using a standard address-list dialog box. The dialog box cannot be suppressed, but function parameters allow the caller to set characteristics of the dialog box.

The call is made with an initial, and possibly empty, set of recipients. The address-list dialog box shows the contents of the recipient set; users can choose new entries to add to the set. The final set of recipients is returned to the caller in the RecipCount and Recipients parameters, destroying their initial values.

The declaration of this function for the 32-bit Visual Basic runtime is:

MAPIAddress(

Session As Long,
UIParam As Long,
Caption As String,
nEditFields As Long,
Label As String,
nRecipients As Long,
Recips() As MapiRecip,
Flags As Long,
Reserved As Long) As Long