Knowing how and when to allocate and free memory is an important part of programming with MAPI. MAPI provides both functions and macros that your client or service provider can use to manage memory in a consistent way. The three functions are:
When clients and service providers use these functions, the issue of who "owns" — that is, knows how to release — a particular block of memory is eliminated. A client calling a service provider method need not pass a buffer large enough to hold a return value of any size. The service provider can simply allocate the appropriate amount of memory using MAPIAllocateBuffer and, if necessary, MAPIAllocateMore, and the client can later release it at will using MAPIFreeBuffer, independent of the service provider. For more information about these functions, see Memory Management Functions.
The memory macros are used to allocate structures or arrays of structures of a specific size. Clients and service providers should use these macros rather than allocate the memory manually. For example, if a client needs to perform name resolution processing on a recipient list with three entries, the SizedADRLIST macro can be used to create an ADRLIST structure to pass to IAddrBook::ResolveName with the correct number of ADRENTRY members. All of the memory macros are defined in the MAPIDEFS.H header file. These macros are:
MAPI also supports the use of the OLE interface IMalloc for memory management. Service providers are given an IMalloc interface pointer by MAPI at initialization time and can also retrieve one through the MAPIGetDefaultMalloc function. The main advantage to using the IMalloc methods for managing memory over the MAPI functions is that with the OLE methods it is possible to reallocate an existing buffer. The MAPI memory functions do not support reallocation.