Internet Explorer Address Book Interfaces

Internet Explorer Address Book Interfaces


Internet Explorer Address Book exports one API, WABOpen. This API gives 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.

These interfaces are based on the address book interface exposed by Extended MAPI 1.0, but Internet Explorer Address Book does not use or require MAPI in any way. OLE is used only for its user interface functionality, such as drag and drop and shell integration. Nothing in OLE is loaded until it is needed.

The IUnknown interface allows clients to get pointers to other interfaces on a given object through the IUnknown::QueryInterface method, and manage the existence of the object through the IUnknown::AddRef and IUnknown::Release methods. All other COM interfaces are inherited, directly or indirectly, from IUnknown. Therefore, the three methods in IUnknown are the first entries in the vtable for every interface.

In a future release, these objects may be exposed to applications that want an OLE Automation interface. For additional information on the IUnknown interface methods, see the Platform SDK.

The following sections describe the Internet Explorer Address Book interfaces and methods.

IABContainer

The methods that are included within the IABContainer interface provide the mechanisms for creating, deleting, searching, and modifying address book entries. The organization of the method list for IABContainer is arranged in v-table order.
IABContainer methods
GetLastError
SaveChanges
GetProps
GetPropList
OpenProperty
SetProps
DeleteProps
CopyTo
CopyProps
GetNamesFromIDs
GetIDsFromNames
GetContentsTable
GetHierarchyTable
OpenEntry
SetSearchCriteria
GetSearchCriteria
CreateEntry
CopyEntries
DeleteEntries
ResolveNames

IABContainer::CopyEntries

Currently not implemented in Internet Explorer Address Book.

IABContainer::CopyProps

Currently not implemented in Internet Explorer Address Book.

IABContainer::CopyTo

Currently not implemented in Internet Explorer Address Book.

IABContainer::CreateEntry

HRESULT CreateEntry(
    ULONG       cbEntryID,
    LPENTRYID   lpEntryID,
    ULONG       ulCreateFlags,
    LPMAPIPROP  lppMAPIPropEntry
);

Creates a new entry in the address book container. Internet Explorer Address Book supports creating new address book objects IDistList for a distribution list and IMailUser for a messaging user. Internet Explorer Address Book might support creation of subcontainers in a future version.

cbEntryID
Size, in bytes, of the existing entry identifier to copy from, in the lpEntryID parameter.
lpEntryID
Entry identifier of the object to copy from.
ulCreateFlags
Bitmask of flags that control how entry creation is performed. The following flags can be set:
CREATE_CHECK_DUP_LOOSE
Indicates a loose level should be used for duplicate entry checking, which returns more matches than setting a strict level with the CREATE_CHECK_DUP_STRICT flag. For example, a provider can define a loose match as any two entries having the same display name.
CREATE_CHECK_DUP_STRICT
Indicates a strict level should be used for duplicate entry checking, which returns fewer matches than setting a loose level with the CREATE_CHECK_DUP_LOOSE flag. For example, a provider can define a strict match as any two entries having the same display name and messaging address.
CREATE_REPLACE
Indicates that duplicate entries replace existing entries within a container.
lppMAPIPropEntry
Returned property interface to a new object.

These flags are valid only for the instance of the object returned by CreateEntry. There is no way in the API to get the SetProps or the SaveChanges method to check for duplicates on an object returned by OpenEntry. To do duplicate checking on SaveChanges of an object returned by OpenEntry, the caller would have to do the following:

  1. Modify any of the name fields in the user interface: PR_SURNAME, PR_GIVEN_NAME, PR_COMPANY_NAME, or PR_DISPLAYNAME.
  2. Delete the old contact.
  3. Use CreateEntry to create a new entry with the CREATE_CHECK_DUP_LOOSE flag, set the properties, and save the changes. On failure, restore the original entry.

IABContainer::DeleteEntries

HRESULT DeleteEntries(
    LPENTRYLIST   lpEntries,
    ULONG         ulFlags
);

Removes one or more entries from the address book container.

lpEntries
ENTRYLIST structure containing identifiers of entries to be deleted.
ulFlags
Reserved; must be zero.

IABContainer::DeleteProps

Currently not implemented in Internet Explorer Address Book.

IABContainer::GetContentsTable

