ITableData::HrGetView

The ITableData::HrGetView method creates a table view, returning a pointer to an IMAPITable implementation.

Quick Info

HRESULT HrGetView(
  LPSSortOrderSet lpSSortOrderSet,        
  CALLERRELEASE FAR * lpfCallerRelease,   
  ULONG ulCallerData,                     
  LPMAPITABLE FAR * lppMAPITable          
);

Parameters

lpSSortOrderSet: [in] Pointer to a sort order structure describing the sort order for the table view. If NULL is passed in the lpSSortOrderSet parameter, the view is not sorted.
lpfCallerRelease: [in] Pointer to a callback function based on the CALLERRELEASE prototype that MAPI calls when it releases the view. If NULL is passed in the lpfCallerRelease parameter, no function is called upon release of the view.
ulCallerData: [in] Data that must be saved with the new view and passed to the callback function pointed to by lpfCallerRelease.
lppMAPITable: [out] Pointer to a pointer to the newly created view.

Return Values

S_OK: The view was successfully created.

Remarks

The ITableData::HrGetView method creates a read-only view of the data in the table sorted in the order pointed to by lpSSortOrderSet. The cursor is placed at the beginning of the first row in the view. An IMAPITable interface implementation for accessing the view is returned.

Service providers call HrGetView when they need to give a client access to a table. HrGetView creates the view and returns the IMAPITable pointer. Service providers in turn pass the pointer on to the client. When the client is finished using the table and calls its IUnknown::Release method, HrGetView calls the callback function pointed to by the lpfCallerRelease parameter.

If a service provider needs to return to a client a view that has a customized column set or a restriction in place, the provider can call the view's IMAPITable::SetColumns and Restrict methods before allowing the client access.