libmapi/IUnknown.c File Reference

Various miscellaneous (ungrouped) functions. More...

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

Functions
_PUBLIC_ enum MAPISTATUS	GetIdFromLongTermId (mapi_object_t *obj, struct LongTermId long_term_id, mapi_id_t *id)
_PUBLIC_ enum MAPISTATUS	GetLastError (void)
_PUBLIC_ enum MAPISTATUS	GetLongTermIdFromId (mapi_object_t *obj, mapi_id_t id, struct LongTermId *long_term_id)
_PUBLIC_ enum MAPISTATUS	MAPIAllocateBuffer (struct mapi_context *mapi_ctx, uint32_t size, void **ptr)
_PUBLIC_ enum MAPISTATUS	MAPIFreeBuffer (void *ptr)
_PUBLIC_ enum MAPISTATUS	Release (mapi_object_t *obj)

---

Detailed Description

Various miscellaneous (ungrouped) functions.

---

Function Documentation

_PUBLIC_ enum MAPISTATUS GetIdFromLongTermId	(	mapi_object_t *	obj,
		struct LongTermId	long_term_id,
		mapi_id_t *	id
	)

Convert an Long Term Id into an Id

The function looks up the Id for a specified Long Term Id value.

Parameters:

	obj	the object to look up on
	long_term_id	the id to look up
	id	the id returned by the server

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 null
• MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See also:

GetLongTermIdFromId

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 GetLastError

(

void

)

Returns the latest error code.

This function returns the error code set by a previous function call.

Note:

Calls to this function may not work reliably in multi-threaded or multisession code. We suggest you capture the return value of the call, and check that instead.

Examples:

mapi_sample1.c.

Referenced by DuplicateProfile(), mapi_nameid_GetIDsFromNames(), OpenMsgStore(), and WrapCompressedRTFStream().

_PUBLIC_ enum MAPISTATUS GetLongTermIdFromId	(	mapi_object_t *	obj,
		mapi_id_t	id,
		struct LongTermId *	long_term_id
	)

Convert an ID to a Long Term Id

The function looks up the Long Term Id for a specified ID value.

Parameters:

	obj	the object to look up on
	id	the id to look up
	long_term_id	the long term ID returned from the server

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 null
• MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See also:

GetIdFromLongTermId

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 MAPIAllocateBuffer	(	struct mapi_context *	mapi_ctx,
		uint32_t	size,
		void **	ptr
	)

Allocate memory using the MAPI memory context

Parameters:

	mapi_ctx	pointer to the MAPI context
	size	the number of bytes to allocate
	ptr	pointer to the allocated byte region

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_SESSION_LIMIT: No session has been opened on the provider
• MAPI_E_NOT_ENOUGH_RESOURCES: MAPI subsystem failed to allocate the necessary resources to operate properly
• MAPI_E_INVALID_PARAMER: size is not set properly.

See also:

MAPIFreeBuffer, GetLastError

References mapi_context::mem_ctx, and OPENCHANGE_RETVAL_IF.

_PUBLIC_ enum MAPISTATUS MAPIFreeBuffer

(

void *

ptr

)

Free allocated memory

This function frees memory previously allocated with MAPIAllocateBuffer.

Parameters:

ptr

memory region to free

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_PARAMER: ptr is not set properly.

See also:

MAPIAllocateBuffer, GetLastError

Examples:

fetchappointment.c, and fetchmail.c.

References OPENCHANGE_RETVAL_IF.

Referenced by AddUserPermission(), DuplicateProfile(), FreeBookmark(), GetABRecipientInfo(), GetBestBody(), GetFolderItemsCount(), GetProps(), GetUserFreeBusyData(), Logoff(), ModifyUserPermission(), ProcessNetworkProfile(), RemoveUserPermission(), SetPropertiesNoReplicate(), and SetProps().

_PUBLIC_ enum MAPISTATUS Release

(

mapi_object_t *

obj

)

Release an object on the server

The function releases the object obj on the server.

Parameters:

obj

the object to release

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:

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.

Referenced by mapi_object_release(), and Unsubscribe().