MAPIClientLibraries 2.0 API Documentation

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

- File List
- Globals

Functions
nspi.c File Reference

Name Service Provider (NSPI) stack functions. More...

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

## Functions
_PUBLIC_ struct nspi_context * | nspi_bind (TALLOC_CTX *parent_ctx, struct dcerpc_pipe *p, struct cli_credentials *cred, uint32_t codepage, uint32_t language, uint32_t method)
_PUBLIC_ enum MAPISTATUS | nspi_CompareMIds (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t MId1, uint32_t MId2, uint32_t *plResult)
int | nspi_disconnect_dtor (void *data)
_PUBLIC_ enum MAPISTATUS | nspi_DNToMId (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, struct StringsArray_r *pNames, struct PropertyTagArray_r **ppMIds)
_PUBLIC_ enum MAPISTATUS | nspi_GetIDsFromNames (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, bool VerifyNames, uint32_t cNames, struct PropertyName_r *ppNames, struct SPropTagArray **ppPropTags)
_PUBLIC_ enum MAPISTATUS | nspi_GetMatches (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, struct SPropTagArray *pPropTags, struct Restriction_r *Filter, uint32_t ulRequested, struct PropertyRowSet_r **ppRows, struct PropertyTagArray_r **ppOutMIds)
_PUBLIC_ enum MAPISTATUS | nspi_GetNamesFromIDs (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, struct FlatUID_r *lpGuid, struct SPropTagArray *pPropTags, struct SPropTagArray **ppReturnedPropTags, struct PropertyNameSet_r **ppNames)
_PUBLIC_ enum MAPISTATUS | nspi_GetPropList (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, bool WantObject, uint32_t dwMId, struct SPropTagArray **ppPropTags)
_PUBLIC_ enum MAPISTATUS | nspi_GetProps (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, struct SPropTagArray *pPropTags, struct PropertyTagArray_r *MId, struct PropertyRowSet_r **SRowSet)
_PUBLIC_ enum MAPISTATUS | nspi_GetSpecialTable (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t Type, struct PropertyRowSet_r **ppRows)
_PUBLIC_ enum MAPISTATUS | nspi_GetTemplateInfo (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t dwFlags, uint32_t ulType, char *pDN, struct PropertyRow_r **ppData)
_PUBLIC_ enum MAPISTATUS | nspi_ModLinkAtt (struct nspi_context *nspi_ctx, bool Delete, uint32_t ulPropTag, uint32_t MId, struct BinaryArray_r *lpEntryIds)
_PUBLIC_ enum MAPISTATUS | nspi_ModProps (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t MId, struct SPropTagArray *pPropTags, struct PropertyRow_r *pRow)
_PUBLIC_ enum MAPISTATUS | nspi_QueryColumns (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, bool WantUnicode, struct SPropTagArray **ppColumns)
_PUBLIC_ enum MAPISTATUS | nspi_QueryRows (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, struct SPropTagArray *pPropTags, struct PropertyTagArray_r *MIds, uint32_t count, struct PropertyRowSet_r **ppRows)
_PUBLIC_ enum MAPISTATUS | nspi_ResolveNames (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, const char **usernames, struct SPropTagArray *pPropTags, struct PropertyRowSet_r ***pppRows, struct PropertyTagArray_r ***pppMIds)
_PUBLIC_ enum MAPISTATUS | nspi_ResolveNamesW (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, const char **usernames, struct SPropTagArray *pPropTags, struct PropertyRowSet_r ***pppRows, struct PropertyTagArray_r ***pppMIds)
_PUBLIC_ enum MAPISTATUS | nspi_ResortRestriction (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, enum TableSortOrders SortType, struct PropertyTagArray_r *pInMIds, struct PropertyTagArray_r **ppMIds)
_PUBLIC_ enum MAPISTATUS | nspi_SeekEntries (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, enum TableSortOrders SortType, struct PropertyValue_r *pTarget, struct SPropTagArray *pPropTags, struct PropertyTagArray_r *pMIds, struct PropertyRowSet_r **pRows)
_PUBLIC_ enum MAPISTATUS | nspi_unbind (struct nspi_context *nspi_ctx)
_PUBLIC_ enum MAPISTATUS | nspi_UpdateStat (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t *plDelta)

## Detailed Description

Name Service Provider (NSPI) stack functions.

## Function Documentation

