ADRPARM 

The ADRPARM structure describes the display and behavior of the common address dialog box.

Quick Info

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;

Members

cbABContEntryID

Count of bytes in the entry identifier pointed to by lpABContEntryID.

lpABContEntryID

Pointer to the entry identifier of the container that initially supplies the list of recipient addresses that are displayed in the address dialog box.

ulFlags

Bitmask of flags associated with various address dialog box options. The following flags can be set:

AB_RESOLVE

Causes all names to be resolved after the address dialog box is closed. If there are ambiguous entries resulting from the name resolution process, a dialog box is displayed to prompt the user for help in resolving them.

AB_SELECTONLY

Disables the creation of one-off addresses and direct type-in entries for a recipient list. This flag is used only if the dialog box is modal, as indicated by the DIALOG_MODAL flag being set.

ADDRESS_ONE

The user can select exactly one recipient instead of multiple recipients from a list. This flag is valid only when cDestFields is zero and the dialog box is modal, as indicated by the DIALOG_MODAL flag being set.

DIALOG_MODAL

Causes the modal version of the common address dialog box to be displayed. Either this flag or DIALOG_SDI should be set; they cannot both be set.

DIALOG_OPTIONS

Causes the Send Options button to be displayed on the dialog box. This flag is used only if the dialog box is modal, as indicated by the DIALOG_MODAL flag being set.

DIALOG_SDI

Causes the modeless version of the common address dialog box to be displayed. Either this flag or DIALOG_MODAL should be set; they cannot both be set.

lpReserved

Reserved, must be zero.

ulHelpContext

Specifies the context within Help that will first be shown when the user clicks the Help button in the address dialog box.

lpszHelpFileName

Pointer to the name of a Help file that will be associated with the address dialog box. The lpszHelpFileName member is used in conjunction with ulHelpContext to call the Windows WinHelp function.

lpfnABSDI

Pointer to a MAPI function based on the ACCELERATEABSDI139ZRU3 prototype or NULL. This member applies to the modeless version of the dialog box only, as indicated by the DIALOG_SDI flag being set.

Clients building an ADRPARM structure to pass to IAddrBook::Address3K38VR 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 insure 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.

lpfnDismiss

Pointer to a function based on the DISMISSMODELESS_1EOI8 prototype or NULL. This member applies only to the modeless version of the dialog box only, as indicated by the DIALOG_SDI flag being set. MAPI calls the DISMISSMODELESS function when the user dismisses the modeless address dialog box, informing a client calling IAddrBook::Address that the dialog box is no longer active.

lpvDismissContext

Pointer to context information to be passed to the DISMISSMODELESS function pointed to by the lpfnDismiss member. This member applies only to the modeless version of the dialog box, as indicated by the DIALOG_SDI flag being set.

lpszCaption

Pointer to text to be used as the title for the common address dialog box.

lpszNewEntryTitle

Pointer to text to be used as the button label for the button that invokes either the New Entry dialog box or another dialog box.

lpszDestWellsTitle

Pointer to text to be used as a title for the recipient edit box controls that can appear in the modal version of the common address dialog box. This member is not used for modeless dialog boxes.

cDestFields

Count of recipient edit box controls in the modal version of the address dialog box, or zero if the dialog box is modeless. The address dialog box is open for browsing only when:

    The cDestFields member is set to zero.

    The DIALOG_BOX flag is set.

    The ADDRESS_ONE flag is not set.

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. 

nDestFieldFocus

Indicates the particular edit box control that should have the initial focus when the modal version of the dialog box appears. This value must be between 0 and the value of cDestFields minus 1.

lppszDestTitles

Pointer to an array of labels for buttons associated with each of the edit box controls that are displayed in the modal version of the address dialog box. The value of the cDestFields member indicates the number of labels included in the array. If the lppszDestTitles member is NULL, the Address method chooses default titles.

lpulDestComps

Pointer to an array of recipient type values, such as MAPI_TO, MAPI_CC, and MAPI_BCC, that is associated with each edit box control. The value of the CDestFields member indicates the number of recipient types included in the array. The values pointed to by lpulDestComps can be used to set the PR_RECIPIENT_TYPE1VRJ4HY property of each recipient. If the lpulDestComps member is NULL, the Address method chooses default recipient types.

lpContRestriction

Pointer to an SRestriction1TRSEKP structure that limits the type of address entries that can be displayed in the dialog box.

lpHierRestriction

Pointer to an SRestriction structure that limits the address book containers that can supply address entries to be displayed in the dialog box.

Remarks

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.

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_1EOI8 prototype. Another function, one that conforms to the ACCELERATEABSDI139ZRU3 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::Address3K38VR or when service providers call IMAPISupport::Address6P2ISS.

The following illustration shows the modeless address dialog box.

{bmc bm6.WMF}

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_TYPE1VRJ4HY property   such as MAPI_TO. The modal address dialog box can be displayed by either of the Address methods or when clients call IAddrBook::Details1PH5_L2 and service providers call IMAPISupport::Details16CSO1N.

The following illustration shows the modal address dialog box.

{bmc bm7.WMF}

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::NewEntry5LZOL5 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.

{bmc bm8.WMF}

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

See Also