BuildDisplayTable

The BuildDisplayTable function creates a display table from the property page data contained in one or more DTPAGE structures.

Quick Info

STDAPI BuildDisplayTable(
  LPALLOCATEBUFFER lpAllocateBuffer,   
  LPALLOCATEMORE lpAllocateMore,   
  LPFREEBUFFER lpFreeBuffer,       
  LPMALLOC lpMalloc,               
  HINSTANCE hInstance,             
  UINT cPages,                     
  LPDTPAGE lpPage,                 
  ULONG ulFlags,                   
  LPMAPITABLE * lppTable,          
  LPTABLEDATA * lppTblData         
);
 

Parameters

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used where required by MAPI to allocate memory.

lpAllocateMore

[in] Pointer to the MAPIAllocateMore function, to be used where required by MAPI to allocate additional memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used where required by MAPI to free memory.

lpMalloc

Unused; should be set to NULL.

hInstance

[in] An instance of a MAPI object from which BuildDisplayTable retrieves resources.

cPages

[in] Count of DTPAGE structures in the array pointed to by the lpPage parameter.

lpPage

[in] Pointer to an array of DTPAGE structures that contain information about the display table pages to be built.

ulFlags

[in] Bitmask of flags. The following flag can be set:

MAPI_UNICODE

The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.

lppTable

[out] Pointer to a pointer to the display table, which exposes the IMAPITable interface.

lppTblData

[in, out] Pointer to a pointer to a table data object exposing the ITableData interface on the table returned in the lppTable parameter. If no table data object is desired, lppTblData should be set to NULL instead of a pointer value.

Remarks

MAPI uses the functions pointed to by lpAllocateBuffer, lpAllocateMore, and lpFreeBuffer for most memory allocation and deallocation, in particular to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows.

Notes to Callers

Everything possible is read from the dialog resource, including:

• The page title — that is, the ulbLpszLabel member of the DTBLPAGE structure — read from the dialog title in the resource.
• All control titles — that is, the ulbLpszLabel members of other control structures — read from the control text in the resource.

BuildDisplayTable overwrites anything passed in the input control structures with information from the dialog resource, which means the caller of BuildDisplayTable cannot dynamically specify page or control titles. Callers who need to do that can choose to have BuildDisplayTable return to them the table data object in lppTableData and change rows in it; but they might find it simpler to build the display table by hand in a table data object instead.

If lppTableData is not set to NULL, the provider is responsible for freeing the table data object when it is finished with the display table.