This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK

Indicates success.

MAPI_E_BUSY

Another operation is in progress that prevents the row retrieval operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.

The cRowsmember in the SRowSetstructure pointed to by the lppRowsparameter indicates the number of rows returned. If zero rows are returned, the cursor was already positioned at the end of the table.

The number of columns and their ordering are the same for each row. If a property does not exist for a row or there is an error reading a property, the SPropValuestructure for the property in the row contains the following values:

• PT_ERRORfor the property type in the ulPropTagmember.
  
  
• MAPI_E_NOT_FOUNDfor the Valuemember.
  
  

Memory used for the SPropValuestructures in the row set pointed to by the lppRowsparameter must be separately allocated and freed for each row. Use FreeProwsto free the property value structures and to free the row set. When a call to QueryRowsreturns zero, however, indicating the end of the table, only the SRowSetstructure needs to be freed.

The rows that are returned and the order in which they are returned depend on whether or not successful calls have been made to IMAPITable::Restrictand IMAPITable::SortTable. Restrictfilters rows from the view, causing QueryRowsto return only the rows that match the criteria specified in the restriction. SortTableestablishes a standardized or categorized sort order that affects the sequence of rows returned by QueryRows. The returned rows are in the order specified in the SSortOrderSetstructure passed to SortTable.

The columns returned for each row and the order in which they are returned depend on whether or not a successful call has been made to IMAPITable::SetColumns. SetColumnsestablishes a column set, specifying the properties to be included in columns in the table and the order in which they should be included. If a SetColumnscall has been made, the particular columns in each row and the order of those columns match the column set specified in the call. If no SetColumnscall has been made, the table returns its default column set.

When the column set established in a call to SetColumnsincludes columns set to PR_NULL, the SPropValuearray within the row set returned in lppRowscontains empty slots.

If none of these calls has been made, QueryRowsreturns all of the requested rows in the table. Each row contains the default column set in default order.

Usually, you receive as many rows as you specified in the lRowCountparameter. However, when memory or implementation limits (10 rows maximum are returned) are an issue or when the operation reaches the end of the table prematurely, QueryRowsreturns fewer rows than requested.

If QueryRowsreturns MAPI_E_BUSY, retry the call to QueryRowswhen the asynchronous operation is complete.

When calling QueryRows, the timing of asynchronous notifications can potentially cause the row set that you get back from QueryRowsnot to accurately represent the underlying data. For example, a call to QueryRowsto a folder's contents table following the deletion of a message but prior to the receipt of the corresponding notification causes the deleted row to be returned in the row set. Always wait for a notification to arrive before updating the user's view of the data.