libmapi/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, struct SPropTagArray *SPropTagArray, struct SPropValue **lpProps, uint32_t *PropCount)
_PUBLIC_ enum MAPISTATUS GetPropsAll (mapi_object_t *obj, 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, struct SPropValue *lpProps, unsigned long PropCount)
_PUBLIC_ enum MAPISTATUS SetProps (mapi_object_t *obj, 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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:
GetIDsFromNames, QueryNamesFromIDs, mapi_nameid_new

References mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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,
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
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, mapi_provider::ctx, mapi_session::emsmdb, emsmdb_get_SPropValue(), emsmdb_transaction(), GetIDsFromNames(), global_mapi_ctx, mapi_ctx::lp_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(), MAPIFreeBuffer(), mapi_nameid::nameid, OPENCHANGE_CHECK_NOTIFICATION, and OPENCHANGE_RETVAL_IF.

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

_PUBLIC_ enum MAPISTATUS GetPropsAll ( mapi_object_t obj,
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
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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, mapi_object_get_handle(), mapi_object_get_logon_id(), mapi_object_get_session(), 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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 mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), global_mapi_ctx, 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,
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
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, mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), GetIDsFromNames(), global_mapi_ctx, 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(), MAPIFreeBuffer(), mapi_nameid::nameid, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS SetProps ( mapi_object_t obj,
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
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, mapi_provider::ctx, mapi_session::emsmdb, emsmdb_transaction(), GetIDsFromNames(), global_mapi_ctx, 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(), 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/