HRESULT GetContentsTable(
    ULONG    ulFlags,
    LPMAPITABLE FAR *  lppTable
);

Returns a pointer to the contents table of the container.

ulFlags
Bitmask of flags that provide the ability to specify the returned text type. Can be one of the following:
MAPI_DEFERRED_ERRORS Not supported by Internet Explorer Address Book.
MAPI_UNICODE Indicates the returned strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format. Not supported in the first version of Internet Explorer Address Book.
lppTable
Address of the table object containing the contents table.

IABContainer::GetHierarchyTable

Currently not implemented in Internet Explorer Address Book.

IABContainer::GetIDsFromNames

Currently not implemented in Internet Explorer Address Book.

IABContainer::GetLastError

Currently not implemented in Internet Explorer Address Book.

IABContainer::GetNamesFromIDs

Currently not implemented in Internet Explorer Address Book.

IABContainer::GetPropList

Currently not implemented in Internet Explorer Address Book.

IABContainer::GetProps

Currently not implemented in Internet Explorer Address Book.

IABContainer::GetSearchCriteria

Currently not implemented in Internet Explorer Address Book.

IABContainer::OpenEntry

HRESULT OpenEntry(
    ULONG         cbEntryID,
    LPENTRYID     lpEntryID,
    LPCIID        lpInterface,
    ULONG         ulFlags,
    ULONG FAR     *lpulObjType,
    LPUNKNOWN FAR *lppUnk
);

Opens a child container object contained in the open container and returns a pointer to the object to provide further access.

cbEntryID
Count of bytes in the entry identifier pointed to by the lpEntryID parameter.
lpEntryID
Address of the entry identifier of the object to open. If lpEntryID is set to NULL, the top-level container in the container's hierarchy is opened.
lpInterface
Address of the interface identifier (IID) representing the interface to be used to access the object. Passing NULL results in the identifier for the object's standard interface being returned. For messages, the standard interface is IMessage; for folders, it is IMAPIFolder. The standard interfaces for address book objects are IDistList for a distribution list and IMailUser for a messaging user.
ulFlags
Bitmask of flags that control how the object is opened. The following flags can be used:
MAPI_BEST_ACCESS Requests that the object be opened with the maximum network permissions allowed for the user and the maximum client application access. For example, if the client has read/write access, the object should be opened with read/write access; if the client has read-only access, the object should be opened with read-only access.
MAPI_DEFERRED_ERRORS Not supported by Internet Explorer Address Book at this time.
MAPI_MODIFY Requests read/write access. By default, objects are opened with read-only access, and clients should not work on the assumption that read/write access has been granted.
lpulObjType
Address of the opened object's type.
lppUnk
Address of a pointer to the interface implementation to use to access the open object.

IABContainer::OpenProperty

Currently not implemented in Internet Explorer Address Book.

IABContainer::ResolveNames

HRESULT ResolveNames(
    LPSPropTagArray    lpPropTagArray,
    ULONG              ulFlags,
    LPADRLIST          lpAdrList,
    LPFlagList         lpFlagList
);

Resolves entries against the address book container.

lpPropTagArray
SPropTagArray structure that specifies the set of properties to be included in the returned ADRLIST structure. Pass NULL to return the default columns.
ulFlags
MAPI_UNICODE flag, which indicates the returned strings of the default column set are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

Note Must be zero in the first version of Internet Explorer Address Book.

lpAdrList
Input-output parameter that on input points to an ADRLIST structure containing the address list of entries whose names need to be resolved. On output, this parameter returns the list of resolved names.
lpFlagList
Input-output parameter containing an array of flags; each flag corresponds to an entry in lpAdrList and provides the name-resolution status for that particular entry. The flags in the lpFlagList parameter are in the same order as the entries in lpAdrList. The following flags can be set:
MAPI_AMBIGUOUS Indicates that the corresponding entry is resolved, but that it did not resolve to a unique entry identifier. If this flag is returned, other containers should ignore this entry when the lpAdrList is passed to them for further name resolution.
MAPI_RESOLVED Indicates that the corresponding entry has been resolved to a unique entry identifier. If this flag is returned, other containers should ignore this entry in further resolution.
MAPI_UNRESOLVED Indicates that the corresponding entry is unresolved. Another container can attempt to resolve this entry.

