MAPIClientLibraries 2.0 API Documentation

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

- File List
- Globals

Functions
mapi_nameid.c File Reference

mapi_nameid convenience API More...

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

## Functions
_PUBLIC_ enum MAPISTATUS | mapi_nameid_canonical_add (struct mapi_nameid *mapi_nameid, uint32_t proptag)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_custom_lid_add (struct mapi_nameid *mapi_nameid, uint16_t lid, uint16_t propType, const char *OLEGUID)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_custom_string_add (struct mapi_nameid *mapi_nameid, const char *Name, uint16_t propType, const char *OLEGUID)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_GetIDsFromNames (struct mapi_nameid *mapi_nameid, mapi_object_t *obj, struct SPropTagArray *SPropTagArray)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_lid_add (struct mapi_nameid *mapi_nameid, uint16_t lid, const char *OLEGUID)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_lid_lookup (uint16_t lid, const char *OLEGUID, uint16_t *propType)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_lid_lookup_canonical (uint16_t lid, const char *OLEGUID, uint32_t *propTag)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_lookup_SPropTagArray (struct mapi_nameid *nameid, struct SPropTagArray *SPropTagArray)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_lookup_SPropValue (struct mapi_nameid *mapi_nameid, struct SPropValue *lpProps, unsigned long PropCount)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_map_SPropTagArray (struct mapi_nameid *mapi_nameid, struct SPropTagArray *SPropTagArray, struct SPropTagArray *SPropTagArray2)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_map_SPropValue (struct mapi_nameid *mapi_nameid, struct SPropValue *lpProps, uint32_t PropCount, struct SPropTagArray *SPropTagArray)
_PUBLIC_ struct mapi_nameid * | mapi_nameid_new (TALLOC_CTX *mem_ctx)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_OOM_add (struct mapi_nameid *mapi_nameid, const char *OOM, const char *OLEGUID)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_OOM_lookup (const char *OOM, const char *OLEGUID, uint16_t *propType)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_property_lookup (uint32_t proptag)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_SPropTagArray (struct mapi_nameid *mapi_nameid, struct SPropTagArray *SPropTagArray)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_string_add (struct mapi_nameid *mapi_nameid, const char *Name, const char *OLEGUID)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_string_lookup (const char *Name, const char *OLEGUID, uint16_t *propType)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_string_lookup_canonical (const char *Name, const char *OLEGUID, uint32_t *propTag)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_unmap_SPropTagArray (struct mapi_nameid *mapi_nameid, struct SPropTagArray *SPropTagArray)
_PUBLIC_ enum MAPISTATUS | mapi_nameid_unmap_SPropValue (struct mapi_nameid *mapi_nameid, struct SPropValue *lpProps, uint32_t PropCount)

## Detailed Description

mapi_nameid convenience API

## Function Documentation

_PUBLIC_ enum MAPISTATUS mapi_nameid_canonical_add | ( | struct mapi_nameid * | mapi_nameid,
|  | uint32_t | proptag
| ) |  |

Add a mapi_nameid entry given its canonical property tag

Parameters

  mapi_nameid | the structure where results are stored
  proptag | the canonical property tag we are searching

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_INITIALIZE: MAPI subsystem has not been initialized
  - MAPI_E_INVALID_PARAMETER: one of the parameters was not set properly
  - MAPI_E_NOT_FOUND: the entry intended to be added was not found

See Also
  mapi_nameid_new

References get_utf8_utf16_conv_length().

Referenced by mapi_nameid_lookup_SPropTagArray(), and mapi_nameid_lookup_SPropValue().

_PUBLIC_ enum MAPISTATUS mapi_nameid_custom_lid_add | ( | struct mapi_nameid * | mapi_nameid,
|  | uint16_t | lid,
|  | uint16_t | propType,
|  | const char * | OLEGUID
| ) |  |

Register and add a custom MNID_ID named property given its lid, proptype and OLEGUID.

