MAPIClientLibraries 2.0 API Documentation

- Main Page
- Related Pages
- Data Structures
- Files
- Examples

- File List
- Globals

Functions
IABContainer.c File Reference

Provides access to address book containers – Used to perform name resolution. More...

`#include "libmapi/libmapi.h"`
`#include "libmapi/libmapi_private.h"`

## Functions
_PUBLIC_ enum MAPISTATUS | GetABRecipientInfo (struct mapi_session *session, const char *username, struct SPropTagArray *pPropTags, struct PropertyRowSet_r **ppRowSet)
_PUBLIC_ enum MAPISTATUS | GetGALTable (struct mapi_session *session, struct SPropTagArray *SPropTagArray, struct PropertyRowSet_r **rowsetp, uint32_t count, uint8_t ulFlags)
_PUBLIC_ enum MAPISTATUS | GetGALTableCount (struct mapi_session *session, uint32_t *totalRecs)
_PUBLIC_ enum MAPISTATUS | ResolveNames (struct mapi_session *session, const char **usernames, struct SPropTagArray *props, struct PropertyRowSet_r **rowset, struct PropertyTagArray_r **flaglist, uint32_t flags)

## Detailed Description

Provides access to address book containers – Used to perform name resolution.

## Function Documentation

_PUBLIC_ enum MAPISTATUS GetABRecipientInfo | ( | struct mapi_session * | session,
|  | const char * | username,
|  | struct SPropTagArray * | pPropTags,
|  | struct PropertyRowSet_r ** | ppRowSet
| ) |  |

Retrieve Address Book information for a given recipient

Parameters

  session | pointer to the MAPI session context
  username | pointer to the username to retrieve information from
  pPropTags | pointer to the property tags array to lookup
  ppRowSet | pointer on pointer to the results

Note that if pPropTags is NULL, then GetABNameInfo will fetch the following default property tags:

1. PR_ADDRTYPE_UNICODE
2. PR_EMAIL_ADDRESS_UNICODE
3. PR_DISPLAY_NAME_UNICODE
4. PR_OBJECT_TYPE

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  1. MAPI_E_NOT_INITIALIZED if MAPI subsystem is not initialized
  2. MAPI_E_SESSION_LIMIT if the NSPI session is unavailable
  3. MAPI_E_INVALID_PARAMETER if a function parameter is invalid
  4. MAPI_E_NOT_FOUND if the username to lookup doesn't match any records

See Also
  nspi_DNToMId, nspi_GetProps

References MAPIFreeBuffer(), nspi_DNToMId(), nspi_GetProps(), ResolveNames(), and set_SPropTagArray().

Referenced by GetUserFreeBusyData().

_PUBLIC_ enum MAPISTATUS GetGALTable | ( | struct mapi_session * | session,
|  | struct SPropTagArray * | SPropTagArray,
|  | struct PropertyRowSet_r ** | rowsetp,
|  | uint32_t | count,
|  | uint8_t | ulFlags
| ) |  |

Retrieve the global address list

The Global Address List is the full list of email addresses (and other account-type things, such as "rooms" and distribution lists) accessible on the server. A user will usually have access to both a personal address book, and to the Global Address List. Public Address Book is another name for Global Address List.

You access the Global Address List by setting the list of things that you want to retrieve from the Global Address List as property names in the SPropTagArray argument, and then calling this function. The results are returned in SRowSet.

You can get a convenient output of the results using mapidump_PAB_entry() for each row returned.

Parameters

  session | pointer to the MAPI session context
  SPropTagArray | pointer to an array of MAPI properties we want to fetch
  SRowSet | pointer to the rows of the table returned
  count | the number of rows we want to fetch
  ulFlags | specify the table cursor location

Possible value for ulFlags:

1. TABLE_START: Fetch rows from the beginning of the table
2. TABLE_CUR: Fetch rows from current table location

The Global Address List may be quite large (tens of thousands of entries in a large deployment), so you usually call this function with ulFlags set to TABLE_START the first time, and then subsequent calls will be made with TABLE_CUR to progress through the table.

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  1. MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  2. MAPI_E_SESSION_LIMIT: No session has been opened on the provider
  3. MAPI_E_INVALID_PARAMETER: if a function parameter is invalid
  4. MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  MapiLogonEx, MapiLogonProvider, mapidump_PAB_entry

References nspi_QueryRows().

_PUBLIC_ enum MAPISTATUS GetGALTableCount | ( | struct mapi_session * | session,
|  | uint32_t * | totalRecs
| ) |  |

Retrieve the total number of records in the global address list

The Global Address List is the full list of email addresses (and other account-type things, such as "rooms" and distribution lists) accessible on the server. A user will usually have access to both a personal address book, and to the Global Address List. Public Address Book is another name for Global Address List.

Parameters

  session | pointer to the MAPI session context
  totalRecs | pointers to the total number of records in the global address list returned

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  1. MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  2. MAPI_E_SESSION_LIMIT: No session has been opened on the provider
  3. MAPI_E_INVALID_PARAMETER: if a function parameter is invalid
  4. MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

References nspi_QueryRows().

_PUBLIC_ enum MAPISTATUS ResolveNames | ( | struct mapi_session * | session,
|  | const char ** | usernames,
|  | struct SPropTagArray * | props,
|  | struct PropertyRowSet_r ** | rowset,
|  | struct PropertyTagArray_r ** | flaglist,
|  | uint32_t | flags
| ) |  |

Resolve user names against the Windows Address Book Provider

Parameters

  session | pointer to the MAPI session context
  usernames | list of user names to resolve
  rowset | resulting list of user details
  props | resulting list of resolved names
  flaglist | resulting list of resolution status (see below)
  flags | if set to MAPI_UNICODE then UNICODE MAPITAGS can be used, otherwise only UTF8 encoded fields may be returned.

Possible flaglist values are:

1. MAPI_UNRESOLVED: could not be resolved
2. MAPI_AMBIGUOUS: resolution match more than one entry
3. MAPI_RESOLVED: resolution matched a single entry

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  1. MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  2. MAPI_E_SESSION_LIMIT: No session has been opened on the provider
  3. MAPI_E_NOT_ENOUGH_RESOURCES: MAPI subsystem failed to allocate the necessary resources to operate properly
  4. MAPI_E_NOT_FOUND: No suitable profile database was found in the path pointed by profiledb

  5. MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

     It is the developer responsibility to call MAPIFreeBuffer on rowset and flaglist once they have finished to use them.

See Also
  MAPILogonProvider, GetLastError

References nspi_ResolveNames(), and nspi_ResolveNamesW().

Referenced by AddUserPermission(), GetABRecipientInfo(), ModifyUserPermission(), and RemoveUserPermission().

| This content is licensed under the Creative Commons Attribution ShareAlike License v. 3.0: http://creativecommons.org/licenses/by-sa/3.0/