This method takes the address list passed in lpAdrList and tries to resolve all the entries that have their corresponding MAPI_UNRESOLVED flag set in lpFlagList. Entries in lpAdrList that lack the PR_ENTRYID property are considered unresolved.

The array of flags this method returns in lpFlagList is used to track the results of the name resolution operation; the array shows for each entry name whether it is resolved or unresolved or matches more than one entry. If, after looking at an unresolved entry, a container can match that entry uniquely, ResolveNames sets the flag for that entry in lpFlagList to MAPI_RESOLVED and adds the PR_ENTRYID property for that entry to that entry's ADRENTRY structure in the address list in lpAdrList. If a container contains more than one entry that matches a given unresolved entry, ResolveNames sets the flag for the unresolved entry in lpFlagList to MAPI_AMBIGUOUS and leaves that entry's ADRENTRY alone.

If the ResolveNames method is unable to return all the properties requested for an unresolved entry, and these properties don't exist in the ADRENTRY structure passed in, it sets the property type of each property not returned to PT_ERROR. Any property columns that are already included for an entry are retained if that entry is resolved.

Note The ADRENTRY items in ADRLIST should be separately allocated, not allocated with AllocateMore. When ResolveNames replaces an entry, it expects to free the ADRENTRY structure by using FreeBuffer and allocate a new one by using AllocateBuffer.

IABContainer::SaveChanges

Currently not implemented in Internet Explorer Address Book.

IABContainer::SetProps

Currently not implemented in Internet Explorer Address Book.

IABContainer::SetSearchCriteria

Currently not implemented in Internet Explorer Address Book.

IABTable

This interface is based upon the IMAPITable interface. This interface is used for contents tables of Internet Explorer Address Book containers and distribution lists. The organization of the method list for IABTable is arranged in v-table order.
IABTable methods
GetLastError
Advise
Unadvise
GetStatus
SetColumns
QueryColumns
GetRowCount
SeekRow
SeekRowApprox
QueryPosition
FindRow
Restrict
CreateBookmark
FreeBookmark
SortTable
QuerySortOrder
QueryRows
Abort
ExpandRow
CollapseRow
WaitForCompletion
GetCollapseState
SetCollapseState

IABTable::Abort

Currently not implemented by Internet Explorer Address Book.

IABTable::Advise

Currently not implemented by Internet Explorer Address Book.

IABTable::CollapseRow

Currently not implemented by Internet Explorer Address Book.

IABTable::CreateBookmark

HRESULT CreateBookmark(
    BOOKMARK FAR * lpbkPosition
);

Creates the address of the current position of the table cursor so a client can return to that position even when the table is updated. The method that calls this method must clean up by freeing the bookmark with FreeBookmark.

lpbkPosition
Address of the returned bookmark's 32-bit bookmark value.

IABTable::ExpandRow

Currently not implemented by Internet Explorer Address Book.

IABTable::FindRow

HRESULT FindRow(
    LPSRestriction  lpRestriction,
    BOOKMARK  BkOrigin,
    ULONG     ulFlags
);

Find the next row in a table that contains a property matching the specified criteria.

lpRestriction
Address of an SRestriction structure that describes the search criteria.
BkOrigin
Bookmark identifying the row where FindRow should begin its search. A bookmark can be created using the CreateBookmark method, or one of the following predefined values can be passed:
BOOKMARK_BEGINNING Searches from the beginning of the table
BOOKMARK_CURRENT Searches from the row in the table where the cursor is located.
BOOKMARK_END Searches from the end of the table.
ulFlags
Bitmask of flags that control the direction of the search. The following flag can be set:
DIR_BACKWARD Searches backward from the row identified by the bookmark.

IABTable::FreeBookmark

HRESULT FreeBookmark(
    BOOKMARK bkPosition
);

Provides the ability to free a bookmark that was created by CreateBookmark.

bkPosition
Address of the bookmark to free.

IABTable::GetCollapseState

Currently not implemented by Internet Explorer Address Book.

IABTable::GetLastError

Currently not implemented by Internet Explorer Address Book.

IABTable::GetRowCount

HRESULT GetRowCount(
    ULONG  ulFlags,
    ULONG  FAR *lpulCount
);