Parameters

  mapi_nameid | the structure where results are stored
  lid | the light ID of the name property (used by MNID_ID named props only)
  propType | the named property type
  OLEGUID | the property set this entry belongs to

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: one of the parameter was no set properly

See Also
  mapi_nameid_new, mapi_nameid_lid_add

_PUBLIC_ enum MAPISTATUS mapi_nameid_custom_string_add | ( | struct mapi_nameid * | mapi_nameid,
|  | const char * | Name,
|  | uint16_t | propType,
|  | const char * | OLEGUID
| ) |  |

Register and add a custom MNID_STRING named property given its string, proptype and OLEGUID.

Parameters

  mapi_nameid | the structure where results are stored
  Name | the property name (used by MNID_STRING named props only)
  propType | the named property type
  OLEGUID | the property set this entry belongs to

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: one of the parameter was not set properly.

See Also
  mapi_nameid_new, mapi_nameid_string_add

References get_utf8_utf16_conv_length().

_PUBLIC_ enum MAPISTATUS mapi_nameid_GetIDsFromNames | ( | struct mapi_nameid * | mapi_nameid,
|  | mapi_object_t * | obj,
|  | struct SPropTagArray * | SPropTagArray
| ) |  |

Lookup named properties (MNID_STRING) and return their mapped proptags

This convenient function calls GetIDsFromNames() and returns property tags with their real property type.

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_INVALID_PARAMETER: one of the parameters was not set properly

See Also
  GetIDsFromNames, mapi_nameid_SPropTagArray

References GetIDsFromNames(), and GetLastError().

_PUBLIC_ enum MAPISTATUS mapi_nameid_lid_add | ( | struct mapi_nameid * | mapi_nameid,
|  | uint16_t | lid,
|  | const char * | OLEGUID
| ) |  |

Add a mapi_nameid entry given its lid and OLEGUID (MNID_ID)

Parameters

  mapi_nameid | the structure where results are stored
  lid | the light ID of the name property (used by MNID_ID named props only)
  OLEGUID | the property set this entry belongs to

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: one of the parameters was not set properly
  - MAPI_E_NOT_FOUND: the entry intended to be added was not found

See Also
  mapi_nameid_new

References get_utf8_utf16_conv_length().

_PUBLIC_ enum MAPISTATUS mapi_nameid_lid_lookup | ( | uint16_t | lid,
|  | const char * | OLEGUID,
|  | uint16_t * | propType
| ) |  |

Search for a given lid,OLEGUID couple and return the associated propType.

Parameters

  lid | the named property light ID
  OLEGUID | the named property GUID for this entry
  propType | pointer on returned named property type

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI_E_NOT_FOUND.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  - MAPI_E_INVALID_PARAMETER: one of the parameter was not set properly.
  - MAPI_E_NOT_FOUND: no named property found

_PUBLIC_ enum MAPISTATUS mapi_nameid_lid_lookup_canonical | ( | uint16_t | lid,
|  | const char * | OLEGUID,
|  | uint32_t * | propTag
| ) |  |

Search for a given lid,OLEGUID couple and return the associated canonical propTag.

Parameters

  lid | the named property light ID
  OLEGUID | the named property GUID for this entry
  propTag | pointer on returned named canonical property tag

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI_E_NOT_FOUND.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  - MAPI_E_INVALID_PARAMETER: one of the parameter was not set properly.
  - MAPI_E_NOT_FOUND: no named property found

_PUBLIC_ enum MAPISTATUS mapi_nameid_lookup_SPropTagArray | ( | struct mapi_nameid * | nameid,
|  | struct SPropTagArray * | SPropTagArray
| ) |  |

Loop over SPropTagArray and look for canonical named property tags we can add to the nameid structure.

Parameters

  nameid | the structure where results are stored
  SPropTagArray | the array of property tags where to look for canonical named 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_INVALID_PARAMETER: one of the parameters was not set properly
  - MAPI_E_NOT_FOUND: no named property found

See Also
  GetIDsFromNames

References mapi_nameid_canonical_add(), and mapi_nameid_property_lookup().

Referenced by GetProps().

