HrQueryAllRows

The HrQueryAllRows function retrieves all rows of a table.

Quick Info

HRESULT HrQueryAllRows(
  LPMAPITABLE ptable,    
  LPSPropTagArray ptaga,   
  LPSRestriction pres,   
  LPSSortOrderSet psos,  
  LONG crowsMax,         
  LPSRowSet FAR * pprows 
);
 

Parameters

ptable

[in] Pointer to the MAPI table from which rows are retrieved.

ptaga

[in] Pointer to an SPropTagArray structure containing an array of property tags indicating table columns. These tags are used to select the specific columns to be retrieved. If the ptaga parameter is NULL, HrQueryAllRows retrieves the entire column set of the current table view passed in the ptable parameter.

pres

[in] Pointer to an SRestriction structure containing retrieval restrictions. If the pres parameter is NULL, HrQueryAllRows makes no restrictions.

psos

[in] Pointer to an SSortOrderSet structure identifying the sort order of the columns to be retrieved. If the psos parameter is NULL, the default sort order for the table is used.

crowsMax

[in] Maximum number of rows to be retrieved. If the value of the crowsMax parameter is zero, no limit on the number of rows retrieved is set.

pprows

[out] Pointer to a pointer to the returned SRowSet structure containing an array of pointers to the retrieved table rows.

Return Values

S_OK

The call retrieved the expected rows of a table.

MAPI_E_TABLE_TOO_BIG

The number of rows in the table is larger than the number passed for the crowsMax parameter.

Remarks

A client application or service provider has no control over the number of rows HrQueryAllRows attempts to retrieve, other than by imposing a restriction pointed to by the pres parameter. The crowsMax parameter does not limit the retrieval to a certain number of table rows, but rather defines a maximum amount of memory available to hold all retrieved rows. The only protection against massive memory overflow is the stopgap feature provided by setting crowsMax. The error return MAPI_E_TABLE_TOO_BIG means the table contains too many rows to be held all at once in memory.

Tables that are typically small, such as a message store table or a provider table, usually can be safely retrieved with HrQueryAllRows. Tables at risk of being very large, such as a contents table or even a recipients table, should be traversed in subsections using the IMAPITable::QueryRows method.

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

See Also

Table Functions