MAPIClientLibraries 2.0 API Documentation

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

- File List
- Globals

Functions
IMAPIProp.c File Reference

Properties and named properties operations. More...

`#include "libmapi/libmapi.h"`

## Functions
_PUBLIC_ enum MAPISTATUS | CopyProps (mapi_object_t *obj_src, mapi_object_t *obj_dst, struct SPropTagArray *tags, uint8_t copyFlags, uint16_t *problemCount, struct PropertyProblem **problems)
_PUBLIC_ enum MAPISTATUS | CopyTo (mapi_object_t *obj_src, mapi_object_t *obj_dst, struct SPropTagArray *excludeTags, uint8_t copyFlags, uint16_t *problemCount, struct PropertyProblem **problems)
_PUBLIC_ enum MAPISTATUS | DeletePropertiesNoReplicate (mapi_object_t *obj, struct SPropTagArray *proptags)
_PUBLIC_ enum MAPISTATUS | DeleteProps (mapi_object_t *obj, struct SPropTagArray *proptags)
_PUBLIC_ enum MAPISTATUS | GetIDsFromNames (mapi_object_t *obj, uint16_t count, struct MAPINAMEID *nameid, uint32_t ulFlags, struct SPropTagArray **proptags)
_PUBLIC_ enum MAPISTATUS | GetNamesFromIDs (mapi_object_t *obj, enum MAPITAGS ulPropTag, uint16_t *count, struct MAPINAMEID **nameid)
_PUBLIC_ enum MAPISTATUS | GetPropList (mapi_object_t *obj, struct SPropTagArray *proptags)
_PUBLIC_ enum MAPISTATUS | GetProps (mapi_object_t *obj, uint32_t flags, struct SPropTagArray *SPropTagArray, struct SPropValue **lpProps, uint32_t *PropCount)
_PUBLIC_ enum MAPISTATUS | GetPropsAll (mapi_object_t *obj, uint32_t flags, struct mapi_SPropValue_array *properties)
_PUBLIC_ enum MAPISTATUS | QueryNamedProperties (mapi_object_t *obj, uint8_t queryFlags, struct GUID *guid, uint16_t *count, uint16_t **propID, struct MAPINAMEID **nameid)
_PUBLIC_ enum MAPISTATUS | SaveChangesAttachment (mapi_object_t *obj_parent, mapi_object_t *obj_child, enum SaveFlags flags)
_PUBLIC_ enum MAPISTATUS | SetPropertiesNoReplicate (mapi_object_t *obj, uint32_t flags, struct SPropValue *lpProps, unsigned long PropCount)
_PUBLIC_ enum MAPISTATUS | SetProps (mapi_object_t *obj, uint32_t flags, struct SPropValue *lpProps, unsigned long PropCount)

## Detailed Description

Properties and named properties operations.

## Function Documentation

_PUBLIC_ enum MAPISTATUS CopyProps | ( | mapi_object_t * | obj_src,
|  | mapi_object_t * | obj_dst,
|  | struct SPropTagArray * | tags,
|  | uint8_t | copyFlags,
|  | uint16_t * | problemCount,
|  | struct PropertyProblem ** | problems
| ) |  |

Copy properties from one object to another

This function copies (or moves) specified properties from one object to another.

Parameters

  obj_src | the object to copy properties from
  obj_dst | the object to set properties on
  copyFlags | flags to determine whether to copy or move, and whether to overwrite existing properties.
  tags | the list of properties to copy
  problemCount | (return value) number of entries in the problems array
  problems | (return value) array of problemCount entries.

The caller is responsible for freeing the problems array using MAPIFreeBuffer(). If the problemCount pointer is NULL, then the problems array will not be 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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  GetProps, SetProps, DeleteProps, CopyTo, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS CopyTo | ( | mapi_object_t * | obj_src,
|  | mapi_object_t * | obj_dst,
|  | struct SPropTagArray * | excludeTags,
|  | uint8_t | copyFlags,
|  | uint16_t * | problemCount,
|  | struct PropertyProblem ** | problems
| ) |  |

Copy multiple properties from one object to another

This function copies (or moves) properties from one object to another. Unlike CopyProperties, this function copies all properties except those identified.

