The following functions are used to allocate and deallocate memory:
FreePadrlist
MAPIAllocateBuffer
MAPIAllocateMore
MAPIFreeBuffer
MAPIGetDefaultMalloc
MAPIAllocateBuffer, MAPIAllocateMore, and MAPIFreeBuffer enable client applications and service providers to exchange blocks of memory. MAPIAllocateBuffer is called to initially allocate memory for a buffer; MAPIAllocateMore can be used at a later time to allocate a subsequent block of memory that is linked to the initial block. Assume when calling these allocators that the returned buffer is appropriately aligned for the CPU architecture.
The chaining of allocations supported by MAPIAllocateMore simplifies the handling of complex memory objects for clients. An array of property values, for example, can consist of numerous blocks of memory linked together by pointers that can be released with a single call to the third function, MAPIFreeBuffer. Whenever a block of memory is returned from any MAPI method, such as IMAPIProp::GetProps, MAPIFreeBuffer must be used to release it. MAPIFreeBuffer releases the initial block and any subsequent blocks.
Whenever possible, allocate all of the necessary memory with a single call to MAPIAllocateBuffer. MAPIAllocateMore exists merely as a convenience. However, if MAPIAllocateMore is used to allocate additional memory for a buffer, this memory should always be freed along with the initial buffer. Ignore any errors returned from MAPIFreeBuffer. The function almost always succeeds, and in the rare case that an error is returned, there is little that the caller can do about it.
Note Clients call the MAPIAllocateBuffer and MAPIAllocateMore functions directly, while service providers must make an indirect call, retrieving the function pointers through a call to IMAPISupport::GetMemAllocRoutines.