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 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_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 emsmdb_transaction(), 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 emsmdb_transaction(), 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 emsmdb_transaction(), 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 emsmdb_transaction(), 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:
GetIDsFromNames, QueryNamesFromIDs, mapi_nameid_new

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

Referenced by GetProps(), mapi_nameid_GetIDsFromNames(), 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 emsmdb_transaction(), 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
See also:
GetProps, GetPropsAll, GetLastError

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

_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:
obj the object to get properties on
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(), emsmdb_transaction(), 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 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:
obj the object to get the properties for
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 emsmdb_transaction(), 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 emsmdb_transaction(), 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 emsmdb_transaction(), mapi_object_get_handle(), mapi_object_get_logon_id(), and mapi_object_get_session().

_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:
obj the object to set properties on
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 emsmdb_transaction(), 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().


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/