_PUBLIC_ struct nspi_context* nspi_bind | ( | TALLOC_CTX * | parent_ctx,
|  | struct dcerpc_pipe * | p,
|  | struct cli_credentials * | cred,
|  | uint32_t | codepage,
|  | uint32_t | language,
|  | uint32_t | method
| ) |  |
| read

Initiates a session between a client and the NSPI server.

Parameters

  parent_ctx | pointer to the memory context
  p | pointer to the DCERPC pipe
  cred | pointer to the user credentials
  codepage | the code to set in the STAT structure
  language | the language to set in the STAT structure
  method | the method to set in the STAT structure

Returns
  Allocated pointer to a nspi_context structure on success, otherwise NULL

_PUBLIC_ enum MAPISTATUS nspi_CompareMIds | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | uint32_t | MId1,
|  | uint32_t | MId2,
|  | uint32_t * | plResult
| ) |  |

Compares the position in an address book container of two objects identified by MId and returns the value of the comparison

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  MId1 | the first MId to compare
  MId2 | the second MId to compare
  plResult | pointer to the value of the comparison

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

int nspi_disconnect_dtor | ( | void * | data | ) |

Destructor for the NSPI context. Call the NspiUnbind function.

Parameters

  data | generic pointer to data with mapi_provider information

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

References nspi_unbind().

Referenced by MapiLogonProvider().

_PUBLIC_ enum MAPISTATUS nspi_DNToMId | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | struct StringsArray_r * | pNames,
|  | struct PropertyTagArray_r ** | ppMIds
| ) |  |

Maps a set of DN to a set of MId

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  pNames | pointer to a StringsArray_r structure with the DN to map
  ppMIds | pointer on pointer to the returned list of MIds

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

Referenced by GetABRecipientInfo(), and ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS nspi_GetIDsFromNames | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | bool | VerifyNames,
|  | uint32_t | cNames,
|  | struct PropertyName_r * | ppNames,
|  | struct SPropTagArray ** | ppPropTags
| ) |  |

Retrieve the Property IDs associated with property names from the NSPI server.

Parameters

  nspi_ctx | pointer on the NSPI connection context
  mem_ctx | pointer to the memoty context
  VerifyNames | boolean value defining whether the NSPI server must verify that all client specified names are recognized by the server
  cNames | count of PropertyName_r entries
  ppNames | pointer to a PropertyName_r structure with the list of property tags supplied by the client
  ppPropTags | pointer on pointer to the list of proptags returned by the server

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

_PUBLIC_ enum MAPISTATUS nspi_GetMatches | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | struct SPropTagArray * | pPropTags,
|  | struct Restriction_r * | Filter,
|  | uint32_t | ulRequested,
|  | struct PropertyRowSet_r ** | ppRows,
|  | struct PropertyTagArray_r ** | ppOutMIds
| ) |  |

Returns an explicit table.

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  pPropTags | pointer to an array of property tags of columns
  Filter | pointer to the Restriction to apply to the table
  ulRequested | The upper limit for returned rows
  ppRows | pointer to pointer to a SRowSet structure holding the rows returned by the server
  ppOutMIds | pointer to pointer to a list of MId that comprise a restricted address book container

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error. If the resulting table rows count will be greater than ulRequested, then an error MAPI_E_TABLE_TOO_BIG is returned. Note, this error can be also returned when server limits for table size are exceeded.

Referenced by DuplicateProfile(), and ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS nspi_GetNamesFromIDs | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | struct FlatUID_r * | lpGuid,
|  | struct SPropTagArray * | pPropTags,
|  | struct SPropTagArray ** | ppReturnedPropTags,
|  | struct PropertyNameSet_r ** | ppNames
| ) |  |

Returns a list of property names for a set of proptags

Parameters

  nspi_ctx | pointer on the NSPI connection text
  mem_ctx | pointer to the memory context
  lpGuid | the property set about which the client is requesting information
  pPropTags | pointer to the proptags list
  ppReturnedPropTags | pointer on pointer to the list of all the proptags in the property set specified in lpGuid
  ppNames | pointer on pointer to the list of property names returned by the server

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

_PUBLIC_ enum MAPISTATUS nspi_GetPropList | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | bool | WantObject,
|  | uint32_t | dwMId,
|  | struct SPropTagArray ** | ppPropTags
| ) |  |

Returns a list of all the properties that have values on the specified object

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  WantObject | boolean value defining whether we want the server to include properties with the type set to PT_OBJECT
  dwMId | the MId of the specified object
  ppPropTags | pointer on pointer to the list of property tags associated to the object.

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

