IAddrBook Interface

IID_IAddrBook

{00020309-0000-0000-C000-000000000046}

This interface supports access to the Microsoft Windows Address Book (WAB) and includes operations such as displaying common dialog boxes, opening containers, messaging users (contacts) and distribution lists (groups) in the address book, and performing name resolution.

Note The implementation of IMAPIProp::GetLastError for IAddrBook supports Unicode on Windows NT platforms only. The implementations of GetLastError for Windows 95 platforms and 16-bit platforms do not support Unicode.

The IAddrBook interface Inherits from IMAPIProp.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IMAPIProp Methods

Description

GetLastError

Not currently implemented.

SaveChanges

Not currently implemented.

GetProps

Not currently implemented.

GetPropList

Not currently implemented.

OpenProperty

Not currently implemented.

SetProps

Not currently implemented.

DeleteProps

Not currently implemented.

CopyTo

Not currently implemented.

CopyProps

Not currently implemented.

GetNamesFromIDs

Not currently implemented.

GetIDsFromNames

Not currently implemented.

IAddrBook Methods

Description

OpenEntry

Opens a container or mail user object and returns a pointer to the object.

CompareEntryIDs

Compares two entry identifiers.

Advise

Registers the caller with the WAB to receive notifications.

Unadvise

Unregisters the caller from the WAB for notifications.

CreateOneOff

Creates an entry identifier for a one-off address.

NewEntry

Displays a blank dialog box that enables the user to create a new entry.

ResolveName

Resolves a partial recipient list to full addresses.

Address

Displays the common address book dialog box.

Details

Displays a dialog box that shows details, and allows editing, of a particular entry in the WAB.

RecipOptions

Not currently implemented.

QueryDefaultRecipOpt

Not currently implemented.

GetPAB

Returns the entry identifier of the default WAB container.

SetPAB

Not currently implemented.

GetDefaultDir

Not currently implemented.

SetDefaultDir

Not currently implemented.

GetSearchPath

Returns an ordered list of the entry identifiers of containers to be included in the name resolution process initiated by the IAddrBook::ResolveName method.

SetSearchPath

Not currently implemented.

PrepareRecips

Prepares a recipient list for later use by the messaging system.

OpenEntry

FUNCTION IAddrBook_OpenEntry ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL cbEntryID AS DWORD _
, BYVAL lpEntryID AS ENTRYID PTR _
, BYREF lpInterface AS GUID _
, BYVAL ulFlags AS DWORD _
, BYREF lpulObjType AS DWORD _
, BYREF lppUnk AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[14] USING IAddrBook_OpenEntry (pIAddrBook, cbEntryID, lpEntryID, lpInterface, ulFlags, lpulObjType, lppUnk) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

CompareEntryIDs

FUNCTION IAddrBook_CompareEntryIDs ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL cbEntryID1 AS DWORD _
, BYVAL lpEntryID1 AS ENTRYID PTR _
, BYVAL cbEntryID2 AS DWORD _
, BYVAL lpEntryID2 AS ENTRYID PTR _
, BYVAL ulFlags AS DWORD _
, BYREF lpulResult AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[15] USING IAddrBook_CompareEntryIDs (pIAddrBook, cbEntryID1, lpEntryID1, cbEntryID2, lpEntryID2, ulFlags, lpulResult) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Advise

FUNCTION IAddrBook_Advise ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL cbEntryID AS DWORD _
, BYVAL lpEntryID AS ENTRYID PTR _
, BYVAL ulEventMask AS DWORD _
, BYVAL lpAdviseSink AS DWORD _
, BYREF lpulConnection AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[16] USING IAddrBook_Advise (pIAddrBook, cbEntryID, lpEntryID, ulEventMask, lpAdviseSink, lpulConnection) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Unadvise

FUNCTION IAddrBook_Unadvise ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL ulConnection AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[17] USING IAddrBook_Unadvise (pIAddrBook, ulConnection) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION
 

CreateOneOff

FUNCTION IAddrBook_CreateOneOff ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYREF lpszName AS ASCIIZ _
, BYREF lpszAdrType AS ASCIIZ _
, BYREF lpszAddress AS ASCIIZ _
, BYVAL ulFlags AS DWORD _
, BYREF lpcbEntryID AS DWORD _
, BYREF lppEntryID AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[18] USING IAddrBook_CreateOneOff (pIAddrBook, lpszName, lpszAdrType, lpszAddress, ulFlags, lpcbEntryID, lppEntryID) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Note: The use of the CreateOneOff method with the PowerBASIC compilers is problematic because it requires the use of an ENTRYID structure that has a variable-length byte array as one of his members, and PowerBASIC doesn't support structures with variable-length arrays. A workaround is not to use this function to make a one-off entry identifier, but to do it manually.

The one-off entry identifier uses a specific format, defined as follows.

$MAPI_ONE_OFF_UID = GUID$("{812b1fa4-bea3-1019-9d6e-00dd010f5402}")
%MAPI_ONE_OFF_UNICODE = &H8000??
%MAPI_ONE_OFF_NO_RICH_INFO = &H0001??
 

LOCAL strDisplayName AS STRING

LOCAL strAdrType AS STRING

LOCAL strEmailAddress AS STRING

LOCAL strNul AS STRING

strDisplayName = "José Roca"

IF %fMapiUnicode THEN strDisplayName = UCODE$(strDisplayName)

strAdrType = "SMTP"

IF %fMapiUnicode THEN strAdrType = UCODE$(strAdrType)

strEmailAddress = "JRoca@com.it-berater.org"

