Windows Address Book Reference

This section contains the reference for the Microsoft Windows Address Book (WAB) application programming interface (API).

Microsoft Windows provides an address book for storing contact information. The Windows Address Book (WAB) is an application and service that enables users to keep track of people. The WAB has a local database and user interface for finding and editing information about people, and it can query network directory servers using Lightweight Directory Access Protocol (LDAP). Other applications can use the WAB. For example, Microsoft Outlook uses the WAB as its e-mail address book.

The following overview topics discuss how to use the WAB.

• About Windows Address Book

• Extending the WAB Toolbar and Context Menu Actions

• Extending the WAB Property Sheets

• WAB and Multi-User/Multi-Identity Profiles

• UNICODE Support in WAB

• Importing and Exporting Named Properties Through vCards

Interfaces

IABContainer

IABTable

IAddrBook

IDistList

IMailUser

IWABExtInit

IWABObject

Functions

WABOpen

Provides access to the address book through a number of object interfaces. The root interface is IAddrBook, which is a subset of the MAPI implementation of IAddrBook.

'HRESULT WABOpen(
' LPADRBOOK *lppAdrBook,
' LPWABOBJECT *lppWABObject,
' LPWAB_PARAM lpWABParam,
' DWORD Reserved2
');

DECLARE FUNCTION WABOpen ( _
  BYREF lppAdrBook AS DWORD _
, BYREF lppWABObject AS DWORD _
, BYREF lpWABParam AS WAB_PARAM _
, BYVAL Reserved2 AS DWORD _
) AS LONG

Parameters

lppAdrBook
Address of a pointer to the IAddrBook interface returned by the function.
lppWABObject
Address of a pointer to the IWABObject interface returned by the function.
lpWABParam
Pointer to a WAB_PARAM structure. Supported by Microsoft Internet Explorer 4.0 or later.
Reserved2
Reserved. Must be set to 0.

Return Value

Returns S_OK if successful, or an error value otherwise.
 

WABOpenEx

Provides access to the Microsoft Windows Address Book (WAB) through a number of object interfaces. The root interface is IAddrBook, which is a subset of the MAPI implementation of IAddrBook.

'HRESULT WABOpenEx(
' LPADRBOOK *lppAdrBook,
' LPWABOBJECT *lppWABObject,
' LPWAB_PARAM lpWABParam,
' DWORD Reserved2,
' ALLOCATEBUFFER *lpfnAllocateBuffer,
' ALLOCATEMORE *lpfnAllocateMore,
' FREEBUFFER *lpfnFreeBuffer
');

DECLARE FUNCTION WABOpenEx ( _
  BYREF lppAdrBook AS DWORD PTR _
, BYREF lppWABObject AS DWORD _
, BYREF lpWABParam AS WAB_PARAM _
, BYVAL Reserved2 AS DWORD _
, BYVAL lpfnAllocateBuffer AS DWORD _
, BYVAL lpfnAllocateMore AS DWORD _
, BYVAL lpfnFreeBuffer AS DWORD _
) AS LONG

Parameters

lppAdrBook
Address of a pointer to the IAddrBook interface returned by the function.
lppWABObject
Address of a pointer to the IWABObject interface returned by the function.
lpWABParam
Pointer to a WAB_PARAM structure. Supported by Microsoft Internet Explorer 4.0 or later.
Reserved2
Reserved. Must be set to 0.
lpfnAllocateBuffer
Pointer to a function that specifies the MAPIAllocateBuffer-style allocation function. Set to NULL to use WAB internal routines.
lpfnAllocateMore
Pointer to a function that specifies the MAPIAllocateMore-style allocation function. Set to NULL to use WAB internal routines.
lpfnFreeBuffer
Pointer to a function that specifies the MAPIFreeBuffer-style memory freeing function. Set to NULL to use WAB internal routines.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

WABOpenEx is an extended version of WABOpen that enables developers to specify the memory allocation functions used by WAB to return buffers to the client. If you pass one allocation routine, you must pass all three routines: MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer.

If you do not need the extra memory allocation functionality of WABOpenEx, use WABOpen instead.
 

Note When you specify memory allocation routines with WABOpenEx, these routines globally replace the WAB internal routines for this process. Other threads may still call WABOpen, but the memory will be allocated with those routines previously passed to WABOpenEx.
 

LoadWABLibrary

Retrieves the path of the WAB32.DLL and loads it into memory.

$WAB_DLL_NAME = "WAB32.DLL"
$WAB_DLL_PATH_KEY = "Software\Microsoft\WAB\DLLPath"
 

FUNCTION LoadWABLibrary (BYREF hLib AS DWORD) AS LONG

  LOCAL hr AS LONG ' // Result code
  LOCAL hKey AS DWORD ' // Key handle
  LOCAL szPathToWAB AS ASCIIZ * %MAX_PATH ' // Path of WAB32.DLL

  hr = RegOpenKeyEx(%HKEY_LOCAL_MACHINE, BYCOPY $WAB_DLL_PATH_KEY, 0, %KEY_READ, hKey)
  IF hr <> %ERROR_SUCCESS THEN FUNCTION = hr : EXIT FUNCTION
  hr = RegQueryValueEx(hKey, "", 0, 0, szPathToWAB, SIZEOF(szPathToWAB))
  RegCloseKey hKey
  IF hr <> %ERROR_SUCCESS THEN FUNCTION = hr : EXIT FUNCTION
  hLib = LoadLibrary(szPathToWAB)
  IF hLib = %NULL THEN FUNCTION = GetLastError

