AddressBook Method (Session Object)

The AddressBook method displays a modal dialog box that allows the user to select entries from the address book. The selections are returned in a Recipients collection object.

Syntax

Set objRecipients = objSession.AddressBook( [recipients] [, title] [, oneAddress] [, forceResolution] [, recipLists] [, toLabel] [, ccLabel] [, bccLabel] [, parentWindow ] )

objRecipients

On successful return, the Recipients collection object. When the user does not select any names from the dialog box, AddressBook returns Nothing.

objSession

Required. The Session object.

recipients

Optional. Object. A Recipients collection object that provides initial values for the recipient list boxes in the address book dialog box. During the dialog, the user can select recipients from this collection and add other recipients.

title

Optional. String. The title or caption of the address book dialog box. The default value is an empty string.

oneAddress

Optional. Boolean. Allows the user to enter or select only one address entry at a time. The default value is False.

forceResolution

Optional. Boolean. If True, attempts to resolve all names before closing the address book. Prompts the user to resolve any ambiguous names. The default value is True.

recipLists

Optional. Long. The number of recipient list boxes to display in the address book dialog box:

recipLists setting	Action
–1	Displays three list boxes with default captions and without resolution, that is, acts as a shortcut for forceResolution=False, recipLists=3 with no setting of toLabel, ccLabel, or bccLabel.
0	Displays no list boxes. The user can interact with the address book dialog box but no recipients are returned by this method.
1	Displays one list box for CdoTo recipients (default).
2	Displays two list boxes for CdoTo and CdoCc recipients.
3	Displays three list boxes for CdoTo, CdoCc, and CdoBcc recipients.

toLabel

Optional. String. The caption for the button associated with the first recipient list box. Ignored if recipLists is less than 1. If omitted, the default value “To:” is displayed.

ccLabel

Optional. String. The caption for the button associated with the second recipient list box. Ignored if recipLists is less than 2. If omitted, the default value “Cc:” is displayed.

bccLabel

Optional. String. The caption for the button associated with the third recipient list box. Ignored if recipLists is less than 3. If omitted, the default value “Bcc:” is displayed.

parentWindow

Optional. Long. The parent window handle for the address book dialog box. A value of zero (the default) specifies that the dialog box should be application-modal.

Remarks

The AddressBook method returns CdoE_USER_CANCEL if the user cancels the dialog box.

The recipients parameter provides initial values for the recipient list boxes. These values expedite the user’s recipient selection process. A common use of this parameter is to set it to the Recipients collection of a message to which you are generating a reply.

When you use AddressBook to let the user select recipients for a new message, you use either two or three different Recipients collections, depending on whether you furnish the recipients parameter. Use the following procedure:

1. Optionally, prepare an initial Recipients collection to be submitted in the recipients parameter to the AddressBook method.
2. Call AddressBook, which returns the user-selected Recipients collection.
3. Call the Add method on a Messages collection to create a new message.
4. Copy the Recipients collection returned by AddressBook to the Recipients property of the new message:

    Set objNewMessage.Recipients = objRecipients 
    objNewMessage.Recipients.Resolve ' also updates everything 
 

The oneAddress parameter indicates whether only one address entry at a time can be selected before being added to the recipients list. If oneAddress is set to False, the user can select multiple recipients by using the CTRL or SHIFT key during the selection. If oneAddress is set to True, multiple selection is disabled.

To provide an access key for the recipient list boxes, include an ampersand (&) character in the label argument string, immediately before the character that serves as the access key. For example, if toLabel is “Local &Attendees:”, users can press ALT+A to move the focus to the first recipient list box.

The address book dialog box is always modal, meaning the parent window is disabled while the dialog box is active. If the parentWindow parameter is set to zero or is not set, all windows belonging to the application are disabled while the dialog box is active. If the parentWindow parameter is supplied but is not valid, the call returns CdoE_INVALID_PARAMETER.

The following methods can invoke dialog boxes:

• Details method (AddressEntry object)
• Options and Send methods (Message object)
• Resolve method (Recipient object)
• Resolve method (Recipients collection)
• AddressBook and Logon methods (Session object)

However, if your application is running as a Microsoft® Windows NT® service, for example from Active Server Pages (ASP) script on a Microsoft® Internet Information Server (IIS), no user interface is allowed.

For more information on running as a service, see "Windows NT Service Client Applications" in the MAPI Programmer's Reference under Guide, Introduction to MAPI Programming, Operating Environment Issues.

Example

This code fragment displays an address book dialog box labeled “Select Attendees” with three recipient lists:

If objSession Is Nothing Then 
    MsgBox "Must first create MAPI session and log on" 
    Exit Function 
End If 
Set objRecipColl = objSession.AddressBook( _ 
                      Title:="Select Attendees", _ 
                      forceResolution:=True, _ 
                      recipLists:=3, _ 
                      toLabel:="&Very Important People", _ ' on button 
                      ccLabel:="&Fairly Important People", _ 
                      bccLabel:="&Secret Important People") 
' "recipients:=" parameter not used in preceding call 
MsgBox "Name of first recipient = " & objRecipColl.Item(1).Name 
' could be objRecipColl(1) since Item and Name are default properties 
Exit Function