MAPIFreeBuffer
The MAPIFreeBuffer
function frees a memory buffer allocated with a call to the MAPIAllocateBuffer function or the MAPIAllocateMore function.
Quick Info
|
Header
file: |
MAPIX.H |
|
Implemented
by: |
MAPI |
|
Called by: |
Client
applications and service providers |
ULONG MAPIFreeBuffer(
|
LPVOID lpBuffer |
|
|
); |
|
Parameters
lpBuffer
[in] Pointer
to a previously allocated memory buffer. If NULL is passed in the lpBuffer parameter,
MAPIFreeBuffer does nothing.
Return Values
S_OK
The call
succeeded and freed the memory requested. MAPIFreeBuffer can also return S_OK
on already freed locations or if memory block is not allocated with MAPIAllocateBuffer
and MAPIAllocateMore.
Remarks
Usually, when
a client application or service provider calls MAPIAllocateBuffer or MAPIAllocateMore, the operating system
constructs in one contiguous memory buffer one or more complex structures with
multiple levels of pointers. When a MAPI function or method creates a buffer
with such contents, a client can later free all the structures contained in the
buffer by passing to MAPIFreeBuffer the pointer to the buffer returned
by the MAPI function that created the buffer. For a service provider to free a
memory buffer using MAPIFreeBuffer, it must pass the pointer to that
buffer returned with the provider s
support object.
The call to MAPIFreeBuffer
to free a particular buffer must be made as soon as a client or provider is
finished using this buffer. Simply calling the MAPILogoff function at the end of a
MAPI session does not automatically release memory buffers.
A client or
service provider should operate on the assumption that the pointer passed in lpBuffer
is invalid after a successful return from MAPIFreeBuffer. If the
pointer indicates either a memory block not allocated by the messaging system
through MAPIAllocateBuffer or MAPIAllocateMore or a free memory
block, the behavior of MAPIFreeBuffer is undefined.
Note Passing a null
pointer to MAPIFreeBuffer makes application cleanup code simpler and
smaller because MAPIFreeBuffer can initialize pointers to NULL and then
free them in the cleanup code without having to test them first.
MAPIFreeBuffer is exported, with a slightly different syntax, by
both Simple MAPI and MAPI. For Simple MAPI, it is an entry point function.
See Also
IMAPISupport::GetMemAllocRoutines