_PUBLIC_ enum MAPISTATUS nspi_GetProps | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | struct SPropTagArray * | pPropTags,
|  | struct PropertyTagArray_r * | MId,
|  | struct PropertyRowSet_r ** | SRowSet
| ) |  |

Returns an address book row containing a set of the properties and values that exists on an object

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  pPropTags | pointer to the list of property tags that the client wants to be returned
  MId | pointer to the MId of the record
  SRowSet | pointer on pointer to the row returned by the server

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

Referenced by GetABRecipientInfo(), and ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS nspi_GetSpecialTable | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | uint32_t | Type,
|  | struct PropertyRowSet_r ** | ppRows
| ) |  |

Returns the rows of a special table to the client. The special table can be a Hierarchy Table or an Address Creation Table

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  Type | bitmap of flags defining the type of the special table
  ppRows | pointer on pointer to the rows returned by the server

Possible values for Type:

1. NspiAddressCreationTemplates to access an Address Creation Table
2. NspiUnicodeStrings for strings to be returned in Unicode

If NspiAddressCreationTemplates is not set, then NspiGetSpecialTable will automatically fetch the Hierarchy Table.

If NspiAddressCreationTemplates is set, then NspiUnicodeStrings is ignored.

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Referenced by DuplicateProfile(), and ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS nspi_GetTemplateInfo | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | uint32_t | dwFlags,
|  | uint32_t | ulType,
|  | char * | pDN,
|  | struct PropertyRow_r ** | ppData
| ) |  |

Returns information about template objects in the address book.

Parameters

  nspi_ctx | pointer to the NSPI memory context
  mem_ctx | pointer to the memory context
  dwFlags | set of bit flags
  ulType | specifies the display type of the template
  pDN | the DN of the template requested
  ppData | pointer on pointer to the data requested

Possible values for dwFlags:

1. TI_TEMPLATE to return the template
2. TI_SCRIPT to return the script associated to the template
3. TI_EMT to return the e-mail type associated to the template
4. TI_HELPFILE_NAME to return the help file associated to the template
5. TI_HELPFILE_CONTENTS to return the contents of the help file associated to the template
   Returns
     MAPI_E_SUCCESS on success, otherwise MAPI error.

_PUBLIC_ enum MAPISTATUS nspi_ModLinkAtt | ( | struct nspi_context * | nspi_ctx,
|  | bool | Delete,
|  | uint32_t | ulPropTag,
|  | uint32_t | MId,
|  | struct BinaryArray_r * | lpEntryIds
| ) |  |

Modifies the values of a specific property of a specific row in the address book. This function only applies only to rows that support the PT_OBJECT Property Type.

Parameters

  nspi_ctx | pointer to the NSPI connection context
  Delete | boolean value defining whether the server must remove all values specified by the input parameter lpEntryIDs from the property specified by ulPropTag
  ulPropTag | property tag of the property the client wishes to modify
  MId | the MId of the address book object
  lpEntryIds | array of BinaryArray_r structures intended to be modified or deleted

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

_PUBLIC_ enum MAPISTATUS nspi_ModProps | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | uint32_t | MId,
|  | struct SPropTagArray * | pPropTags,
|  | struct PropertyRow_r * | pRow
| ) |  |

Modify the properties of an object in the address book

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  MId | the MId of the address book object
  pPropTags | pointer to the list of properties to be modified on the object
  pRow | Contains an address book row

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

_PUBLIC_ enum MAPISTATUS nspi_QueryColumns | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | bool | WantUnicode,
|  | struct SPropTagArray ** | ppColumns
| ) |  |

Returns a list of all the properties the NSPI server is aware off.

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  WantUnicode | whether we want UNICODE properties or not
  ppColumns | pointer on pointer to a property tag array

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

_PUBLIC_ enum MAPISTATUS nspi_QueryRows | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | struct SPropTagArray * | pPropTags,
|  | struct PropertyTagArray_r * | MIds,
|  | uint32_t | count,
|  | struct PropertyRowSet_r ** | ppRows
| ) |  |

Returns a number of Rows from a specified table.

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  pPropTags | pointer to the list of proptags that the client requires to be returned for each row.
  MIds | pointer to a list of values representing an Explicit table
  count | the number of rows requested
  ppRows | pointer on pointer to the the rows returned by the server

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