END FUNCTION
 

TB_WABOpen

Wrapper function for WABOpen.

FUNCTION TB_WABOpen ( _
  BYVAL hLib AS DWORD _
, BYREF lppAdrBook AS DWORD _
, BYREF lppWABObject AS DWORD _
, BYREF lpWABParam AS WAB_PARAM _
) AS LONG

  LOCAL hr AS LONG ' // Result code
  LOCAL pProcAddress AS DWORD ' // Address of the WABOpen function

  IF ISFALSE hLib THEN FUNCTION = %E_POINTER : EXIT FUNCTION
  pProcAddress = GetProcAddress (hLib, "WABOpen")
  IF ISFALSE pProcAddress THEN FUNCTION = GetLastError : EXIT FUNCTION

  CALL DWORD pProcAddress USING WABOpen (lppAdrBook, lppWABObject, lpWABParam, 0) TO hr
  FUNCTION = hr

END FUNCTION
 

TB_WABOpenEx

Wrapper function for WABOpenEx.

FUNCTION TB_WABOpenEx ( _
  BYVAL hLib AS DWORD _
, BYREF lppAdrBook AS DWORD _
, BYREF lppWABObject AS DWORD _
, BYREF lpWABParam AS WAB_PARAM _
, BYVAL lpfnAllocateBuffer AS DWORD _
, BYVAL lpfnAllocateMore AS DWORD _
, BYVAL lpfnFreeBuffer AS DWORD _
) AS LONG

  LOCAL hr AS LONG ' // Result code
  LOCAL pProcAddress AS DWORD ' // Address of the WABOpen function

  IF ISFALSE hLib THEN FUNCTION = %E_POINTER : EXIT FUNCTION
  pProcAddress = GetProcAddress (hLib, "WABOpenEx")
  IF ISFALSE pProcAddress THEN FUNCTION = GetLastError : EXIT FUNCTION

  CALL DWORD pProcAddress USING WABOpenEx (lppAdrBook, lppWABObject, lpWABParam, 0, lpfnAllocateBuffer, lpfnAllocateMore, lpfnFreeBuffer) TO hr
  FUNCTION = hr

END FUNCTION
 

Structures

ADRENTRY

Describes zero or more properties belonging to one or more recipients.

'typedef struct _ADRENTRY {
' ULONG ulReserved1;
' ULONG cValues;
' LPSPropValue rgPropVals;
'} ADRENTRY;

TYPE ADRENTRY
   ulReserved1 AS DWORD
   cValues AS DWORD
   rgPropVals AS SPropValue PTR
END TYPE

Members

ulReserved1
Reserved. Must be set to 0.
cValues
Variable of type ULONG that specifies the count of properties in the property value array to which the rgPropVals member points. The cValues member can be zero.
rgPropVals
Pointer to a variable of type SPropValue that specifies the property value array describing the properties for the recipient. The rgPropVals member can be NULL.
 

ADRLIST

Describes zero or more properties belonging to one or more recipients.

'typedef struct _ADRLIST {
' ULONG cEntries;
' ADRENTRY aEntries[MAPI_DIM];
'} ADRLIST;

