ITableData::HrModifyRows

The ITableData::HrModifyRows method inserts multiple table rows, possibly replacing existing rows.

Quick Info

HRESULT HrModifyRows(
  ULONG ulFlags,       
  LPSRowSet lpSRowSet  
);

Parameters

ulFlags: Reserved; must be zero.
lpSRowSet: [in] Pointer to an SRowSet structure containing the set of rows to be added, replacing existing rows if necessary. One of the property value structures pointed to by the lpProps member of each SRow structure in the row set should contain the index column — the same property that was specified in the ulPropTagIndexColumn parameter in the call to CreateTable.

Return Values

S_OK: The rows were successfully inserted or modified.
MAPI_E_INVALID_PARAMETER: One or more of the passed-in rows does not have an index column. If this error is returned, no rows are changed.

Remarks

The ITableData::HrModifyRows method inserts the rows described by the SRowSet structure pointed to by the lpSRowSet parameter. For each row in the row set, if its index column value matches the value for an existing row in the table, the existing row is replaced. If no row exists that matches the one included in the SRowSet structure, HrModifyRows adds the row to the end of the table.

All views of the table are modified to include the rows pointed to by lpSRowSet. However, if a view has a restriction in place that excludes a row, it may not be visible to the user.

The columns in the rows pointed to by lpSRowSet do not have to be in the same order as the columns in the table. The caller can also include as columns properties that are not currently in the table. For existing views, HrModifyRows makes these new columns available but does not include them in the current column set. For future views, HrModifyRows includes the new columns in the column set.

After HrModifyRows has added the rows, notifications are sent to all clients or service providers with a view of the table and that have called the table's IMAPITable::Advise method to register for notifications. MAPI sends TABLE_ROW_ADDED or TABLE_ROW_MODIFIED notifications for each row for up to eight rows. If more than eight rows are affected by the HrModifyRows call, MAPI sends a single TABLE_CHANGED notification instead.