IF %fMapiUnicode THEN strEmailAddress = UCODE$(strEmailAddress)

strNul = $NUL
IF %fMapiUnicode THEN strNul = UCODE$(strNul)
strEntryID = $MAPI_ONE_OFF_UID & MKDWD$(0) & MKDWD$(%MAPI_SEND_NO_RICH_INFO) & _
             strDisplayName & strNul & strAdrType & strNul & strEmailAddress & strNul
lppEntryID = VARPTR(strEntryID)
cbEntryID = LEN(strEntryID)

Please note that although the version and flag fields are defined as 16-bit words in Intel byte order, we have to convert them to DWORDs when used in 32-bit OSes. The display name, address type and email address are null terminated strings (ASCIIZ), but we have to use dynamic strings (with a nul character added at the end) if we want to use Unicode.

NewEntry

FUNCTION IAddrBook_NewEntry ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL ulUIParam AS DWORD _
, BYVAL ulFlags AS DWORD _
, BYVAL cbEIDContainer AS DWORD _
, BYVAL lpEIDContainer AS DWORD _
, BYVAL cbEIDNewEntryTpl AS DWORD _
, BYVAL lpEIDNewEntryTpl AS DWORD _
, BYREF lpcbEIDNewEntry AS DWORD _
, BYREF lppEIDNewEntry AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[19] USING IAddrBook_NewEntry (pIAddrBook, ulUIParam, ulFlags, cbEIDContainer, lpEIDContainer, cbEIDNewEntryTpl, lpEIDNewEntryTpl, lpcbEIDNewEntry, lppEIDNewEntry) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

ResolveName

FUNCTION IAddrBook_ResolveName ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL ulUIParam AS DWORD _
, BYVAL ulFlags AS DWORD _
, BYVAL lpszNewEntryTitle AS DWORD _
, BYVAL lpAdrList AS ADRLIST PTR _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[20] USING IAddrBook_ResolveName (pIAddrBook, ulUIParam, ulFlags, lpszNewEntryTitle, lpAdrList) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Address

FUNCTION IAddrBook_Address ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYREF lpulUIParam AS DWORD _
, BYREF lpAdrParms AS ADRPARM _
, BYVAL lppAdrList AS ADRLIST PTR _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[21] USING IAddrBook_Address (pIAddrBook, lpulUIParam, lpAdrParms, lppAdrList) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

Details

FUNCTION IAddrBook_Details ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYREF lpulUIParam AS DWORD _
, BYVAL lpfnDismiss AS DWORD _
, BYVAL lpvDismissContext AS DWORD _
, BYVAL cbEntryID AS DWORD _
, BYVAL lpEntryID AS ENTRYID PTR _
, BYVAL lpfButtonCallback AS DWORD _
, BYVAL lpvButtonContext AS DWORD _
, BYVAL lpszButtonText AS DWORD _
, BYVAL ulFlags AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[22] USING IAddrBook_Details (pIAddrBook, lpulUIParam, lpfnDismiss, lpvDismissContext, cbEntryID, lpEntryID, lpfButtonCallback, lpvButtonContext, lpszButtonText, ulFlags) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

RecipOptions

FUNCTION IAddrBook_RecipOptions ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL ulUIParam AS DWORD _
, BYVAL ulFlags AS DWORD _
, BYVAL lpRecip AS ADRENTRY PTR _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[23] USING IAddrBook_RecipOptions (pIAddrBook, ulUIParam, ulFlags, lpRecip) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

QueryDefaultRecipOpt

FUNCTION IAddrBook_QueryDefaultRecipOpt ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYREF lpszAdrType AS ASCIIZ _
, BYVAL ulFlags AS DWORD _
, BYREF lpcValues AS DWORD _
, BYREF lppOptions AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[24] USING IAddrBook_QueryDefaultRecipOpt (pIAddrBook, lpszAdrType, ulFlags, lpcValues, lppOptions) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetPAB

FUNCTION IAddrBook_GetPAB ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYREF lpcbEntryID AS DWORD _
, BYREF lppEntryID AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[25] USING IAddrBook_GetPAB (pIAddrBook, lpcbEntryID, lppEntryID) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetPAB

FUNCTION IAddrBook_SetPAB ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL cbEntryID AS DWORD _
, BYVAL lpEntryID AS ENTRYID PTR _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[26] USING IAddrBook_SetPAB (pIAddrBook, cbEntryID, lpEntryID) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetDefaultDir

FUNCTION IAddrBook_GetDefaultDir ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYREF lpcbEntryID AS DWORD _
, BYREF lppEntryID AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[27] USING IAddrBook_GetDefaultDir (pIAddrBook, lpcbEntryID, lppEntryID) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

GetSearchPath

FUNCTION IAddrBook_GetSearchPath ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL ulFlags AS DWORD _
, BYREF lppSearchPath AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[29] USING IAddrBook_GetSearchPath (pIAddrBook, ulFlags, lppSearchPath) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

SetSearchPath

FUNCTION IAddrBook_SetSearchPath ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL ulFlags AS DWORD _
, BYVAL lpSearchPath AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[30] USING IAddrBook_SetSearchPath (pIAddrBook, ulFlags, lpSearchPath) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

PrepareRecips

FUNCTION IAddrBook_PrepareRecips ( _
  BYVAL pIAddrBook AS DWORD PTR _
, BYVAL lpSPropTagArray AS DWORD _
, BYVAL lpRecipList AS DWORD _
  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pIAddrBook[31] USING IAddrBook_PrepareRecips (pIAddrBook, lpSPropTagArray, lpRecipList) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION