
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.
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.
Currently not implemented in Internet Explorer Address Book.
Currently not implemented in Internet Explorer Address Book.
Currently not implemented in Internet Explorer Address Book.
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.
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:
HRESULT DeleteEntries(
LPENTRYLIST lpEntries,
ULONG ulFlags
);
Removes one or more entries from the address book container.
Currently not implemented in Internet Explorer Address Book.
HRESULT GetContentsTable(
ULONG ulFlags,
LPMAPITABLE FAR * lppTable
);
Returns a pointer to the contents table of the container.
| S_OK | The contents table was successfully retrieved. |
| MAPI_E_BAD_CHARWIDTH | Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode. |
| MAPI_E_NO_SUPPORT | The container has no contents and cannot provide a contents table. |
| 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. |
Currently not implemented in Internet Explorer Address Book.
Currently not implemented in Internet Explorer Address Book.
Currently not implemented in Internet Explorer Address Book.
Currently not implemented in Internet Explorer Address Book.
Currently not implemented in Internet Explorer Address Book.
Currently not implemented in Internet Explorer Address Book.
Currently not implemented in Internet Explorer Address Book.
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.
| 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. |
Currently not implemented in Internet Explorer Address Book.
HRESULT ResolveNames(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags,
LPADRLIST lpAdrList,
LPFlagList lpFlagList
);
Resolves entries against the address book container.
Note Must be zero in the first version of Internet Explorer Address Book.
| 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.
Currently not implemented in Internet Explorer Address Book.
Currently not implemented in Internet Explorer Address Book.
Currently not implemented in Internet Explorer Address Book.
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.
Currently not implemented by Internet Explorer Address Book.
Currently not implemented by Internet Explorer Address Book.
Currently not implemented by Internet Explorer Address Book.
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.
Currently not implemented by Internet Explorer Address Book.
HRESULT FindRow(
LPSRestriction lpRestriction,
BOOKMARK BkOrigin,
ULONG ulFlags
);
Find the next row in a table that contains a property matching the specified criteria.
| S_OK | The find operation was successful. |
| MAPI_E_INVALID_BOOKMARK | The bookmark in the BkOrigin parameter is invalid because it has been removed or because it is beyond the last row requested. |
| MAPI_E_NOT_FOUND | No rows were found that matched the restriction. |
| MAPI_W_POSITION_CHANGED | The call succeeded, but the bookmark used in the operation is no longer set at the same row as when it was last used; if the bookmark has not been used, it is no longer in the same position as when it was created. When this warning is returned, the call should be handled as successful. To test for this warning, use the FAILED macro. |
| 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. |
| DIR_BACKWARD | Searches backward from the row identified by the bookmark. |
HRESULT FreeBookmark(
BOOKMARK bkPosition
);
Provides the ability to free a bookmark that was created by CreateBookmark.
Currently not implemented by Internet Explorer Address Book.
Currently not implemented by Internet Explorer Address Book.
HRESULT GetRowCount(
ULONG ulFlags,
ULONG FAR *lpulCount
);
Returns the total number of rows in a table view.
| S_OK | The row count was successfully returned. |
| MAPI_E_BUSY | Another operation is in progress that prevents the row count retrieval operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped. |
| MAPI_E_NO_SUPPORT | The table cannot calculate the number of rows. |
| MAPI_W_APPROX_COUNT | The call succeeded, but an approximate row count was returned because the exact row count could not be determined, possibly due to memory constraints. To test for this warning, use the FAILED macro. |
Currently not implemented by Internet Explorer Address Book.
HRESULT QueryColumns(
ULONG ulFlags,
LPSPropTagArray FAR * lpPropTagArray
);
Returns a list of columns for the table.
| S_OK | The column set was successfully returned. |
| MAPI_E_BUSY | Another operation is in progress that prevents the column set retrieval operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped. |
| TBL_ALL_COLUMNS | Returns all available columns. |
HRESULT QueryPosition(
ULONG FAR * lpulRow,
ULONG FAR * lpulNumerator,
ULONG FAR * lpulDenominator
);
Gets the current table cursor position, based on a fractional value.
HRESULT QueryRows(
LONG lRowCount,
ULONG ulFlags,
LPSRowSet FAR * lppRows
);
Gets rows of data from a table.
| S_OK | The rows were successfully returned. |
| MAPI_E_BUSY | Another operation is in progress that prevents the row retrieval operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped. |
| MAPI_E_INVALID_PARAMETER | The lRowCount parameter is set to zero. |
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.
HRESULT QuerySortOrder(
LPSSortOrderSet FAR * lppSortCriteria
);
Retrieves the current sort order for the table.
| S_OK | The current sort order was successfully returned. |
| MAPI_E_BUSY | Another operation is in progress that prevents the sort order retrieval operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped. |
HRESULT Restrict(
lpRestriction,
ulFlags
);
Applies a restriction to a table, reducing the rows visible to only those matching the restriction criteria.
| S_OK | The filter was successfully applied. |
| MAPI_E_BUSY | Another operation is in progress that prevents the restriction operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped. |
| MAPI_E_TOO_COMPLEX | The table cannot perform the operation because the particular filter pointed to by the lpRestriction parameter is too complicated. |
HRESULT SeekRow(
BOOKMARK bkOrigin,
LONG lRowCount,
LONG FAR * lplRowsSought
);
Moves the table cursor to a specific position.
| S_OK | The seek operation was successful. |
| MAPI_E_BUSY | Another operation is in progress that prevents the row seeking operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped. |
| MAPI_E_INVALID_BOOKMARK | The bookmark specified in the bkOrigin parameter is invalid because it has been removed or because it is beyond the last row requested. |
| MAPI_W_POSITION_CHANGED | The call succeeded, but the bookmark specified in the bkOrigin parameter is no longer set at the same row as when it was last used. If the bookmark has not been used, it is no longer in the same position as when it was created. When this warning is returned, the call should be handled as successful. To test for this warning, use the FAILED macro. |
| 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. |
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.