_PUBLIC_ enum MAPISTATUS mapi_nameid_lookup_SPropValue | ( | struct mapi_nameid * | mapi_nameid,
|  | struct SPropValue * | lpProps,
|  | unsigned long | PropCount
| ) |  |

Loop over lpProps and look for canonical named property tags we can add to the nameid structure.

Parameters

  mapi_nameid | the structure where results are stored
  lpProps | pointer on a SPropValue structure with the property tags where to look for canonical named property tags
  PropCount | count of lpProps elemense

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_INVALID_PARAMETER: one of the parameters was not set properly
  - MAPI_E_NOT_FOUND: no named property found

See Also
  GetIDsFromNames

References mapi_nameid_canonical_add().

Referenced by SetPropertiesNoReplicate(), and SetProps().

_PUBLIC_ enum MAPISTATUS mapi_nameid_map_SPropTagArray | ( | struct mapi_nameid * | mapi_nameid,
|  | struct SPropTagArray * | SPropTagArray,
|  | struct SPropTagArray * | SPropTagArray2
| ) |  |

Replace named property tags in SPropTagArray with the property ID Exchange expects and stored in SPropTagArray2.

Parameters

  mapi_nameid | the structure where results are stored
  SPropTagArray | the array of property tags with original property tags
  SPropTagArray2 | the array of named property tags resolved with GetIDsFromNames

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_INVALID_PARAMETER: one of the parameters was not set properly

See Also
  GetIDsFromNames

Referenced by GetProps().

_PUBLIC_ enum MAPISTATUS mapi_nameid_map_SPropValue | ( | struct mapi_nameid * | mapi_nameid,
|  | struct SPropValue * | lpProps,
|  | uint32_t | PropCount,
|  | struct SPropTagArray * | SPropTagArray
| ) |  |

Replace named property tags in the SPropValue array with the property ID Exchange expects and stored in SPropTagArray.

Parameters

  mapi_nameid | the structure where results are stored
  lpProps | pointer on a SPropValue structure with property tags and values
  PropCount | count of lpProps elements
  SPropTagArray | the array of named property tags resolved with GetIDsFromNames

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_INVALID_PARAMETER: one of the parameters was not set properly

See Also
  GetIDsFromNames

Referenced by SetPropertiesNoReplicate(), and SetProps().

_PUBLIC_ struct mapi_nameid* mapi_nameid_new | ( | TALLOC_CTX * | mem_ctx | ) |
| read

Create a new mapi_nameid structure

Parameters

  mem_ctx | memory context to use for allocation

Returns
  a pointer to an allocated mapi_nameid structure on success, otherwise NULL

See Also
  GetIDsFromNames

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

_PUBLIC_ enum MAPISTATUS mapi_nameid_OOM_add | ( | struct mapi_nameid * | mapi_nameid,
|  | const char * | OOM,
|  | const char * | OLEGUID
| ) |  |

Add a mapi_nameid entry given its OOM and OLEGUID (MNID_ID|MNID_STRING)

Parameters

  mapi_nameid | the structure where results are stored
  OOM | the Outlook Object Model matching string
  OLEGUID | the property set this entry belongs to

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: one of the parameters was not set properly
  - MAPI_E_NOT_FOUND: the entry intended to be added was not found

See Also
  mapi_nameid_new

References get_utf8_utf16_conv_length().

_PUBLIC_ enum MAPISTATUS mapi_nameid_OOM_lookup | ( | const char * | OOM,
|  | const char * | OLEGUID,
|  | uint16_t * | propType
| ) |  |

Search for a given OOM,OLEGUID couple and return the associated propType.

Parameters

  OOM | The Outlook Object Model
  OLEGUID | the named property GUID for this entry
  propType | pointer on returned named property type

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI_E_NOT_FOUND.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  - MAPI_E_INVALID_PARAMETER: one of the parameter was not set properly.
  - MAPI_E_NOT_FOUND: no named property found

_PUBLIC_ enum MAPISTATUS mapi_nameid_property_lookup | ( | uint32_t | proptag | ) |

