MAPIClientLibraries 2.0 API Documentation

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

- File List
- Globals

Functions
property.c File Reference

Functions for manipulating MAPI properties. More...

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

## Functions
_PUBLIC_ uint32_t | cast_mapi_SPropValue (TALLOC_CTX *mem_ctx, struct mapi_SPropValue *mapi_sprop, struct SPropValue *sprop)
_PUBLIC_ void | cast_PropertyRow_to_SRow (TALLOC_CTX *mem_ctx, struct PropertyRow_r *proprow, struct SRow *srow)
_PUBLIC_ void | cast_PropertyRowSet_to_SRowSet (TALLOC_CTX *mem_ctx, struct PropertyRowSet_r *prowset, struct SRowSet *srowset)
_PUBLIC_ void | cast_PropertyValue_to_SPropValue (struct PropertyValue_r *propvalue, struct SPropValue *spropvalue)
_PUBLIC_ uint32_t | cast_SPropValue (TALLOC_CTX *mem_ctx, struct mapi_SPropValue *mapi_sprop, struct SPropValue *sprop)
_PUBLIC_ struct AddressBookEntryId * | get_AddressBookEntryId (TALLOC_CTX *mem_ctx, struct Binary_r *bin)
_PUBLIC_ struct FolderEntryId * | get_FolderEntryId (TALLOC_CTX *mem_ctx, struct Binary_r *bin)
_PUBLIC_ struct GlobalObjectId * | get_GlobalObjectId (TALLOC_CTX *mem_ctx, struct Binary_r *bin)
_PUBLIC_ struct MessageEntryId * | get_MessageEntryId (TALLOC_CTX *mem_ctx, struct Binary_r *bin)
_PUBLIC_ struct PtypServerId * | get_PtypServerId (TALLOC_CTX *mem_ctx, struct Binary_r *bin)
_PUBLIC_ struct RecurrencePattern * | get_RecurrencePattern (TALLOC_CTX *mem_ctx, struct Binary_r *bin)
_PUBLIC_ struct TimeZoneStruct * | get_TimeZoneStruct (TALLOC_CTX *mem_ctx, struct Binary_r *bin)
_PUBLIC_ const char * | get_TypedString (struct TypedString *tstring)
size_t | get_utf8_utf16_conv_length (const char *inbuf)
_PUBLIC_ void | mapi_copy_spropvalues (TALLOC_CTX *mem_ctx, struct SPropValue *source_values, struct SPropValue *dest_values, uint32_t count)
_PUBLIC_ enum MAPISTATUS | PropertyRow_addprop (struct PropertyRow_r *aRow, struct PropertyValue_r propValue)
_PUBLIC_ uint32_t | PropertyRowSet_propcpy (TALLOC_CTX *mem_ctx, struct PropertyRowSet_r *RowSet, struct PropertyValue_r value)
_PUBLIC_ struct SPropTagArray * | set_SPropTagArray (TALLOC_CTX *mem_ctx, uint32_t PropCount,...)
_PUBLIC_ enum MAPISTATUS | SPropTagArray_add (TALLOC_CTX *mem_ctx, struct SPropTagArray *SPropTagArray, enum MAPITAGS aulPropTag)
_PUBLIC_ enum MAPISTATUS | SPropTagArray_delete (TALLOC_CTX *mem_ctx, struct SPropTagArray *SPropTagArray, uint32_t aulPropTag)
_PUBLIC_ enum MAPISTATUS | SPropTagArray_find (struct SPropTagArray SPropTagArray, enum MAPITAGS aulPropTag, uint32_t *propIdx)
_PUBLIC_ enum MAPISTATUS | SRow_addprop (struct SRow *aRow, struct SPropValue spropvalue)
_PUBLIC_ uint32_t | SRowSet_propcpy (TALLOC_CTX *mem_ctx, struct SRowSet *SRowSet, struct SPropValue spropvalue)

## Detailed Description

Functions for manipulating MAPI properties.

## Function Documentation

_PUBLIC_ uint32_t cast_mapi_SPropValue | ( | TALLOC_CTX * | mem_ctx,
|  | struct mapi_SPropValue * | mapi_sprop,
|  | struct SPropValue * | sprop
| ) |  |