TYPE ADRLIST {
  cEntries AS DWORD
  aEntries (0) AS ADRENTRY   ' Variable-length array
END TYPE

Members

cEntries
Variable of type ULONG that specifies the entry count in the array specified by the aEntries member.
aEntries
Variable of type ADRENTRY that specifies the array of ADRENTRY structures, one structure for each recipient.
 

ADRPARM

Describes the display and behavior of the common address dialog box.

'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 *lppszDestTitles;
' ULONG *lpulDestComps;
' LPSRestriction lpContRestriction;
' LPSRestriction lpHierRestriction;
'} ADRPARM, *LPADRPARM;

TYPE ADRPARM
   cbABContEntryID AS DWORD
   lpABContEntryID AS ENTRYID PTR
   ulFlags AS DWORD
   lpReserved AS DWORD
   ulHelpContext AS DWORD
   lpszHelpFileName AS ASCIIZ PTR
   lpfnABSDI AS DWORD
   lpfnDismiss AS DWORD
   lpvDismissContext AS DWORD
   lpszCaption AS ASCIIZ PTR
   lpszNewEntryTitle AS ASCIIZ PTR
   lpszDestWellsTitle AS ASCIIZ PTR
   cDestFields AS DWORD
   nDestFieldFocus AS DWORD
   lppszDestTitles AS DWORD
   lpulDestComps AS DWORD
   lpContRestriction AS DWORD
   lpHierRestriction AS DWORD
END TYPE

Members

cbABContEntryID
Variable of type ULONG that specifies the list of entries that can be added to the recipient wells.

lpABContEntryID
Pointer to a variable of type ENTRYID that specifies the container that will supply the list of one-off entries that can be added to the recipient wells of the address book's common dialog box. The address book container that lpABContEntryID points to determines what is listed in the edit box within the dialog box that holds possible recipient names. Usually, lpABContEntryID is NULL, indicating the use of a custom recipient provider.

ulFlags
Value of type ULONG that specifies the bitmask of flags associated with various address dialog box options. The following flags can be set in the WAB.

AB_RESOLVE = &H20
Causes all names to be resolved after the address book dialog box is closed. The Resolve Name dialog box is displayed if there are ambiguous entries in the recipient list.
AB_SELECTONLY = &H10
Disables the creation of custom recipient addresses and direct type-in entries for a recipient list. This flag is used only if the dialog box is modal.
ADDRESS_ONE = &H8
Indicates that the user of the dialog box can select exactly one message recipient, instead of a number of recipients from a recipient list. This flag is valid only when cDestFields is zero. This flag is used only if the dialog box is modal.
DIALOG_MODAL = 1
Causes a modal dialog box to be displayed. The client must set either this flag or DIALOG_SDI, but not both.
DIALOG_SDI = 2
Causes a modeless dialog box to be displayed. This call returns immediately and thus does not modify the ADRLIST structure passed in. The caller must set either this flag or DIALOG_MODAL, but not both.

lpReserved
Reserved. Must be set to 0.

ulHelpContext
Not supported. Must be set to 0.

lpszHelpFileName
Not supported. Must be set to NULL.

lpfnABSDI
Pointer to a WAB function based on the ACCELERATEABSDI prototype (see MAPI documentation), or NULL. This member applies only to the modeless version of the dialog box, as indicated by the DIALOG_SDI flag being set.

Clients building an ADRPARM structure to pass to Address must always set the lpfnABSDI member to NULL. If the DIALOG_SDI flag is set, WAB then sets 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 WAB calls the function to which the lpfnDismiss member points, clients should unhook the ACCELERATEABSDI function from their message loop.

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

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

lpszCaption
Variable of type LPTSTR that specifies the text to be used as a caption for the address book dialog box.

lpszNewEntryTitle
Variable of type LPTSTR that specifies the text to be used as a new-entry prompt for an edit box in an address book dialog box.

lpszDestWellsTitle
Variable of type LPTSTR that specifies the text to be used as a title for the set of recipient-name edit boxes that appears in the dialog box. This member is used only if the address book dialog box is modal.

cDestFields
Variable of type ULONG that specifies the number of recipient-name edit boxes (that is, destination fields) in the address book dialog box. A number from 0 through 3 is typical. If the cDestFields member is zero and the ADDRESS_ONE flag is not set in ulFlags, the address book will be open for browsing only.

nDestFieldFocus
Variable of type ULONG that specifies the field in the address book dialog box that should have the initial focus when the dialog box appears. This value must be between 0 and the value of cDestFields minus 1.

lppszDestTitles
Pointer to an array of variables of type LPTSTR that specify the text titles to be displayed in the recipient-name edit boxes of the address book dialog box. The size of the array is the value of cDestFields. If the lppszDestTitles member is NULL, the Address method chooses default titles.

lpulDestComps
Pointer to an array of variables of type ULONG that specify the recipient types—such as MAPI_TO, MAPI_CC, and MAPI_BCC—associated with each recipient-name edit box. The size of the array is the value of cDestFields. If the lpulDestComps member is NULL, the Address method chooses default recipient types.

lpContRestriction
Not supported. Must be set to NULL.

lpHierRestriction
Not supported. Must be set to NULL.
 

ENTRYID

Contains the entry identifier information for a MAPI object.

'typedef struct _ENTRYID {
' BYTE abFlags[4];
' BYTE ab[MAPI_DIM];
'} ENTRYID, *LPENTRYID;

TYPE ENTRYID
   abFlags(3) AS BYTE
   ab (0) AS BYTE   ' Variable-length array
END TYPE

Members

abFlags
Array of variables of type BYTE that specifies the bitmask of flags that provide information describing the object.

ab
Array of variables of type BYTE that specifies the binary data used by service providers. Client applications cannot use this array.
 

ENTRYLIST

An array of entry identifiers representing MAPI objects. Uses the same implementation as SBinaryArray.

'typedef struct _ENTRYLIST {
' ULONG cValues;
' SBinary *lpbin;
'} ENTRYLIST, *LPENTRYLIST;

TYPE ENTRYLIST
   cValues AS DWORD
   lpbin AS SBinary PTR
END TYPE

Members

cValues
Variable of type ULONG that specifies the number of entry identifiers.

lpbin
Array of variables of type SBinary that specify the entry identifiers.
 

SPropProblem

Describes an error relating to an operation involving a property.

'typedef struct _SPropProblem {
' ULONG ulIndex;
' ULONG ulPropTag;
' SCODE scode;
'} SPropProblem;

TYPE SPropProblem
   ulIndex AS DWORD
   ulPropTag AS DWORD
   scode AS DWORD
END TYPE

Members

ulIndex
Variable of type ULONG that specifies the index value in an array of property tags.

ulPropTag
Variable of type ULONG that specifies the property tag for the property with the error.

scode
Variable of type SCODE that specifies the error value that describes the problem with the property.
 

SPropProblemArray

Contains an array of one or more SPropProblem structures.

'typedef struct _SPropProblemArray {
' ULONG cProblem;
' SPropProblem aProblem[MAPI_DIM];
'} SPropProblemArray;

TYPE SPropProblemArray
   cProblem AS DWORD
   aProblem (0) AS SPropProblem   ' Variable-length array
END TYPE

Members

cProblem
Variable of type ULONG that specifies the count of SPropProblem structures in the array indicated by the aProblem member.

aProblem
Array of variables of type SPropProblem that specify information about a property error.
 

SPropTagArray

Contains an array of property tags.

'typedef struct _SPropTagArray {
' ULONG cValues;
' ULONG aulPropTag[MAPI_DIM];
'} SPropTagArray;

TYPE SPropTagArray
   cValues AS DWORD
   aulPropTag (0) AS DWORD   ' Variable-length array
END TYPE

Members

cValues
Variable of type ULONG that specifies the number of property tags in the array indicated by the aulPropTag member.

aulPropTag
Array of variables of type ULONG that specify the property tags.
 

SPropValue

Contains the property tag values.

'typedef struct _SPropValue {
' ULONG ulPropTag;
' ULONG dwAlignPad;
' union {
' short i;
' LONG l;
' ULONG ul;
' float flt;
' double dbl;
' USHORT b;
' CURRENCY cur;
' double at;
' FILETIME ft;
' LPSTR lpszA;
' SBinary bin;
' LPWSTR lpszW;
' LPGUID lpguid;
' LARGE_INTEGER li;
' SShortArray MVi;
' SLongArray MVl;
' SRealArray MVflt;
' SDoubleArray MVdbl;
' SCurrencyArray MVcur;
' SAppTimeArray MVat;
' SDateTimeArray MVft;
' SBinaryArray MVbin;
' SLPSTRArray MVszA;
' SWStringArray MVszW;
' SGuidArray MVguid;
' SLargeIntegerArray MVli;
' SCODE err;
' LONG x;
' } Value;
'} SPropValue;

UNION union_SPropValue
   i AS INTEGER
   l AS LONG
   ul AS DWORD
   flt AS SINGLE
   dbl AS DOUBLE
   b AS WORD
   cy AS CUR
   apt AS DOUBLE
   ft AS FILETIME
   lpszA AS ASCIIZ PTR
   bin AS SBinary
   lpszW AS DWORD
   lpguid AS GUID PTR
   li AS QUAD
   MVi AS SShortArray
   MVl AS SLongArray
   MVflt AS SRealArray
   MVdbl AS SDoubleArray
   MVcur AS SCurrencyArray
   MVat AS SAppTimeArray
   MVft AS SDateTimeArray
   MVbin AS SBinaryArray
   MVszA AS SLPSTRArray
   MVszW AS SWStringArray
   MVguid AS SGuidArray
   MVli AS SLargeIntegerArray
   errn AS DWORD
   x AS LONG
END UNION

TYPE SPropValue
   ulPropTag AS DWORD
   dwAlignPad AS DWORD
   Value AS union_SPropValue
END TYPE

Members

ulPropTag
Variable of type ULONG that specifies the property tag for the property. Property tags are 32-bit unsigned integers consisting of the property's unique identifier in the high-order 16 bits and the property's type in the low-order 16 bits.

dwAlignPad
Reserved. Must be set to 0.

Value
Union of data values, with the specific value dictated by the property type. The following text provides a list for each property type of the member of the union to be used and its associated data type.

i
    PT_I2 or PT_SHORT
l
     PT_LONG
ul
     PT_LONG
flt
     PT_R4
dbl
    PT_DOUBLE
b
    PT_BOOLEAN
cur
    PT_CURRENCY
at
    PT_APPTIME
ft
    PT_SYSTIME
lpszA
    PT_STRING8
bin
    PT_BINARY
lpszW
    PT_UNICODE
lpguid
    PT_CLSID
li
    PT_I8
MVi
    PT_MV_I2
MVl
    PT_MV_LONG
MVflt
    PT_MV_R4
MVdbl
    PT_MV_DOUBLE
MVcur
    PT_MV_CURRENCY
MVat
    PT_MV_APPTIME
MVft
    PT_MV_SYSTIME
MVbin
    PT_MV_BINARY
MVszA
    PT_MV_STRING8
MVszW
    PT_MV_UNICODE
MVguid
    PT_MV_CLSID
MVli
    PT_MV_I8
err
    PT_ERROR
x
    PT_NULL, PT_OBJECT (no usable value)
 

SRestriction

Describes a filter for limiting the view of a table to particular rows.

'typedef struct _SRestriction {
' ULONG rt;
' union {
' SComparePropsRestriction resCompareProps;
' SAndRestriction resAnd;
' SOrRestriction resOr;
' SNotRestriction resNot;
' SContentRestriction resContent;
' SPropertyRestriction resProperty;
' SBitMaskRestriction resBitMask;
' SSizeRestriction resSize;
' SExistRestriction resExist;
' SSubRestriction resSub;
' SCommentRestriction resComment;
' } res;
'} SRestriction;

UNION union_SRestriction
   resCompareProps AS SComparePropsRestriction
   resAnd AS SAndRestriction
   resOr AS SOrRestriction
   resNot AS SNotRestriction
   resContent AS SContentRestriction
   resProperty AS SPropertyRestriction
   resBitMask AS SBitMaskRestriction
   resSize AS SSizeRestriction
   resExist AS SExistRestriction
   resSub AS SSubRestriction
   resComment AS SCommentRestriction
END UNION

TYPE SRestriction
   rt AS DWORD
   res AS union_SRestriction
END TYPE

Members

rt
Variable of type ULONG that specifies the restriction type. The possible values are as follows.

RES_AND = 0
SRestriction structure describes an AND restriction, which applies a bitwise AND operation to a restriction.
RES_BITMASK = 6
SRestriction structure describes a bitmask restriction, which applies a bitmask to a property value.
RES_COMMENT = 10
SRestriction structure describes a comment restriction, which associates a comment with a restriction.
RES_COMPAREPROPS = 5
SRestriction structure describes a compare properties restriction, which compares two property values.
RES_CONTENT = 3
SRestriction structure describes a content restriction, which searches a property value for specific content.
RES_EXIST = 8
SRestriction structure describes an exist restriction, which determines if a property is supported.
RES_NOT = 2
SRestriction structure describes a NOT restriction, which applies a logical NOT operation to a restriction.
RES_OR = 1
SRestriction structure describes an OR restriction, which applies a logical OR operation to a restriction.
RES_PROPERTY = 4
SRestriction structure describes a property restriction, which determines if a property value matches a particular value.
RES_SIZE = 7
SRestriction structure describes a size restriction, which determines if a property value is a particular size.
RES_SUBRESTRICTION = 9
SRestriction structure describes a subobject restriction, which applies a restriction to a message's attachments or recipients.

uRes
Union of restriction structures describing the filter to be applied. The specific structure included in the res member depends on the value of the rt member. The following list gives the mapping between the structure and the restriction type.

resCompareProps
     RES_COMPAREPROPS
resAnd
    RES_AND
resOr
    RES_OR
resNot
    RES_NOT
resContent
    RES_CONTENT
resProperty
    RES_PROPERTY
resBitMask
    RES_BITMASK
resSize
    RES_SIZE
resExist
    RES_EXIST
resSub
    RES_SUBRESTRICTION
resComment
    RES_COMMENT
 

SRow

Describes a row from a table containing selected properties for a specific object.

'typedef struct _SRow {
' ULONG ulAdrEntryPad;
' ULONG cValues;
' LPSPropValue lpProps;
'} SRow, *LPSRow;

TYPE SRow
   ulAdrEntryPad AS DWORD
   cValues AS DWORD
   lpProps AS SPropValue PTR
END TYPE

Members

ulAdrEntryPad
Variable of type ULONG that specifies the number of padding bytes for aligning properly the property values to which the lpProps member points.

cValues
Variable of type ULONG that specifies the count of property values to which lpProps points.

lpProps
Pointer to an array of variables of type SPropValue that describe the property values for the columns in the row.
 

SRowSet

Contains an array of SRow structures. Each SRow structure describes a row from a table.

'typedef struct _SRowSet {
' ULONG cRows;
' SRow aRow[MAPI_DIM];
'} SRowSet;

TYPE SRowSet
   cRows AS DWORD
   aRow (0) AS SRow   ' Variable-length array
END TYPE

Members

cRows
Variable of type ULONG that specifies the number of SRow structures in the aRow member.

aRow
Array of variables of type SRow that specifies the structures that represent the rows in the table.
 

SSortOrder

Defines how to sort rows of a table, describing both the column to use as the sort key and the direction of the sort.

'typedef struct _SSortOrder {
' ULONG ulPropTag;
' ULONG ulOrder;
'} SSortOrder, *LPSSortOrder;

TYPE SSortOrder
   ulPropTag AS DWORD
   ulOrder AS DWORD
END TYPE

Members

ulPropTag
Variable of type ULONG that specifies the property tag identifying either the sort key or, for a categorized sort, the category column.
 

ulOrder
Variable of type ULONG that specifies the order in which the data is to be sorted. The possible values are as follows.

TABLE_SORT_ASCEND = &H00000000
Table is sorted in ascending order.
TABLE_SORT_COMBINE =  &H00000002
Sort operation creates a category that combines the property identified as the sort key column in the ulPropTag member with the sort key column specified in the previous SSortOrder structure.
TABLE_SORT_COMBINE can only be used when the SSortOrder structure is being used as an entry in an SSortOrderSet structure to specify multiple sort orders for a categorized sort. TABLE_SORT_COMBINE cannot be used in the first SSortOrder structure in an SSortOrderSet structure.
TABLE_SORT_DESCEND = &H00000001
Table is sorted in descending order.
 

SSortOrderSet

Defines a collection of keys for a table to be used for standard or categorized sorting.

'typedef struct _SSortOrderSet {
' ULONG cSorts;
' ULONG cCategories;
' ULONG cExpanded;
' SSortOrder aSort[MAPI_DIM];
'} SSortOrderSet, *LPSSortOrderSet;

TYPE SSortOrderSet
   cSorts AS DWORD
   cCategories AS DWORD
   cExpanded AS DWORD
   aSort (0) AS SSortOrderSet   ' Variable-length array
END TYPE

Members

cSorts
Variable of type ULONG that specifes the number of SSortOrder structures that are included in the aSort member.

cCategories
Variable of type ULONG that specifes the number of columns that are designated as category columns. Possible values range from zero, which indicates a non-categorized or standard sort, to the number indicated by the cSorts member.

cExpanded
Variable of type ULONG that specifies the number of categories that start in an expanded state, where all the rows that apply to the category are visible in the table view. Possible values range from zero to the number indicated by cCategories.

aSort
Array of variables of type SSortOrder that specifies the structures that define a sort order.
 

WAB_PARAM

Contains the input information to pass to WABOpen.

'typedef struct _WAB_PARAM {
' ULONG cbSize;
' HWND hwnd;
' LPTSTR szFileName;
' ULONG ulFlags;
' GUID guidPSExt;
'} WAB_PARAM, *LPWAB_PARAM;

TYPE WAB_PARAM
   cbSize AS DWORD
   hwnd AS DWORD
   szFileName AS ASCIIZ PTR
   ulFlags AS DWORD
   guidPSExt AS GUID
END TYPE

Members

cbSize
Value of type ULONG that specifies the size of the WAB_PARAM structure in bytes.

hwnd
Value of type HWND that specifies the window handle of the calling client application. Can be NULL.

szFileName
Value of type LPTSTR that specifies the Microsoft Windows Address Book (WAB) file name to open. If this parameter is NULL, the default Address Book file is opened.

ulFlags
Value of type ULONG that specifies flags that control the behavior of WAB functionality. Available only on Microsoft Internet Explorer 4.0 or later.

WAB_USE_OE_SENDMAIL = &H00000001
Indicates that WAB is to use Microsoft Outlook Express for e-mail before checking for a default Simple MAPI client. Default behaviour is to check for the Simple MAPI client first.

WAB_ENABLE_PROFILES = &H00400000
Invokes WAB in an Identity-aware session using Identity-Manager based profiles. Available only on Internet Explorer 5 or later.

guidPSExt
Value of type GUID that specifies the GUID that identifies the calling application's property sheet extensions. The GUID can be used to determine whether the extension property sheets are displayed or not. Available only on Internet Explorer 5 or later.
 

WABEXTDISPLAY

Used by the Microsoft Windows Address Book (WAB) to initialize user's IContextMenu and IShellPropSheetExt implementations.

'typedef struct _WABEXTDISPLAY {
' ULONG cbSize;
' LPWABOBJECT lpWABObject;
' LPADRBOOK lpAdrBook;
' LPMAPIPROP lpPropObj;
' BOOL fReadOnly;
' BOOL fDataChanged;
' ULONG ulFlags;
' LPVOID lpv;
' LPTSTR lpsz;
'} WABEXTDISPLAY, *LPWABEXTDISPLAY;

TYPE WABEXTDISPLAY
   cbSize AS DWORD
   lpWABObject AS DWORD PTR
   lpAdrBook AS DWORD PTR
   lpPropObj AS DWORD PTR
   fReadOnly AS LONG
   fDataChanged AS LONG
   ulFlags AS DWORD
   lpv AS DWORD
   lpsz AS ASCIIZ PTR
END TYPE

Members

cbSize
Not used.
 

lpWABObject
Pointer to an IWABObject interface that specifies the object to use for calling the IWABObject memory allocation methods. These methods allocate any memory that you pass back to the WAB and that you expect the WAB to free or use. You can also use this pointer to call any of the other IWABObject methods.
 

lpAdrBook
Pointer to an IAddrBook interface that specifies the object to use for calling any of the standard WAB IAddrBook methods.
 

lpPropObj

Pointer to an IMailUser object. This interface is relevant for both IShellPropSheetExt and IContextMenu implementations. For IShellPropSheetExt implementations, lpPropObj contains the actual object being displayed. It can be either an IMailUser or IDistList object. To determine which object lpPropObj is, query for its PR_OBJECT_TYPE property. You can retrieve properties from this object to populate your extension property sheets.

For IContextMenu implementations, lpPropObj contains a valid object; however, this object does not have any properties associated with it. You can call the AddRef on this object to ensure that the object and any other data of interest in this WABEXTDISPLAY structure survives as long as you need it. If you call AddRef, you must call Release on lpPropObj when you no longer need it.

If your application uses named properties, and you want to get the named properties relevant to you from the WAB, you can call the GetIDsfromNames method on this lpPropObj object to retrieve any such named properties. If you want to access properties that are associated with messaging users, cast this object to an LPMAILUSER before calling GetIDsfromNames on it.
 

fReadOnly
Variable of type BOOL that specifies the read-only property on certain kinds of objects, such as vcard_name, LDAP search results, and One-Off MailUser. This member is relevant only for IShellPropSheetExt. If this flag is set to true, one's property sheet must set all its controls to a read-only or disabled mode, typically in response to the WM_INITDIALOG message. Setting controls to a read-only state makes the user experience more consistent.
 

fDataChanged
Variable of type BOOL that specifies the flag indicating that a change has been made to your property sheet. This member is relevant for IShellPropSheetExt only. Any time the user makes a change such as adding, editing or deleting data on your property sheet, you must set this flag to true to signal to the WAB that the data on your property sheet has changed. If this flag is not set, the WAB may not persist the changes the user made to your property sheet.
 

ulFlags
Variable of type ULONG that specifies flags that control behavior. The following flags are valid.

WAB_CONTEXT_ADRLIST = &H00000002
Set when the WAB calls IWABExtInit::Initialize prior to invoking your IContextMenu methods. This flag indicates that lpv contains a pointer to an ADRLIST structure. The ADRLIST structure contains one or more entries, each corresponding to a selected item in the WAB user interface. To retrieve and use this ADRLIST, cast lpv to an LPADRLIST. You can also use ulFlags to determine that WABEXTDISPLAY is being used to initialize an IContextMenu operation. If ulFlags does not contain this flag, you can safely assume that the structure is being used for a IShellPropSheetExt action.

WAB_DISPLAY_LDAPURL = &H00000001
Indicates that lpsz contains the LDAP URL that is currently being displayed. Sometimes the WAB will display a property sheet on a contact represented by a LDAP URL. While the contact to which the LDAP URL points will be wrapped into a WAB object and placed in lpPropObj, the property sheet may access the URL directly.

lpv
Pointer that specifies miscellaneous information that is passed to your application. The current flags identify the information being represented. If ulFlags is set to WAB_CONTEXT_ADRLIST, lpv contains a pointer to an ADRLIST. Cast lpv to an ADRLIST to access the contents of the ADRLIST. The cEntries member contains the number of selected items. The ADRENTRY structures in aEntries contain SPropValue arrays with all of the properties pertaining to each selected item.
 

lpsz
Variable of type LPTSTR that specifies a string used for passing in miscellaneous information to your application. The current flags identify the information being represented. If ulFlags is set to WAB_DISPLAY_LDAPURL, the lpsz member contains a pointer to a NULL terminated string containing the Lightweight Directory Access Protocol (LDAP) URL whose properties are being displayed.
 

WABIMPORTPARAM

Structure passed to IWABObject::Import that gives information about importing .wab files.

'typedef struct _WABIMPORTPARAM {
' ULONG cbSize;
' IAddrBook *lpAdrBook;
' HWND hwnd;
' ULONG ulFlags;
' LPSTR lpszFileName;
'} WABIMPORTPARAM, *LPWABIMPORTPARAM;

TYPE WABIMPORTPARAM
   cbSize AS DWORD
   lpAdrBook AS DWORD PTR
   hwnd AS DWORD
   ulFlags AS DWORD
   lpszFileName AS ASCIIZ PTR
END TYPE

Members

cbSize
Value of type ULONG that specifies the size of the structure in bytes.
 

lpAdrBook
Pointer to an IAddrBook interface that specifies the address book object to import to.
 

hwnd
Value of type HWND that specifies the parent window handle for any dialog boxes.
 

ulFlags
Value of type ULONG that specifies flags affecting behavior.

MAPI_DIALOG = &H00000008
Causes IWABObject::Import to show a dialog box with a progress bar indicating the progress of the import process.

lpszFileName
Value of type LPSTR that specifies the filename to import, or NULL to cause a FileOpen dialog box to open.
 

Enumerations

Gender

The Gender enumeration specifies the possible values for the PR_GENDER property.

%genderUnspecified = 0
' No gender is specified.
%genderFemale = 1
' Specifies a gender of female.
%genderMale = 2
' Specifies a gender of male.
 

WAB Example

' ****************************************************************************************
' WAB Example
' ****************************************************************************************

#COMPILE EXE
#DIM ALL
#DEBUG ERROR ON

#INCLUDE "Win32Api.inc"
#INCLUDE "TB_MAPIX.INC"

' ****************************************************************************************
' Main
' ****************************************************************************************
FUNCTION PBMAIN () AS LONG


   LOCAL hr AS LONG                            ' // HRESULT
   LOCAL hWabLib AS DWORD                      ' // Handle of the WAB library
   LOCAL wp AS WAB_PARAM                       ' // WAB_PARAM structure
   LOCAL ppIAddrBook AS DWORD                  ' // IAddrBook interface pointer
   LOCAL ppIWABObject AS DWORD                 ' // IWABObject interface pointer
   LOCAL cbEntryID AS DWORD                    ' // Size of the entry identifier
   LOCAL pEntryID AS ENTRYID PTR               ' // Pointer to an ENTRYID structure
   LOCAL ulFlags AS DWORD                      ' // Flags
   LOCAL ulObjType AS DWORD                    ' // Object type
   LOCAL IID_IABContainer AS GUID              ' // IABContainer IID
   LOCAL ppIABCOntainer AS DWORD               ' // IABContainer interface pointer
   LOCAL ppIABTable AS DWORD                   ' // IABTable interface pointer
   LOCAL ulRows AS DWORD                       ' // Number of rows
   LOCAL dwRowSet AS DWORD
   LOCAL pRowSet AS SRowSet PTR                ' // Pointer to a SRowset structure
   LOCAL cRows AS DWORD                        ' // Number of rows
   LOCAL pRow AS SRow PTR                      ' // Pointer to a SRow structure
   LOCAL i AS LONG                             ' // Loop counter
   LOCAL x AS LONG                             ' // Loop counter
   LOCAL pProp AS SPropValue PTR               ' // Pointer to a SPropValue structure
   LOCAL cValues AS DWORD
   LOCAL ppIMailUser AS DWORD

   ' Load the WAB library
   hr = LoadWABLibrary(hWabLib)
   IF ISTRUE hr THEN
      MSGBOX "LoadWABLibrary - Error: " & HEX$(hr)
      EXIT FUNCTION
   END IF

   ' Initialize the WAB_PARM structure
   wp.cbsize = SIZEOF(WAB_PARAM)
   ' To open a particular WAB file, set the path
   ' LOCAL szFileName AS ASCIIZ * %MAX_PATH
   ' szFileName = "<WAB file path>"
   ' wp.szFileName = VARPTR(szFileName)
'   hr = TB_WABOpen(hWABLib, ppIAddrBook, ppIWABObject, wp)
   ' If we choose not to pass in a WAB_PARAM object,
   ' the default WAB file will be opened up
   hr = TB_WABOpen(hWABLib, ppIAddrBook, ppIWABObject, BYVAL %NULL)
   IF hr THEN
      MSGBOX "TB_WABOpen - Error: " & HEX$(hr)
      EXIT FUNCTION
   END IF

   ' You can think of the WAB as a database. Everything is stored in rows with
   ' a binary entry identifier (ENTRYID) for each row.  In the next portion,
   ' cbEntryID tells us the size of what the ENTRYID is going to be and
   ' IAddrBook_GetPAB() will return the entry identifier to our actual
   ' Address Book data.

   hr = IAddrBook_GetPAB(ppIAddrBook, cbEntryID, pEntryID)
   IF hr <> %S_OK THEN
      MSGBOX "IAddrBook_GetPAB - Error: " & HEX$(hr)
      GOTO Terminate
   END IF

   ' Open the Address Book with MAPI_BEST_ACCESS which opens the entry with
   ' the best available access rights. It returns a pointer to the IABContainer
   ' interface, which lets us get the contents of the WAB table.
   ulObjType = %NULL
   ulFlags = %MAPI_BEST_ACCESS
   hr = IAddrBook_OpenEntry(ppIAddrBook, cbEntryID, pEntryID, BYVAL %NULL, ulFLags, ulObjType, ppIABContainer)
   ' Free the buffer pointed by pEntryID
   IF ISTRUE pEntryID THEN
      IWABObject_FreeBuffer(ppIWABObject, pEntryID)
      pEntryID = %NULL
   END IF
   ' Check for IAddrBook_OpenEntry errors
   IF hr <> %S_OK THEN
      MSGBOX "IAddrBook_OpenEntry - Error: " & HEX$(hr)
      GOTO Terminate
   END IF

   IF ulObjTYpe = %MAPI_ABCONT THEN
      ' Get the IABTable reference for the WAB
      ulFlags = %NULL
      hr = IABContainer_GetContentsTable(ppIABContainer, ulFlags, ppIABTable)
      IF hr <> %S_OK THEN
         MSGBOX "IABContainer_GetContentsTable - Error: " & HEX$(hr)
         GOTO Terminate
      END IF
      hr = IABTable_GetRowCount(ppIABTable, 0, ulRows)
      IF hr <> %S_OK THEN
         MSGBOX "IABTable_GetRowCount - Error: " & HEX$(hr)
         GOTO Terminate
      END IF
      IF ulRows = 0 THEN
         MSGBOX "No rows"
         GOTO Terminate
      END IF
      ' Query all the rows
      hr = IABTable_QueryRows(ppIABTable, ulRows, 0, dwRowset)
      IF hr <> %S_OK THEN
         MSGBOX "IABTable_QueryRows - Error: " & HEX$(hr)
         GOTO Terminate
      END IF
      pRowSet = dwRowSet
      MSGBOX "pRowSet = " & STR$(pRowSet)
      ' Get the number of rows retrieved
      cRows = @pRowSet.cRows
      MSGBOX "Rows = " & STR$(cRows)

      ' Parse the Rowset array
      FOR i = 0 TO cRows - 1
         pProp = @pRowSet.aRow(i).lpProps
         IF pProp THEN
            cValues = @pRowSet.aRow(i).cValues
            MSGBOX "cValues = " & STR$(cValues)
            FOR x = 0 TO cValues -1
               IF @pRowSet.aRow(i).@lpProps[x].ulPropTag = PR_DISPLAY_NAME_A THEN
                  MSGBOX "Name = " & @pRowSet.aRow(i).@lpProps[x].Value.@lpszA
               END IF
               IF @pRowSet.aRow(i).@lpProps[x].ulPropTag = PR_EMAIL_ADDRESS_A THEN
                  MSGBOX "Email = " & @pRowSet.aRow(i).@lpProps[x].Value.@lpszA
               END IF
               IF @pRowSet.aRow(i).@lpProps[x].ulPropTag = PR_NICKNAME_A THEN
                  MSGBOX "Email = " & @pRowSet.aRow(i).@lpProps[x].Value.@lpszA
               END IF
               IF @pRowSet.aRow(i).@lpProps[x].ulPropTag = PR_ENTRYID THEN
                  cbEntryID = @pRowSet.aRow(i).@lpProps[x].Value.sbin.cb
                  MSGBOX "cbEntryID = " & STR$(cbEntryID)
                  pEntryID = @pRowSet.aRow(i).@lpProps[x].Value.sbin.lpb
                  MSGBOX "pEntryID = " & STR$(pEntryID)
                  hr = IAddrBook_OpenEntry(ppIAddrBook, cbEntryID, pEntryID, BYVAL %NULL, 0, ulObjType, ppIMailUser)
                  MSGBOX "ppIMailUser = " & STR$(ppIMailUser) & " | " & HEX$(hr)
                  ' Free the buffer pointed by pEntryID
                  IF ISTRUE pEntryID THEN
                     IWABObject_FreeBuffer(ppIWABObject, pEntryID)
                     pEntryID = %NULL
                  END IF
                  IMailUser_Release ppIMailUser
               END IF
            NEXT
            hr = IWABObject_FreeBuffer(ppIWABObject, pProp)
         END IF
      NEXT
      ' Free the SRowSet array
      hr = IWABObject_FreeBuffer(ppIWABObject, pRowSet)
   END IF


Terminate:

   ' Release the IABTable interface
   IF ISTRUE ppIABTable THEN IABTable_Release ppIABTable

   ' Release the IABContainer interface
   IF ISTRUE ppIABContainer THEN IABContainer_Release ppIABContainer

   ' Release the interfaces
   IF ISTRUE ppIAddrBook THEN IAddrBook_Release ppIAddrBook
   IF ISTRUE ppIWABObject THEN IWABObject_Release ppIWABObject

   ' Free the WAB library
   IF hWABLib THEN FreeLibrary hWABLib

END FUNCTION
' ****************************************************************************************