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_srcthe object to copy properties from
obj_dstthe object to set properties on
copyFlagsflags to determine whether to copy or move, and whether to overwrite existing properties.
tagsthe 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 emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_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_srcthe object to copy properties from
obj_dstthe object to set properties on
excludeTagsthe list of properties to not copy
copyFlagsflags 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 emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

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

Deletes property values from an object without invoking replication.

Parameters
objthe object to remove properties from
proptagsthe 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 emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

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

Delete one or more properties from an object

Parameters
objthe object to remove properties from
proptagsthe 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 emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_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
objthe object we are retrieving the identifiers from
countcount of property names pointed to by the nameid parameter.
nameidpointer to an array of property names
ulFlagsindicates how the property identifiers should be returned
proptagspointer 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 emsmdb_transaction_wrapper(), get_utf8_utf16_conv_length(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, OPENCHANGE_RETVAL_IF, and PT_UNSPECIFIED.

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
objthe object we are retrieving the names from
ulPropTagthe mapped property tag
countcount of property names pointed to by the nameid parameter returned by the server
nameidpointer 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 emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

Referenced by mapi_SPropValue_array_named().

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

Retrieve all the properties associated with a given object

Parameters
objthe object to retrieve properties for
proptagsthe 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 emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_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
objthe object to get properties on
flagsFlags for behaviour; can be bit-OR of MAPI_UNICODE and MAPI_PROPS_SKIP_NAMEDID_CHECK constants
SPropTagArrayan array of MAPI property tags
lpPropsthe result of the query
PropCountthe 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 mapi_nameid::count, emsmdb_get_SPropValue(), emsmdb_transaction_wrapper(), GetIDsFromNames(), mapi_session::mapi_ctx, 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(), MAPI_PROPS_SKIP_NAMEDID_CHECK, MAPI_UNICODE, MAPIFreeBuffer(), mapi_nameid::nameid, OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

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
objthe object to get the properties for
flagsFlags for behaviour; can be a MAPI_UNICODE constant
propertiesthe 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 emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), MAPI_UNICODE, OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_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
objthe object to obtain the properties for
queryFlagsA set of flags that can restrict the type of properties
guida pointer to the GUID for the property set to fetch (null for all property sets.
countcount of property names pointed to by the nameid and propID parameters returned by the server
propIDpointer to an array of property IDs returned by the server
nameidpointer 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 emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_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_parentthe parent of the object to save changes for
obj_childthe object to save changes for
flagsthe 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 emsmdb_transaction_wrapper(), mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

_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
objthe object to set properties on
flagsFlags for behaviour; can be MAPI_PROPS_SKIP_NAMEDID_CHECK
lpPropsthe list of properties to set
PropCountthe 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(), mapi_nameid::count, emsmdb_transaction_wrapper(), 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(), MAPI_PROPS_SKIP_NAMEDID_CHECK, MAPIFreeBuffer(), mapi_nameid::nameid, and OPENCHANGE_RETVAL_IF.

_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
objthe object to set properties on
flagsFlags for behaviour; can be MAPI_PROPS_SKIP_NAMEDID_CHECK
lpPropsthe list of properties to set
PropCountthe 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(), mapi_nameid::count, emsmdb_transaction_wrapper(), 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(), MAPI_PROPS_SKIP_NAMEDID_CHECK, MAPIFreeBuffer(), mapi_nameid::nameid, OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.


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