Convenience function to convert a SPropValue structure into a mapi_SPropValue structure and return the associated size.

Parameters

  mem_ctx | pointer to the memory context to use for allocation
  mapi_sprop | pointer to the MAPI SPropValue structure to copy data to
  sprop | pointer to the SPropValue structure to copy data from

Returns
  size of the converted data on success, otherwise 0

References get_utf8_utf16_conv_length().

Referenced by ModifyRecipients(), SetPropertiesNoReplicate(), and SetProps().

_PUBLIC_ void cast_PropertyRow_to_SRow | ( | TALLOC_CTX * | mem_ctx,
|  | struct PropertyRow_r * | proprow,
|  | struct SRow * | srow
| ) |  |

Convenience function to convert a PropertyRow_r structure into a SRow structure.

Parameters

  mem_ctx | pointer to the allocation context for structure members
  proprow | pointer to the PropertyRow_r structure to copy data to
  srow | pointer to the SRow structure to copy data from

References cast_PropertyValue_to_SPropValue().

Referenced by cast_PropertyRowSet_to_SRowSet().

_PUBLIC_ void cast_PropertyRowSet_to_SRowSet | ( | TALLOC_CTX * | mem_ctx,
|  | struct PropertyRowSet_r * | prowset,
|  | struct SRowSet * | srowset
| ) |  |

Convenience function to convert a PropertyRowSet_r structure into a SRowSet structure.

Parameters

  mem_ctx | pointer to the allocation context for structure members
  prowset | pointer to the PropertyRowSet_r structure to copy data to
  setrowset | pointer to the SRowSet structure to copy data from

References cast_PropertyRow_to_SRow().

_PUBLIC_ void cast_PropertyValue_to_SPropValue | ( | struct PropertyValue_r * | propvalue,
|  | struct SPropValue * | spropvalue
| ) |  |

Convenience function to convert a PropertyValue_r structure into a SPropValue structure.

Parameters

  propvalue | pointer to the PropertyValue_r structure to copy data to
  spropvalue | pointer to the SPropValue structure to copy data from

Referenced by cast_PropertyRow_to_SRow().

_PUBLIC_ uint32_t cast_SPropValue | ( | TALLOC_CTX * | mem_ctx,
|  | struct mapi_SPropValue * | mapi_sprop,
|  | struct SPropValue * | sprop
| ) |  |

Convenience function to convert a mapi_SPropValue structure into a SPropValue structure and return the associated size

Parameters

  mem_ctx | pointer to the memory context to use for allocation
  mapi_sprop | pointer to the MAPI SPropValue structure to copy data from
  sprop | pointer to the SPropValue structure to copy data to

Returns
  size of the converted data on success, otherwise 0

References get_utf8_utf16_conv_length().

_PUBLIC_ struct AddressBookEntryId* get_AddressBookEntryId | ( | TALLOC_CTX * | mem_ctx,
|  | struct Binary_r * | bin
| ) |  |
| read

Retrieve a AddressBookEntryId structure from a binary blob

Parameters

  mem_ctx | pointer to the memory context
  bin | pointer to the Binary_r structure with raw AddressBookEntryId data

Returns
  Allocated AddressBookEntryId structure on success, otherwise NULL

Note
  Developers must free the allocated AddressBookEntryId when finished.

_PUBLIC_ struct FolderEntryId* get_FolderEntryId | ( | TALLOC_CTX * | mem_ctx,
|  | struct Binary_r * | bin
| ) |  |
| read

Retrieve a FolderEntryId structure from a binary blob

Parameters

  mem_ctx | pointer to the memory context
  bin | pointer to the Binary_r structure with raw FolderEntryId data

Returns
  Allocated FolderEntryId structure on success, otherwise NULL

Note
  Developers must free the allocated FolderEntryId when finished.

_PUBLIC_ struct GlobalObjectId* get_GlobalObjectId | ( | TALLOC_CTX * | mem_ctx,
|  | struct Binary_r * | bin
| ) |  |
| read

Retrieve a GlobalObjectId structure from a binary blob

Parameters

  mem_ctx | pointer to the memory context
  bin | pointer to the Binary_r structure with raw GlobalObjectId data