Returns the total number of rows in a table view.

ulFlags
Reserved; must be zero.
lpulCount
Address of the number of rows in the table.

IABTable::GetStatus

Currently not implemented by Internet Explorer Address Book.

IABTable::QueryColumns

HRESULT QueryColumns(
    ULONG  ulFlags,
    LPSPropTagArray  FAR * lpPropTagArray
);

Returns a list of columns for the table.

ulFlags
Bitmask of flags that indicate which column set should be returned. The following flag can be set:
TBL_ALL_COLUMNS Returns all available columns.
lpPropTagArray
Address of an SPropTagArray structure containing the property tags for the column set.

IABTable::QueryPosition

HRESULT QueryPosition(
    ULONG FAR * lpulRow,
    ULONG FAR * lpulNumerator,
    ULONG FAR * lpulDenominator
);

Gets the current table cursor position, based on a fractional value.

lpulRow
Address of the value that contains the current row number. The row numbers are zero-based in position; row zero is the first row.
lpulNumerator
Address of the value that contains the fractional numerator part of the table position.
lpulDenominator
Address of the value that contains the fractional denominator part of the table position. The lpulDenominator parameter cannot be zero.

IABTable::QueryRows

HRESULT QueryRows(
    LONG lRowCount,
    ULONG ulFlags,
    LPSRowSet FAR * lppRows
);

Gets rows of data from a table.

lRowCount
Number of rows requested. If positive, rows are read starting at the current position and reading forward. If negative, the cursor position moves backward the indicated number of rows, then reads in forward order.
ulFlags
Flags specifying advancement of the cursor operation. TBL_NOADVANCE prevents the cursor from advancing. Default is that the cursor will advance past the last returned row.
lppRows
Returned SRowSet structure. This buffer must be freed by the caller according to the rules specified in the following comments.

The cRows member in the SRowSet structure returned in lppRows indicates the number of rows returned. If zero rows are returned, there are no more rows to return.

Freeing of the SRowSet structure returned by QueryRows is unusual in that each row must be freed independently; the rows are not allocated with AllocateMore. Memory used for the properties held in the SRow structures that make up the SRowSet in the lppRows parameter and for the rgPropVals members of the ADRENTRY structure is separately allocated for each row, and memory for each row must be separately freed by a call to MAPIFreeBuffer. The SRowSet structure itself must also be freed. Thus, to free all the memory returned for 10 rows requires 11 calls to FreeBuffer. This process might seem complex, but freeing memory for each row separately enables implementations to free different rows at different times. However, when a call to QueryRows returns zero, indicating the beginning or end of the table, only the SRowSet structure itself needs to be freed.

IABTable::QuerySortOrder

HRESULT QuerySortOrder(
    LPSSortOrderSet FAR * lppSortCriteria
);

Retrieves the current sort order for the table.

lppSortCriteria
Address of the SSortOrderSet structure holding the current sort order.

IABTable::Restrict

HRESULT Restrict(
    lpRestriction,
    ulFlags
);

Applies a restriction to a table, reducing the rows visible to only those matching the restriction criteria.

lpRestriction
Address of an SRestriction structure defining the conditions of the restriction. Passing NULL removes the current restriction.
ulFlags
Flags specifying asynchronous operation. For Internet Explorer Address Book, this value must be zero.

IABTable::SeekRow

HRESULT SeekRow(
    BOOKMARK bkOrigin,
    LONG lRowCount,
    LONG FAR * lplRowsSought
);

Moves the table cursor to a specific position.

bkOrigin
Bookmark identifying the starting position for the seek operation. A bookmark can be created using the CreateBookmark method, or one of the following predefined values can be passed:
BOOKMARK_BEGINNING Starts the seek operation from the beginning of the table.
BOOKMARK_CURRENT Starts the seek operation from the row in the table where the cursor is located.
BOOKMARK_END Starts the seek operation from the end of the table.
lRowCount
Signed count of the number of rows to move, starting from the bookmark identified by the bkOrigin parameter.
lplRowsSought
If lplRowsSought is a valid pointer on input, on output it points to the number of rows that were processed in the seek operation. If lplRowsSought is NULL on input, the indication is the caller is not interested in the number of rows processed, and nothing is returned on output.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.