3.2.5.2 Receiving a CPMGetRowsOut Response

  • Article

When the client receives a CPMGetRowsOut message response from the server, the client MUST perform the following:

  1. Check whether the _status field in the header indicates success or failure.

  2. If the _status value is STATUS_BUFFER_TOO_SMALL (0xC0000023), the client MUST check the Last Message Sent state. If it does not contain a CPMGetRowsIn message, the received message MUST be silently ignored. Otherwise the client MUST send to the server a new CPMGetRowsIn message with all fields identical to the stored one, except that the _cbReadBuffer MUST be increased by 512 (but not greater than 0x4000). If _status is STATUS_BUFFER_TOO_SMALL (0xC0000023), and the Last Message Sent already has _cbReadBuffer equal to 0x4000, the client MUST report the error to the higher level.

  3. If the _status value is any other error value, the client MUST report the failure to the higher layer.

  4. If the _status value indicates success, the results MUST be reported to the higher layer requesting the information, and further actions are determined by the higher layer.

For informative purposes, it is expected that higher layers will typically perform the following actions, but these are not enforced by the Windows Search Protocol client:

  • If the values in rows represent the document IDs, chapter handles, or bookmark handles, the higher layer will typically store them for use in subsequent operations that involve valid document IDs, chapter handles, or bookmark handles.

  • The higher layer will typically store or display or otherwise use the data from row values.

  • For the values that were marked as deferred, the higher layer will fetch the value using CPMFetchValueIn messages.

  • The seek description is returned back to the higher layer as well, and can be reused or examined by the higher layer.

For informative purposes, if the higher layer requested handles to chapters and bookmarks that were received in the rows, it MAY perform the following:

  • Use CPMGetQueryStatusExIn to check on the execution progress of a query as well as additional status information, such as the number of filtered documents, documents remaining to be filtered, the ratio of documents processed by the query, the total number of rows in the query, and the position of the bookmark in the rowset.

  • Use CPMGetNotify to request that the server notify the client of rowset changes.

  • Use CPMGetApproximatePositionIn to request the approximate position of a bookmark in a chapter.

  • Use CPMCompareBmkIn to request a comparison of two bookmarks in a chapter.

  • Use CPMRestartPositionIn to request the server changes the location of the cursor to the start of rowset.