Search for a given referenced unmapped named property and return whether it was found or not.

Parameters

  proptag | the unmapped property tag to lookup

Returns
  MAPI_E_SUCCESS on success otherwise MAPI_E_NOT_FOUND

Referenced by mapi_nameid_lookup_SPropTagArray().

_PUBLIC_ enum MAPISTATUS mapi_nameid_SPropTagArray | ( | struct mapi_nameid * | mapi_nameid,
|  | struct SPropTagArray * | SPropTagArray
| ) |  |

set SPropTagArray ulPropTag property types from mapi_nameid returned by GetIDsFromNames()

Parameters

  mapi_nameid | the structure where results are stored
  SPropTagArray | the array of property tags returned by previous call to GetIDsFromNames()

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_INVALID_PARAMETER: one of the parameters was not set properly

See Also
  GetIDsFromNames

_PUBLIC_ enum MAPISTATUS mapi_nameid_string_add | ( | struct mapi_nameid * | mapi_nameid,
|  | const char * | Name,
|  | const char * | OLEGUID
| ) |  |

Add a mapi_nameid entry given its Name and OLEGUID (MNID_STRING)

Parameters

  mapi_nameid | the structure where results are stored
  Name | the property name (used by MNID_STRING named props only)
  OLEGUID | the property set this entry belongs to

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: one of the parameters was not set properly
  - MAPI_E_NOT_FOUND: the entry intended to be added was not found

See Also
  mapi_nameid_new

References get_utf8_utf16_conv_length().

_PUBLIC_ enum MAPISTATUS mapi_nameid_string_lookup | ( | const char * | Name,
|  | const char * | OLEGUID,
|  | uint16_t * | propType
| ) |  |

Search for a given Name,OLEGUID couple and return the associated propType.

Parameters

  Name | the named property name
  OLEGUID | the named property GUID for this entry
  propType | pointer on returned named property type

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI_E_NOT_FOUND.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  - MAPI_E_INVALID_PARAMETER: one of the parameter was not set properly.
  - MAPI_E_NOT_FOUND: no named property found

_PUBLIC_ enum MAPISTATUS mapi_nameid_string_lookup_canonical | ( | const char * | Name,
|  | const char * | OLEGUID,
|  | uint32_t * | propTag
| ) |  |

Search for a given Name,OLEGUID couple and return the associated canonical propTag.

Parameters

  Name | the named property name
  OLEGUID | the named property GUID for this entry
  propTag | pointer on returned named canonical property tag

Returns
  MAPI_E_SUCCESS on success, otherwise MAPI_E_NOT_FOUND.

Note
  Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:
  - MAPI_E_INVALID_PARAMETER: one of the parameter was not set properly.
  - MAPI_E_NOT_FOUND: no named property found

_PUBLIC_ enum MAPISTATUS mapi_nameid_unmap_SPropTagArray | ( | struct mapi_nameid * | mapi_nameid,
|  | struct SPropTagArray * | SPropTagArray
| ) |  |

Restore the original SPropTagArray array with the property tags saved in the mapi_nameid structure.

Parameters

  mapi_nameid | the structure where results are stored
  SPropTagArray | the array of property tags with original 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_INVALID_PARAMETER: one of the parameters was not set properly

See Also
  GetIDsFromNames

Referenced by GetProps().

_PUBLIC_ enum MAPISTATUS mapi_nameid_unmap_SPropValue | ( | struct mapi_nameid * | mapi_nameid,
|  | struct SPropValue * | lpProps,
|  | uint32_t | PropCount
| ) |  |

Restore the original SPropValue array with the property tags saved in the mapi_nameid structure.

Parameters

  mapi_nameid | the structure where results are stored
  lpProps | the array of SPropValue structures with original property tags
  PropCount | count of lpProps elements

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_INVALID_PARAMETER: one of the parameters was not set properly

See Also
  GetIDsFromNames

Referenced by SetPropertiesNoReplicate(), and SetProps().

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