Parameters

  obj_src | the object to copy properties from
  obj_dst | the object to set properties on
  excludeTags | the list of properties to not copy
  copyFlags | flags to determine whether to copy or move, and whether to overwrite existing properties.
  problemCount | (return value) number of entries in the problems array
  problems | (return value) array of problemCount entries.

The caller is responsible for freeing the problems array using MAPIFreeBuffer(). If the problemCount pointer is NULL, then the problems array will not be 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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  GetProps, SetProps, DeleteProps, CopyProps

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS DeletePropertiesNoReplicate | ( | mapi_object_t * | obj,
|  | struct SPropTagArray * | proptags
| ) |  |

Deletes property values from an object without invoking replication.

Parameters

  obj | the object to remove properties from
  proptags | the properties to remove from the given object

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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  DeleteProps

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS DeleteProps | ( | mapi_object_t * | obj,
|  | struct SPropTagArray * | proptags
| ) |  |

Delete one or more properties from an object

Parameters

  obj | the object to remove properties from
  proptags | the properties to remove from the given object

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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  SetProps, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS GetIDsFromNames | ( | mapi_object_t * | obj,
|  | uint16_t | count,
|  | struct MAPINAMEID * | nameid,
|  | uint32_t | ulFlags,
|  | struct SPropTagArray ** | proptags
| ) |  |

Provides the property identifiers that correspond to one or more property names.

Parameters

  obj | the object we are retrieving the identifiers from
  count | count of property names pointed to by the nameid parameter.
  nameid | pointer to an array of property names
  ulFlags | indicates how the property identifiers should be returned
  proptags | pointer to a pointer to an array of property tags containing existing or newly assigned property identifiers. Property types in this array are set to PT_NULL.

ulFlags can be set to:

- 0 retrieves named properties from the server
- MAPI_CREATE create the named properties if they don't exist on the server

Note
  count and nameid parameter can automatically be built using the mapi_nameid API.

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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  GetNamesFromIds, QueryNamesFromIDs, mapi_nameid_new

References get_utf8_utf16_conv_length(), mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

Referenced by GetProps(), mapi_nameid_GetIDsFromNames(), SetPropertiesNoReplicate(), and SetProps().

_PUBLIC_ enum MAPISTATUS GetNamesFromIDs | ( | mapi_object_t * | obj,
|  | enum MAPITAGS | ulPropTag,
|  | uint16_t * | count,
|  | struct MAPINAMEID ** | nameid
| ) |  |

Provides the property names that correspond to one or more property identifiers.

Parameters

  obj | the object we are retrieving the names from
  ulPropTag | the mapped property tag
  count | count of property names pointed to by the nameid parameter returned by the server
  nameid | pointer to a pointer to property names returned by the server

ulPropTag must be a property with type set to PT_NULL

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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  GetIDsFromNames, QueryNamesFromIDs

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS GetPropList | ( | mapi_object_t * | obj,
|  | struct SPropTagArray * | proptags
| ) |  |

Retrieve all the properties associated with a given object

Parameters

  obj | the object to retrieve properties for
  proptags | the resulting list of properties associated with the object

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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized

  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

    The developer MUST provide an allocated SPropTagArray structure to the function.

See Also
  GetProps, GetPropsAll, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS GetProps | ( | mapi_object_t * | obj,
|  | uint32_t | flags,
|  | struct SPropTagArray * | SPropTagArray,
|  | struct SPropValue ** | lpProps,
|  | uint32_t * | PropCount
| ) |  |

Returns values of one or more properties for an object

The function takes a pointer on the object obj, a MAPITAGS array specified in mapitags, and the count of properties. The function returns associated values within the SPropValue values pointer.

The array of MAPI property tags can be filled with both known and named properties.

Parameters

  obj | the object to get properties on
  flags | Flags for behaviour; can be bit-OR of MAPI_UNICODE and MAPI_PROPS_SKIP_NAMEDID_CHECK constants
  SPropTagArray | an array of MAPI property tags
  lpProps | the result of the query
  PropCount | the count of property tags

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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_INVALID_PARAMETER: obj or SPropTagArray are null, or the session context could not be obtained
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  SetProps, GetPropList, GetPropsAll, DeleteProps, GetLastError

