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:

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 Windows NT services, see the Win32® Web page Using MAPI from a Windows NT Service at http://www.microsoft.com/win32dev/mapi/mapiserv.htm. For more information on running as a service, see "Windows NT Service Client Applications" in the MAPI Programmer's Reference.

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