HrAddColumnsEx

The HrAddColumnsEx function adds or moves columns to the beginning of an existing table.

Quick Info

HRESULT HrAddColumnsEx(
  LPMAPITABLE lptbl,                                       
  LPSPropTagArray lpproptagColumnsNew,                     
  LPALLOCATEBUFFER lpAllocateBuffer,                       
  LPFREEBUFFER lpFreeBuffer,                               
  void (FAR * lpfnFilterColumns) (LPSPropTagArray ptaga)   
);
 

Parameters

lptbl

[in] Pointer to the MAPI table affected.

lpproptagColumnsNew

[in] Pointer to an SPropTagArray structure containing an array of property tags for the properties to be added or moved to the beginning of the table.

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.

lpfnFilterColumns

[in] Pointer to a callback function furnished by the caller. If the lpfnFilterColumns parameter is set to NULL, no callback is made.

ptaga

[in] Pointer to an SPropTagArray structure containing the array of property tags already existing in the table before properties are added or moved to the beginning. HrAddColumnsEx passes this pointer as the parameter to the callback function pointed to by lpfnFilterColumns.

Return Values

S_OK

The call succeeded and the specified columns were moved or added.

Remarks

The properties passed to HrAddColumnsEx using the lpproptagColumnsNew parameter become the first properties exposed on subsequent calls to the IMAPITable::QueryRows method. Any properties previously in the table that were not specified in the lpproptagColumnsNew parameter are exposed after all the added and moved properties.

If any table properties are undefined when QueryRows is called, they are returned with property type PT_NULL and property identifier PROP_ID_NULL.

Notes to Callers

The HrAddColumnsEx function allows the caller to furnish a callback function to filter the columns that were already in the table, for example to convert strings from property type PT_UNICODE to PT_STRING8. HrAddColumnsEx passes a pointer to the previously existing column set as the parameter to the callback function. The callback function can change data within the property tag array but cannot add new tags.

HrAddColumnsEx first calls the callback function if one is furnished, then adds or moves the specified columns, and finally calls IMAPITable::SetColumns.

The lpAllocateBuffer and lpFreeBuffer input parameters point to the MAPIAllocateBuffer and MAPIFreeBuffer functions, respectively. The exact values of the pointers passed to HrAddColumnsEx depend on whether the caller is a client application or a service provider. A client passes pointers to the MAPI functions with the specified names. A service provider passes the pointers it received in its initialization call or retrieved by calling the IMAPISupport::GetMemAllocRoutines method.

See Also

Table Functions, IMAPITable::QueryColumns