| Platform SDK: MAPI |
The ADRPARM structure describes the display and behavior of the common address dialog box.
| Header file: | MAPIDEFS.H |
typedef struct _ADRPARM
{
ULONG cbABContEntryID;
LPENTRYID lpABContEntryID;
ULONG ulFlags;
LPVOID lpReserved;
ULONG ulHelpContext;
LPTSTR lpszHelpFileName;
LPFNABSDI lpfnABSDI;
LPFNDISMISS lpfnDismiss;
LPVOID lpvDismissContext;
LPTSTR lpszCaption;
LPTSTR lpszNewEntryTitle;
LPTSTR lpszDestWellsTitle;
ULONG cDestFields;
ULONG nDestFieldFocus;
LPTSTR FAR *lppszDestTitles;
ULONG FAR *lpulDestComps;
LPSRestriction lpContRestriction;
LPSRestriction lpHierRestriction;
} ADRPARM, FAR *LPADRPARM;
Clients building an ADRPARM structure to pass to IAddrBook::Address must always set the lpfnABSDI member to NULL. If the DIALOG_SDI flag is set, MAPI will then set it to a valid function before returning. Clients call this function from within their message loop to ensure that accelerators in the address book dialog box work. When the dialog box is dismissed and MAPI calls the function pointed to by the lpfnDismiss member, clients should unhook the ACCELERATEABSDI function from their message loop.
Setting cDestFields to 0XFFFFFFFF implies that MAPI should create the default number of recipient edit box controls. In this case, the lppszDestTitles and lpulDestComps members must be NULL.
ADRPARM structures are used by clients and service providers to control the appearance and behavior of the MAPI common address dialog boxes. There are two varieties of the address dialog box: modeless and modal. Some of the members in the ADRPARM structure apply to both versions of the dialog box, but some only apply to one of the two versions. The following table relates the members of an ADRPARM structure to their use with the common address dialog boxes.
| ADRPARM member | Type of dialog box |
|---|---|
| cbABContEntryID and lpABContEntryID | Modal and modeless |
| ulFlags | Modal and modeless |
| lpReserved | Modal and modeless |
| ulHelpContext and lpszHelpFileName | Modal and modeless |
| lpfnABSDI | Modeless |
| lpfnDismiss and lpvDismissContext | Modeless |
| lpszCaption | Modal and modeless |
| lpszNewEntryTitle | Modal |
| lpszDestWellsTitle, cDestFields, nDestFieldFocus, lppszDestTitles, and lpulDestComps | Modal |
| lpContRestriction | Modal and modeless |
| lpHierRestriction | Modal and modeless |
The modeless dialog box is a read-only display of entries from one or more address book containers. The dialog box can display all entries from the selected containers or be limited to only those entries and containers that match criteria established by a restriction. The contents restriction pointed to by lpContRestriction can limit the types of entries displayed and the hierarchy restriction pointed to by lpHierRestriction can limit the containers providing the entries. To inform the caller when the dialog box has been dismissed, MAPI invokes a function provided by the caller that conforms to the DISMISSMODELESS prototype. Another function, one that conforms to the ACCELERATEABSDI prototype, is provided by MAPI and invoked by the caller in the Windows message loop to facilitate the working of accelerator keys. The modeless version of the MAPI address dialog box can be displayed when clients call IAddrBook::Address or when service providers call IMAPISupport::Address.
The following illustration shows the modeless address dialog box.
The modal dialog box is a read/write display of entries from one or more containers. Its contents can be affected in the same way as can the modeless version — by restrictions set in the lpContRestriction and lpHierRestriction members. In addition to the list box displaying container entries, the modal dialog box can contain between one and three edit box controls for holding entries selected by the user. Each edit control is associated with a particular recipient type — or PR_RECIPIENT_TYPE property — such as MAPI_TO. The modal address dialog box can be displayed by either of the Address methods or when clients call IAddrBook::Details and service providers call IMAPISupport::Details.
The following illustration shows the modal address dialog box.
This illustration includes two edit box controls because the cDestFields member of the ADRPARM structure controlling the display of this dialog box is set to 2. The first control has initial focus because the nDestFieldFocus member is set to 0.
The lpszNewEntryTitle member points to text for a button label that, when selected, causes an additional dialog box to be displayed. Typically, as is shown in the illustration of the modal dialog box, the button is labeled New and the dialog box that is displayed lists all of the types of addresses that can be created by any of the address book providers in the profile. Clients cause this New Entry dialog box to be displayed by calling IAddrBook::NewEntry and passing zero for the cbEidNewEntryTpl parameter and NULL for the lpEidNewEntryTpl parameter when the user selects the button. The information included in this dialog box comes from the MAPI one-off table.
The following illustration shows the appearance of the New Entry dialog box.
Every entry in this dialog box is associated with a template for entering the data required to create an address of the particular type. Most address book providers supply one template for every type of address entry they can create. When a user makes a selection from this dialog box, MAPI displays the corresponding template.
The most significant four bits of the ADRPARM structure's ulFlags member contain a version number identifying the version of the ADRPARM structure. The current version is 0 (zero) — or ADRPARM_HELP_CTX. The current implementation of MAPI will fail for any version of the structure other than zero.
Future versions of the structure may be completely different; they may or may not support the version-zero structure. The following macros are provided for extracting the version number from the ulFlags member and for combining it with the defined flags:
GET_ADRPARM_VERSION(ulFlags)
SET_ADRPARM_VERSION(ulFlags, ulVersion)
ADRPARM_HELP_CTX
Address Structures, ACCELERATEABSDI, DISMISSMODELESS, IAddrBook::Address, IMAPISupport::Address, SRestriction