Returns
  Allocated GlobalObjectId structure on success, otherwise NULL

Note
  Developers must free the allocated GlobalObjectId when finished.

_PUBLIC_ struct MessageEntryId* get_MessageEntryId | ( | TALLOC_CTX * | mem_ctx,
|  | struct Binary_r * | bin
| ) |  |
| read

Retrieve a MessageEntryId structure from a binary blob

Parameters

  mem_ctx | pointer to the memory context
  bin | pointer to the Binary_r structure with raw MessageEntryId data

Returns
  Allocated MessageEntryId structure on success, otherwise NULL

Note
  Developers must free the allocated MessageEntryId when finished.

_PUBLIC_ struct PtypServerId* get_PtypServerId | ( | TALLOC_CTX * | mem_ctx,
|  | struct Binary_r * | bin
| ) |  |
| read

Retrieve a PtypServerId structure from a binary blob

Parameters

  mem_ctx | pointer to the memory context
  bin | pointer to the Binary_r structure with raw PtypServerId data

Returns
  Allocated PtypServerId structure on success, otherwise NULL

Note
  Developers must free the allocated PtypServerId when finished.

_PUBLIC_ struct RecurrencePattern* get_RecurrencePattern | ( | TALLOC_CTX * | mem_ctx,
|  | struct Binary_r * | bin
| ) |  |
| read

Retrieve a RecurrencePattern structure from a binary blob

Parameters

  mem_ctx | pointer to the memory context
  bin | pointer to the Binary_r structure with non-mapped reccurrence data

Returns
  Allocated RecurrencePattern structure on success, otherwise NULL

Note
  Developers must free the allocated RecurrencePattern when finished.

_PUBLIC_ struct TimeZoneStruct* get_TimeZoneStruct | ( | TALLOC_CTX * | mem_ctx,
|  | struct Binary_r * | bin
| ) |  |
| read

Retrieve a TimeZoneStruct structure from a binary blob

Parameters

  mem_ctx | pointer to the memory context
  bin | pointer to the Binary_r structure with raw TimeZoneStruct data

Returns
  Allocated TimeZoneStruct structure on success, otherwise NULL

Note
  Developers must free the allocated TimeZoneStruct when finished.

_PUBLIC_ const char* get_TypedString | ( | struct TypedString * | tstring | ) |

Return the effective value used in a TypedString structure.

Parameters

  tstring | pointer to TypedString structure

Returns
  pointer to a valid string on success, otherwise NULL

Referenced by OpenMessage().

size_t get_utf8_utf16_conv_length | ( | const char * | inbuf | ) |

Return the expected size of the utf8 string after conversion to utf16 by iconv() function.

Parameters

  inbuf | pointer to the input string

Returns
  expected length of the converted string

Note
  This routine is based upon utf8_pull() function from samba4/lib/util/charset/iconv.c

Referenced by cast_mapi_SPropValue(), cast_SPropValue(), CopyFolder(), CreateFolder(), GetIDsFromNames(), mapi_nameid_canonical_add(), mapi_nameid_custom_string_add(), mapi_nameid_lid_add(), mapi_nameid_OOM_add(), mapi_nameid_string_add(), ModifyRecipients(), and MoveFolder().

_PUBLIC_ void mapi_copy_spropvalues | ( | TALLOC_CTX * | mem_ctx,
|  | struct SPropValue * | source_values,
|  | struct SPropValue * | dest_values,
|  | uint32_t | count
| ) |  |

Convenience function to copy an array of struct SPropValue or a part thereof into another array, by duplicating and properly parenting pointer data. The destination array is considered to be preallocated.

_PUBLIC_ enum MAPISTATUS PropertyRow_addprop | ( | struct PropertyRow_r * | aRow,
|  | struct PropertyValue_r | propValue
| ) |  |

add a PropertyValue_r structure to a PropertyRow_r array

Parameters

  aRow | pointer to the PropertyRow_r array where propValue should be appended
  propValue | the PropertyValue_r structure to add to aRow

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI_E_INVALID_PARAMETER.