References emsmdb_get_SPropValue(), GetIDsFromNames(), mapi_nameid_lookup_SPropTagArray(), mapi_nameid_map_SPropTagArray(), mapi_nameid_new(), mapi_nameid_unmap_SPropTagArray(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), and MAPIFreeBuffer().

Referenced by EntryIDFromSourceIDForMessage(), GetBestBody(), GetFolderItemsCount(), and GetUserFreeBusyData().

_PUBLIC_ enum MAPISTATUS GetPropsAll | ( | mapi_object_t * | obj,
|  | uint32_t | flags,
|  | struct mapi_SPropValue_array * | properties
| ) |  |

Retrieve all properties and values associated with an object

This function returns all the properties and and associated values for a given object.

Parameters

  obj | the object to get the properties for
  flags | Flags for behaviour; can be a MAPI_UNICODE constant
  properties | the properties / values for the object

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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  GetProps, GetPropList, GetLastError

Examples:
  fetchappointment.c, and fetchmail.c.

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS QueryNamedProperties | ( | mapi_object_t * | obj,
|  | uint8_t | queryFlags,
|  | struct GUID * | guid,
|  | uint16_t * | count,
|  | uint16_t ** | propID,
|  | struct MAPINAMEID ** | nameid
| ) |  |

Provides the property names that correspond to one or more property identifiers.

Parameters

  obj | the object to obtain the properties for
  queryFlags | A set of flags that can restrict the type of properties
  guid | a pointer to the GUID for the property set to fetch (null for all property sets.
  count | count of property names pointed to by the nameid and propID parameters returned by the server
  propID | pointer to an array of property IDs returned by the server
  nameid | pointer to an array of property names returned by the server

Note
  queryFlags can be NoStrings (0x1) or NoIds (0x2), neither or both. NoStrings will produce only ID properties, NoIds will produce only named properties, and both will result in no output.

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI error.

See Also
  GetNamesFromIDs

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS SaveChangesAttachment | ( | mapi_object_t * | obj_parent,
|  | mapi_object_t * | obj_child,
|  | enum SaveFlags | flags
| ) |  |

Makes permanent any changes made to an attachment since the last save operation.

Parameters

  obj_parent | the parent of the object to save changes for
  obj_child | the object to save changes for
  flags | the access flags to set on the saved object

Possible flags:

- KeepOpenReadOnly
- KeepOpenReadWrite
- ForceSave

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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  SetProps, ModifyRecipients, GetLastError

References mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_PUBLIC_ enum MAPISTATUS SetPropertiesNoReplicate | ( | mapi_object_t * | obj,
|  | uint32_t | flags,
|  | struct SPropValue * | lpProps,
|  | unsigned long | PropCount
| ) |  |

Set one or more properties on a given object without invoking replication.

This function sets one or more properties on a specified object. It is the same as SetProps, except if the object is a folder, where this function does not result in folder properties being replicated.

Parameters

  obj | the object to set properties on
  flags | Flags for behaviour; can be MAPI_PROPS_SKIP_NAMEDID_CHECK
  lpProps | the list of properties to set
  PropCount | the number of properties

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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_INVALID_PARAMETER: obj is not valid
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  SetProps, DeletePropertiesNoReplicate

References cast_mapi_SPropValue(), GetIDsFromNames(), mapi_nameid_lookup_SPropValue(), mapi_nameid_map_SPropValue(), mapi_nameid_new(), mapi_nameid_unmap_SPropValue(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), and MAPIFreeBuffer().

_PUBLIC_ enum MAPISTATUS SetProps | ( | mapi_object_t * | obj,
|  | uint32_t | flags,
|  | struct SPropValue * | lpProps,
|  | unsigned long | PropCount
| ) |  |

Set one or more properties on a given object

This function sets one or more properties on a specified object.

Parameters

  obj | the object to set properties on
  flags | Flags for behaviour; can be MAPI_PROPS_SKIP_NAMEDID_CHECK
  lpProps | the list of properties to set
  PropCount | the number of properties

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:
  - MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
  - MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See Also
  GetProps, GetPropList, GetPropsAll, DeleteProps, GetLastError

References cast_mapi_SPropValue(), GetIDsFromNames(), mapi_nameid_lookup_SPropValue(), mapi_nameid_map_SPropValue(), mapi_nameid_new(), mapi_nameid_unmap_SPropValue(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), and MAPIFreeBuffer().

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