The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

MAPIAddress function

[The use of this function is discouraged. It may be altered or unavailable in subsequent versions of Windows.]

The MAPIAddress function creates or modifies a set of address list entries.


  _In_  LHANDLE         lhSession,
  _In_  ULONG_PTR       ulUIParam,
  _In_  LPSTR           lpszCaption,
  _In_  ULONG           nEditFields,
  _In_  LPSTR           lpszLabels,
  _In_  ULONG           nRecips,
  _In_  lpMapiRecipDesc lpRecips,
  _In_  FLAGS           flFlags,
        ULONG           ulReserved,
  _Out_ LPULONG         lpnNewRecips,
  _Out_ lpMapiRecipDesc *lppNewRecips


lhSession [in]

Session handle that represents a Simple MAPI session or zero. If the value of the lhSession 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.

ulUIParam [in]

Parent window handle or zero, indicating that if a dialog box is displayed, it is application modal. If the ulUIParam parameter contains a parent window handle, it is of type HWND (cast to a ULONG_PTR). If no dialog box is displayed during the call, ulUIParam is ignored.

lpszCaption [in]

Pointer to the caption for the address list dialog box, NULL, or an empty string. When the lpszCaption parameter is NULL or points to an empty string, MAPIAddress uses the default caption "Address Book."

nEditFields [in]

The number of edit controls that should be present in the address list. The values 0 through 4 are 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 nEditFields 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 array pointed to by the lpRecips parameter is greater than the value of nEditFields, the number of classes in lpRecips is used to indicate the number of edit controls instead of the value of nEditFields. If the value of nEditFields is 1 and more than one kind of entry exists in lpRecips, then the lpszLabels parameter is ignored. Entries selected for the different controls are differentiated by the ulRecipClass member in the returned recipient structure.

lpszLabels [in]

Pointer to a string to be used as an edit control label in the address-list dialog box. When the nEditFields parameter is set to any value other than 1, the lpszLabels parameter is ignored and should be NULL or point to an empty string. Also, if the caller requires the default control label "To," lpszLabels should be NULL or point to an empty string.

nRecips [in]

The number of entries in the array indicated by the lpRecips parameter. If the value of the nRecips parameter is zero, lpRecips is ignored.

lpRecips [in]

Pointer to an array of MapiRecipDesc structures defining the initial recipient entries to be used to populate the address-list dialog box. The entries do not need to be grouped by recipient class; they are differentiated by the values of the ulRecipClass members of the MapiRecipDesc structures in the array. If the number of different recipient classes is greater than the value indicated by the nEditFields parameter, the nEditFields and lpszLabels parameters are ignored.

flFlags [in]

Bitmask of option flags. The following flags can be set.


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.


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; must be zero.

lpnNewRecips [out]

Pointer to the number of entries in the lppNewRecips recipient output array. If the value of the lpnNewRecips parameter is zero, the lppNewRecips parameter is ignored.

lppNewRecips [out]

Pointer to an array of MapiRecipDesc structures containing the final list of recipients. This array is allocated by MAPIAddress, cannot be NULL, and must be freed using MAPIFreeBuffer, even if there are no new recipients. Recipients are grouped by recipient class in the following order: MAPI_TO, MAPI_CC, MAPI_BCC.

Return value

This function returns one of the following values.

Return codeDescription

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


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


The value of the nEditFields parameter was outside the range of 0 through 4. No list of recipient entries was returned.


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


An invalid session handle was used for the lhSession parameter. No list of recipient entries was returned.


There was no default logon, and the user failed to log on successfully when the logon dialog box was displayed. No list of recipient entries was returned.


The operation was not supported by the underlying messaging system.


The user canceled one of the dialog boxes. No list of recipient entries was returned.


The call succeeded and a list of recipient entries was returned.



The MAPIAddress function displays a standard address-list dialog box to show an initial set of zero or more recipients. The user can choose new entries to add to the set or make changes to existing entries. This dialog box cannot be suppressed, but the caller can set dialog box characteristics. The changed set of recipients is returned to the caller.

Before MAPIAddress writes new or changed recipient information, it must allocate memory for the structure array that will contain the information. Memory is also allocated as part of preloading the address book, regardless of whether new or changed recipient data is written. Client applications must call the MAPIFreeBuffer function to free this memory after MAPIAddress returns. If any error occurs, no memory was allocated and clients do not need to call MAPIFreeBuffer.






See also

Simple MAPI



Community Additions