ITableData::HrEnumRow

The ITableData::HrEnumRow method retrieves a row based on its position in the table.

Quick Info

HRESULT HrEnumRow(
  ULONG ulRowNumber,   
  LPSRow FAR * lppSRow 
);

Parameters

ulRowNumber: [in] Number of the row for which to return properties. The value in the ulRowNumber parameter can be any value from 0, indicating the first row in the table, through n – 1, indicating the last row in the table.
lppSRow: [out] Pointer to a pointer to an SRow structure describing the target row.

Return Values

S_OK: The row was retrieved successfully or a row for the row number specified by the ulRowNumber parameter does not exist.

Remarks

The ITableData::HrEnumRow method retrieves a row based on a sequential number. This number represents the order of insertion, with 0 being the first row and the number of rows minus 1 being the last row. MAPI maintains this chronological order of row insertion for the lifetime of the table data object.

If the number specified in ulRowNumber does not correspond to a row in the table, HrEnumRow returns S_OK and sets the lppSRow parameter to NULL.

MAPI allocates memory for the returned SRow structure using the MAPIAllocateBuffer function when the table data object is created. The caller must release this memory by calling the MAPIFreeBuffer function.

To retrieve rows from a table in the order that they were inserted, table data object users call the HrEnumRow method.