Referenced by GetGALTable(), GetGALTableCount(), and ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS nspi_ResolveNames | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | const char ** | usernames,
|  | struct SPropTagArray * | pPropTags,
|  | struct PropertyRowSet_r *** | pppRows,
|  | struct PropertyTagArray_r *** | pppMIds
| ) |  |

Takes a set of string values in an 8-bit character set and performs ANR on those strings

Parameters

  nspi_ctx | pointer on the NSPI connection context
  mem_ctx | pointer to the memory context
  usernames | pointer on pointer to the list of values we want to perform ANR on
  pPropTags | pointer on the property tags list we want for each row returned
  pppRows | pointer on pointer on pointer to the rows returned by the server
  pppMIds | pointer on pointer on pointer to the MIds matching the array of strings

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

Referenced by ResolveNames().

_PUBLIC_ enum MAPISTATUS nspi_ResolveNamesW | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | const char ** | usernames,
|  | struct SPropTagArray * | pPropTags,
|  | struct PropertyRowSet_r *** | pppRows,
|  | struct PropertyTagArray_r *** | pppMIds
| ) |  |

Takes a set of string values in the Unicode character set and performs ambiguous name resolution (ANR) on those strings

Parameters

  nspi_ctx | pointer on the NSPI connection context
  mem_ctx | pointer to the memory context
  usernames | pointer on pointer to the list of values we want to perform ANR on
  pPropTags | pointer on the property tags list we want for each row returned
  pppRows | pointer on pointer on pointer to the rows returned by the server
  pppMIds | pointer on pointer on pointer to the MIds matching the array of strings

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

Referenced by ResolveNames().

_PUBLIC_ enum MAPISTATUS nspi_ResortRestriction | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | enum TableSortOrders | SortType,
|  | struct PropertyTagArray_r * | pInMIds,
|  | struct PropertyTagArray_r ** | ppMIds
| ) |  |

Applies a sort order to the objects in a restricted address book container

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  SortType | the table sort order to use
  pInMIds | pointer on a list of MIds that comprise a restricted address book container
  ppMIds | pointer on pointer to the returned list of MIds that comprise a restricted address book container.

SortType can take the following values:

1. SortTypeDisplayName
2. SortTypePhoneticDisplayName

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

_PUBLIC_ enum MAPISTATUS nspi_SeekEntries | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | enum TableSortOrders | SortType,
|  | struct PropertyValue_r * | pTarget,
|  | struct SPropTagArray * | pPropTags,
|  | struct PropertyTagArray_r * | pMIds,
|  | struct PropertyRowSet_r ** | pRows
| ) |  |

Searches for and sets the logical position in a specific table to the first entry greater than or equal to a specified value. Optionally, it might also return information about rows in the table.

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  SortType | the table sort order to use
  pTarget | PropertyValue_r struct holding the value being sought
  pPropTags | pointer to an array of property tags of columns that the client wants to be returned for each row returned.
  pMIds | pointer to a list of Mid that comprise a restricted address book container
  pRows | pointer to pointer to a SRowSet structure holding the rows returned by the server

SortType can take the following values:

1. SortTypeDisplayName
2. SortTypePhoneticDisplayName

If pTarget property tag is not set accordingly to SortType, the function returns MAPI_E_INVALID_PARAMETER. Possible values are:

1. SortType set to SortTypeDisplayName and pTarget property tag set to PR_DISPLAY_NAME or PR_DISPLAY_UNICODE
2. SortType set to SortTypePhoneticDisplayName and pTarget property tag set to PR_EMS_AB_PHONETIC_DISPLAY_NAME or PR_EMS_AB_PHONETIC_DISPLAY_NAME_UNICODE

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

_PUBLIC_ enum MAPISTATUS nspi_unbind | ( | struct nspi_context * | nspi_ctx | ) |

Destroys the context handle

Parameters

  nspi_ctx | pointer to the NSPI connection context

Returns
  return 1 on success or 2 if the input context is NULL

Referenced by nspi_disconnect_dtor().

_PUBLIC_ enum MAPISTATUS nspi_UpdateStat | ( | struct nspi_context * | nspi_ctx,
|  | TALLOC_CTX * | mem_ctx,
|  | uint32_t * | plDelta
| ) |  |

Updates the STAT block representing position in a table to reflect positioning changes requested by the client.

Parameters

  nspi_ctx | pointer to the NSPI connection context
  mem_ctx | pointer to the memory context
  plDelta | pointer to an unsigned long indicating movement within the address book container specified by the input parameter pStat.

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error

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