_PUBLIC_ uint32_t PropertyRowSet_propcpy | ( | TALLOC_CTX * | mem_ctx,
|  | struct PropertyRowSet_r * | RowSet,
|  | struct PropertyValue_r | value
| ) |  |

Append a PropertyValue_r structure to given PropertyRowSet_r

Parameters

  mem_ctx | pointer to the memory context
  RowSet | pointer to the PropertyRowSet_r array to update
  value | the PropertyValue_r to append within SRowSet

Returns
  0 on success, otherwise 1

_PUBLIC_ struct SPropTagArray* set_SPropTagArray | ( | TALLOC_CTX * | mem_ctx,
|  | uint32_t | PropCount,
|  |  | ...
| ) |  |
| read

Create a property tag array

Parameters

  mem_ctx | talloc memory context to use for allocation
  PropCount | the number of properties in the array

The varargs (the third and subsequent arguments) are the property tags to make up the array. So the normal way to use this to create an array of two tags is like:

struct SPropTagArray *array
array = set_SPropTagArray(mem_ctx, 2, PR_ENTRYID, PR_DISPLAY_NAME);

Examples:
  fetchappointment.c, and fetchmail.c.

Referenced by AddUserPermission(), DuplicateProfile(), EntryIDFromSourceIDForMessage(), GetABRecipientInfo(), GetBestBody(), GetFolderItemsCount(), GetUserFreeBusyData(), ModifyUserPermission(), ProcessNetworkProfile(), and RemoveUserPermission().

_PUBLIC_ enum MAPISTATUS SPropTagArray_add | ( | TALLOC_CTX * | mem_ctx,
|  | struct SPropTagArray * | SPropTagArray,
|  | enum MAPITAGS | aulPropTag
| ) |  |

Add a property tag to an existing properties array

Parameters

  mem_ctx | talloc memory context to use for allocation
  SPropTagArray | existing properties array to add to
  aulPropTag | the property tag to add

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Possible MAPI error codes are:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_INVALID_PARAMETER: SPropTagArray parameter is not correctly set

Referenced by OpenEmbeddedMessage(), OpenMessage(), and ReloadCachedInformation().

_PUBLIC_ enum MAPISTATUS SPropTagArray_delete | ( | TALLOC_CTX * | mem_ctx,
|  | struct SPropTagArray * | SPropTagArray,
|  | uint32_t | aulPropTag
| ) |  |

Delete a property tag from an existing properties array

Parameters

  mem_ctx | talloc memory context to use for allocation
  SPropTagArray | existing properties array to remove from
  aulPropTag | the property tag to remove

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Possible MAPI error codes are:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_INVALID_PARAMETER: SPropTagArray parameter is not correctly set

_PUBLIC_ enum MAPISTATUS SPropTagArray_find | ( | struct SPropTagArray SPropTagArray | ,
|  | enum MAPITAGS | aulPropTag,
|  | uint32_t * | propIdx
| ) |  |

Return the index of a property tag in an existing properties array

Parameters

  SPropTagArray | existing properties array to remove from
  aulPropTag | the property tag to find
  propIdx | the index of the found property (undefined when MAPI_E_NOT_FOUND is returned)

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

Note
  Possible MAPI error codes are:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_INVALID_PARAMETER: SPropTagArray parameter is not correctly set

_PUBLIC_ enum MAPISTATUS SRow_addprop | ( | struct SRow * | aRow,
|  | struct SPropValue | spropvalue
| ) |  |

add a SPropValue structure to a SRow array

Parameters

  aRow | pointer to the SRow array where spropvalue should be appended
  spropvalue | reference to the SPropValue structure to add to aRow

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI_E_INVALID_PARAMETER.

Referenced by OpenEmbeddedMessage(), OpenMessage(), ReloadCachedInformation(), and SetRecipientType().

_PUBLIC_ uint32_t SRowSet_propcpy | ( | TALLOC_CTX * | mem_ctx,
|  | struct SRowSet * | SRowSet,
|  | struct SPropValue | spropvalue
| ) |  |

Append a SPropValue structure to given SRowSet

Parameters

  mem_ctx | pointer to the memory context
  SRowSet | pointer to the SRowSet array to update
  spropvalue | the SPropValue to append within SRowSet

Returns
  0 on success, otherwise 1

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