Server Details - [ms-wsp]: Windows Search Protocol Intellectual Property Rights Notice for Open Specifications Documentation

Server Details Abstract Data Model
The following section specifies data and state maintained by the Windows Search Protocol server. The data provided in this document explains how the protocol behaves. This section does not mandate that implementations adhere to this model as long as their external behavior is consistent with that described in this document.
The Generic Search Service (GSS) implementing the Windows Search Protocol MUST maintain the following abstract data elements:
ConnectedClientsIdentifiers: A list of 32-bit unsigned integers. Values are added upon successful responses to CPMConnectIn messages and are removed when the clients disconnect. These integer identifiers are actually set to the values of the named pipe HANDLEs to connected clients because they uniquely identify incoming connections. The identifiers are removed from the list when the named pipe with the same HANDLEs are disconnected. Apart from the unique connection identification quality, no named pipe HANDLE semantics are assumed about the integer values in this list. Queries can be executed only one at a time over any given connection. Therefore, the server passes values in the ConnectedClientIdentifiers list as the QueryIdentifier argument to any GSS abstract interface calls that it makes.
ConnectedClientVersions: A list of 32-bit unsigned integers, one for each identifier in the ConnectedClientIdentifiers list. If the last 2 bytes of the client version are greater than or equal to 0x109, the server will verify the checksums in the message. If the version is greater than 0x10000, the server detects that the client is a 64-bit system.
Timers
The following timer is required for the server.
EventTimer: This is a periodic timer that is started upon receipt of a CPMSetScopePrioritizationIn message. The timer expiration interval is defined by the server when the timer is started. This timer instance is associated with exactly one active query. There can be multiple EventTimers, one for each query.
The following input or state is required for this timer.
QueryIdentifier: A unique query identifier of the query for which this timer was started.
Initialization
Upon initialization, the server MUST set its state to "not initialized" and start listening for messages on the named pipe specified in section 1.9. After performing any other internal initialization, it MUST transition to the "running" state.
Higher-Layer Triggered Events
None.
Processing and Sequencing Rules
Whenever an error occurs during processing of a message sent by a client, the server MUST report an error back to the client as follows:
Stop processing the message sent by the client.
Respond with the message header (only) of the message sent by the client, keeping the _msg field intact. The only exception to this is when an error occurs in the CPMConnectIn (section 2.2.3.2) request and the server cannot find a catalog. The response is a CPMConnectOut (section 2.2.3.3) message with the following possible errors.
Error
|
Meaning
|
DS_E_DATASOURCENOTAVAILABLE
|
Catalog not in ready state for queries.
|
DS_E_INVALIDDATASOURCE
|
Failed to specify catalog correctly.
|
CI_E_NO_CATALOG
|
Catalog not found.
|
Set the _status field to the error code value.
When a message arrives, the server MUST check the _msg field value to identify whether it is a known type (see section 2.2.2). If the type is not known, it MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
The server MUST then validate the _ulChecksum field value if the message type is one of the following:
CPMConnectIn (0x000000C8)
CPMCreateQueryIn (0x000000CA)
CPMSetBindingsIn (0x000000D0)
CPMGetRowsIn (0x000000CC)
CPMFetchValueIn (0x000000E4)
To validate the _ulChecksum field value, the server MUST check the value that the client specified in the _iClientVersion field in the CPMConnectIn message.
If the value of the _iClientVersion field's last 2 bytes is 0x00000109 or greater and _ulChecksum is not equal to zero, the server MUST validate that the _ulChecksum field was calculated as specified in section 3.2.4. If the _ulChecksum value is invalid, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Next, the server checks which state it is in. If its state is "not initialized", the server MUST report a CI_E_NOT_INITIALIZED (0x8004180B) error. If the state is "shutting down", the server MUST report a CI_E_SHUTDOWN (0x80041812) error.
After a header has been determined to be valid and the server to be in "running" state, further message-specific processing MUST be performed, as specified in the following subsections.
Some messages are valid only after a previous message has been sent. Typically, an ID or handle from the earlier message is required as input to the later message. These requirements are detailed in the following sections. The table below summarizes the relationship between messages.
Figure 6: Windows Search Protocol message sequence relationships
Remote Windows Search Service Catalog Management Receiving a CPMCiStateInOut Request
When the server receives a CPMCiStateInOut message request from the client, the server MUST first search the ConnectedClientIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMCiStateInOut message. If the handle is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error; otherwise, it MUST respond to the client with a CPMCiStateInOut message containing information about the client's associated catalog, obtained by calling the GetState abstract interface.
Remote Windows Search Service Querying Receiving a CPMConnectIn Request
When the server receives a CPMConnectIn request from a client, the server MUST do the following.
Search the ConnectedClientIdentifiers list for the handle of the named pipe over which the server has received the CPMConnectIn message. If it is present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Call the IsCatalogAvailable abstract interface. Provide the DBPROP_CI_CATALOG_NAME property value from the CPMConnectIn request message as the sole argument. Report a MSS_E_CATALOGNOTFOUND (0x80042103) error if the result of the IsCatalogAvailable abstract interface call to the GSS is not true. <25>
If the value of the iClientVersion field is larger than 0x00000109, then validate the checksum of the CPMConnectIn request as described in section 3.2.4.
Add the handle of the named pipe over which the server received the CPMConnectIn message to the ConnectedClientIdentifiers list. Call the StoreClientInformation abstract interface to the GSS with the query identifier that uniquely identifies the query to the server, the CPMConnectIn message as the ConnectMessage argument, and the HANDLE of the named pipe over which the server has received the CPMConnectIn message as the NamedPipeHandle argument. This helps the GSS later assess whether the user identified here has access to returned results.
Store the _iClientVersion field in the ConnectedClientVersions list under the same index as the index in the ConnectedClientIdentifiers list of the handle of the named pipe over which the server received this message.
Call the GetServerVersions abstract interface of the GSS. Fill in the _serverVersion field using the _serverVersion output argument obtained from the GetServerVersions abstract interface. If supportsVersioningInfo is true, fill in the dwWinVerMajor, dwWinVerMinor, dwNLSVerMajor, and dwNLSVerMinor fields with the values returned by GetServerVersions. Otherwise, in order to indicate that versioning is not supported (see section 3.2.4.2.1), the server MUST copy four DWORDs at the offset starting after _serverVersion in the CPMConnectIn message to the same location in the CPMConnectOut reply (the offset right after _serverVersion).
Respond to the client with the CPMConnectOut message.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: Generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: Generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
STATUS_INVALID_PARAMETER_MIX: Generated when the client version as passed in this message is smaller than CI_VERSION_WDS30 (0x102).
DS_E_DATASOURCENOTAVAILABLE: Generated when the catalog requested is not in a ready state for queries.
DS_E_ INVALIDDATASOURCE: Generated when the catalog was not specified correctly.
CI_E_NO_CATALOG: Generated when the catalog requested was not found.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMCreateQueryIn Request
When the server receives a CPMCreateQueryIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMCreateQueryIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Run the RunNewQuery abstract interface of the GSS. Pass in as parameters the HANDLE of the named pipe over which the server has received the CPMCreateQueryIn message, along with the ColumnSet, RestrictionArray, SortSet, CCategorizationSet, RowSetProperties, PidMapper, GroupArray, and Lcid values. If the CanRunQueryNow output parameter is not true, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error. Otherwise, report the QueryParametersError output parameter in the reply. Details for how to report an error are specified in section 3.1.5.
Respond to the client with a CPMCreateQueryOut message by using the CursorHandlesList, fTrueSequential, and fWorkidUnique outputs obtained from the RunNewQuery abstract interface to the GSS.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. The following errors are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client are invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
STATUS_INVALID_PARAMETER_MIX: generated when the client version, as passed in this message, is smaller than CI_VERSION_WDS30 (0x102).
STATUS_NO_MEMORY: generated on memory allocation errors.
STATUS_INSUFFICIENT_RESOURCES: generated on resource allocation errors. These resources could be file or pipe handles, any data structures that are specific to the implementation of the GSS, or any other resources used by the GSS implementation.
CI_E_NOT_FOUND: generated when the requested property was not found.
ERROR_INVALID_PARAMETER: this is generated by the WSS implementation on some internal errors, such as registry access failures. Implementations of the GSS can choose to do the same.
CI_E_TIMEOUT: generated on named pipe communication timeout.
E_ACCESSDENIED: generated when the client does not have permissions to access a needed resource, such as a file result or a catalog.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMGetQueryStatusIn Request
When the server receives a CPMGetQueryStatusIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMGetQueryStatusIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Call the ClientQueryHasCursorHandle abstract interface to the GSS with the HANDLE of the named pipe over which the server has received the CPMGetQueryStatusIn message as its QueryIdentifier argument and with the _hCursor handle as its CursorHandle argument. <26>
Call the GetQueryStatus abstract interface to the GSS. Use the HANDLE of the named pipe over which the server has received the CPMGetQueryStatusIn message as its QueryIdentifier argument. Prepare a CPMGetQueryStatusOut message, using the QueryStatus output for the _QStatus field. If the Error output is not 0, then report the error.
Respond to the client with the CPMGetQueryStatusOut message.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMGetQueryStatusExIn Request
When the server receives a CPMGetQueryStatusExIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMGetQueryStatusExIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Call the ClientQueryHasCursorHandle abstract interface to the GSS with the HANDLE of the named pipe over which the server has received the CPMGetQueryStatusIn message as its QueryIdentifier argument and with the _hCursor handle as its CursorHandle argument.<27>
Prepare a CPMGetQueryStatusExOut message, using corresponding parameters obtained by calling the following abstract interfaces to the GSS.
GetState, with no parameters
Parameters: none
Use Output parameters:
cFilteredDocuments = CFilteredDocuments
Set cDocumentsToFilter to: CTotalDocuments - CFilteredDocuments
GetQueryStatus
Parameters:
The HANDLE of the named pipe over which the server has received the CPMGetQueryStatusExIn message.
Use Output parameters:
GetRatioFinishedParams
Parameters:
The HANDLE of the named pipe over which the server has received the CPMGetQueryStatusExIn message.
hCursor
Use Output parameters:
dwRatioFinishedDenominator = rdwRatioFinishedDenominator
dwRatioFinishedNumerator = rdwRatioFinishedNumerator
GetApproximatePosition
Parameters:
The HANDLE of the named pipe over which the server has received the CPMGetQueryStatusExIn message.
hCursor
bmk
Use Output Parameters:
GetWhereID
Parameters:
The HANDLE of the named pipe over which the server has received the CPMGetQueryStatusExIn message.
Use Output parameters:
GetExpensiveProperties
Parameters:
The HANDLE of the named pipe over which the server has received the CPMGetQueryStatusExIn message.
hCursor
Use Output parameters:
cRowsTotal = rcRowsTotal
cResultsFound = rdwResultCount
maxRank = maxRank
Respond to the client with the CPMGetQueryStatusExOut message.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
E_ACCESSDENIED: generated when the client does not have permissions to access a needed resource such as a file result or a catalog.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMRatioFinishedIn Request
When the server receives a CPMRatioFinishedIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMRatioFinishedIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Call the ClientQueryHasCursorHandle abstract interface to the GSS with the HANDLE of the named pipe over which the server has received the CPMRatioFinishedIn message as its QueryIdentifier argument and with the hCursor handle as its CursorHandle argument. <28>
Call the GetRatioFinishedParams abstract interface with the HANDLE of the named pipe over which the server has received the CPMRatioFinishedIn message as its QueryIdentifier argument and with the hCursor handle as its CursorHandle argument.
Prepare a CPMRatioFinishedOut message; the server MUST set the CPMRatioFinishedOut parameters as follows.
ulNumerator = rdwRatioFinishedNumerator
ulDenominator = rdwRatioFinishedDenominator
cRows = cRows
fNewRows = fNewRows
If this step fails for any reason, the server MUST report any error code encountered in performing the request in accordance with Win32 Error Codes in [MS-ERREF].
Respond to the client with the CPMRatioFinishedOut message.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
E_ACCESSDENIED: generated when the client does not have permissions to access a needed resource such as a file result or a catalog.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMGetRowsIn Request
When the server receives a CPMGetRowsIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMGetRowsIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Call the ClientQueryHasCursorHandle abstract interface to the GSS with the HANDLE of the named pipe over which the server has received the CPMGetRowsIn message as its QueryIdentifier argument and with the _hCursor handle as its CursorHandle argument.<29>
Call the HasBindings abstract interface with the HANDLE of the named pipe over which the server has received the CPMGetRowsIn message as its QueryIdentifier argument and with the _hCursor handle as its CursorHandle argument. If the hasBindings output parameter is not true, the server MUST report an E_UNEXPECTED (0x8000FFFF) error.<30>
Prepare a CPMGetRowsOut message by setting the position from which to retrieve the next rows, according to the received SeekDescription:
If eType == 0x00000000, then no work needs to be done to reposition the next row's read index within the rowset.
Define oldIndex as the result of calling the GetNextGetRowsPosition abstract interface with QueryIdentifier and CursorHandle as arguments. Then, as a function of eType, call the SetNextGetRowsPosition abstract interface with QueryIdentifier, chapter, and CursorHandle as arguments and with Index set to:
If eType == eRowSeekNext (section 2.2.3.11), then Index = oldIndex + cskip (section 2.2.1.37).
If eType == eRowSeekAt (section 2.2.3.11), then Index = GetBookmarkPosition(QueryIdentifier, CursorHandle, _bmkOffset) + _cskip (sections 3.1.7and 2.2.1.37).
If eType == eRowSeekatRatio (section 2.2.3.11), then Index = (ulNumerator/ulDenominator) * rcRowsTotal. The value of rcRowsTotal (section 3.1.7) is equal to the output argument of the GetExpensiveProperties abstract interface called with QueryIdentifier and CursorHandle as arguments.
When the value of ulDenominator is zero, or if _ulDenominator > _ulNumerator, DB_E_BADRATIO is returned as the error value.
If eType == eRowSeekByBookmark (section 2.2.3.11), then for each bookmark handle value in the aBookmarks array (section 2.2.1.39) of the SeekDescription (section 2.2.3.11) argument:
Call the GetBookmarkPosition abstract interface to the GSS with QueryIdentifier, CursorHandle, and the bookmark handle value as arguments.
Use the bmkIndex (section 3.1.7) returned as an argument to SetNextGetRowsPosition (section 3.1.7), along with QueryIdentifier, CursorHandle, and _chapter.
Call the GetRows abstract interface with QueryIdentifier, CursorHandle, 1, and _fBwdFetch as arguments.
After the position is set, retrieve the desired row from the GSS by calling the GetRows abstract interface with the HANDLE of the named pipe over which the server has received the CPMGetRowsIn message as its QueryIdentifier argument, with the _hCursor handle as its CursorHandle argument, with _chapter as its chapter argument, with _cRowsToTransfer as its NumRowsRequested argument, and with _fBwdFetch as its FetchForward argument. Do this in all cases, except for step 4 bullet 3.
Copy as many rows as fit in a buffer, the size of which is indicated by _cbReadBuffer (section 2.2.3.11), but not more than indicated by _cRowsToTransfer (section 2.2.3.11). Thereafter, reposition the cursor to reflect the actual number of returned rows by calling the SetNextGetRowsPosition abstract interface with QueryIdentifier, CursorHandle and _chapter as arguments and with Index set to the old index (as obtained by calling GetNextRowsPosition(QueryIdentifier, _hCursor, _chapter)) plus the number of rows that fit in the buffer.
If there are no more rows available on the server to finish this request, as signaled by the NoMoreRowsToReturn output parameter for the call made to the GetRows abstract interface (section 3.1.7), the Status fleld of CPMGetRowsOut message MUST be set to DB_S_ENDOFROWSET.
Store the number of rows fetched in _cRowsReturned (section 2.2.3.12), as determined by the NumRowsReturned output parameter from the GetRows call (or, in the case of step 4 bullet 3, the sum of the NumRowsReturned parameters from the GetRows calls).
Copy the _chapt field from the CPMGetRowsIn message to a CPMGetRowsOut message to be sent.
If either of the following cases are true, copy the SeekDescription (section 2.2.3.11) from the CPMGetRowsIn to the CPMGetRowsOut message.
The server fails to completely fill the buffer due to a memory allocation failure, but has been able to store at least one row.
Copying the SeekDescription (section 2.2.3.11) allows the client to continue from the point where the server left off. In addition, the server SHOULD set the error code DB_S_BLOCKLIMITEDROWS, and in the case of CRowSeekAtRatio, convert CRowSeekAtRatio to CRowSeekAt.
CRowSeekByBookmark is specified.
Otherwise, clear SeekDescription (section 2.2.3.11) by setting it to zero.
Store the fetched rows in the Rows field (see section 2.2.3.12 for details on the structure of the Rows field).
Note Regarding status byte field: If StatusUsed is set to 0x01 in the CTableColumn of the CPMSetBindingsIn message for the column, the server MUST set the status byte (which is located at StatusOffset from the start of the rows) for this column to one of the following values.
Value
|
Meaning
|
0x00
|
StoreStatusOK
|
0x01
|
StoreStatusDeferred
|
0x02
|
StoreStatusNull
|
Respond to the client with the CPMGetRowsOut message.
If the property value is absent for this row, the server MUST set the status byte to StoreStatusNull. If the value is too big to be transferred in the CPMGetRowsOut message (greater than 2048 bytes), the server MUST set the status byte to StoreStatusDeferred. Otherwise, the server MUST set the status byte to StoreStatusOK.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
STATUS_NO_MEMORY: generated on memory allocation errors.
CI_E_NOT_FOUND: generated when the requested property was not found.
E_ACCESSDENIED: generated when the client does not have permissions to access a needed resource such as a file result or a catalog.
CI_E_BUFFERTOOSMALL: generated when the buffer passed in is too small to accommodate the requested property or properties. This error signals the client to request the potentially large property value separately using a CPMFetchValueIn request.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMFetchValueIn Request
When the server receives a CPMFetchValueIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMFetchValueIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Prepare a CPMFetchValueOut message. If this step fails for any reason, the server MUST report an error.
Call the GetPropertyValueForWorkid abstract interface with the HANDLE of the named pipe over which the server has received the CPMFetchValueIn message, _wid, and Propspec as arguments. If the ValueExists output parameter is not true, the server MUST set _fValueExists (section 2.2.3.16) to 0x00000000; otherwise set _fValueExists (section 2.2.3.16) to 0x00000001. If this step fails for any reason, the server MUST report any error code encountered in performing the request in accordance with Win32 Error Codes in [MS-ERREF].
If _fValueExists is equal to 0x00000001, the server MUST do the following:
Scan the Property output parameter structure, starting from the _cbSoFar offset, and copy a maximum of _cbChunk bytes (do not go past the end of the serialized property) to the vValue field. If this step fails for any reason, the server MUST report an error.
Set _cbValue to the number of bytes copied in the previous step.
If the length of the serialized property is greater than _cbSoFar added to _cbValue, set _fMoreExists to 0x00000001; otherwise, set it to 0x00000000.
Respond to the client with the CPMFetchValueOut message.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
E_ACCESSDENIED: generated when the client does not have permissions to access a needed resource such as a file result or a catalog.
CI_E_BUFFERTOOSMALL: generated when the buffer passed in is too small to accommodate the requested property. This error signals the client to request the potentially large property value separately, using a CPMFetchValueIn request with a larger buffer.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMSetBindingsIn Request
When the server receives a CPMSetBindingsIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMSetBindingsIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Call the ClientQueryHasCursorHandle abstract interface to the GSS with the HANDLE of the named pipe over which the server has received the CPMSetBindingsIn message as its QueryIdentifier argument and with the _hCursor handle as its CursorHandle argument.<31>
Verify that the bindings information is valid (that is, the column at least specifies value, length, or status to be returned; there is no overlap in bindings for value, length, or status; and value, length, and status fit in the row size specified) and, if not, report a DB_E_BADBINDINFO (0x80040E08) error.<32>
Call the SetBindings abstract interface with the HANDLE of the named pipe over which the server has received the CPMSetBindingsIn message as its QueryIdentifier argument, with the _hCursor handle as its CursorHandle argument, and with the aColumns field as its Columns argument. The server MUST report any error code returned as the Error output parameter.
Respond to the client with a message header (only), with _msg set to CPMSetBindingsIn and _status set to the results of the specified binding.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMGetNotify Request
When the server receives a CPMGetNotify message from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMGetNotify message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.<33>
Call the GetQueryStatusChanges abstract interface with the HANDLE of the named pipe over which the server has received the CPMGetNotify message as its QueryIdentifier argument. If the ChangesPresent output parameter is true, then the server MUST respond with a CPMSendNotifyOut message and MUST set the _watchNotify field of this message to the LatestChange parameter value that is output from the call.
At a later time, if there is a change in the query results set as determined by polling the GSS with GetQueryStatusChanges interface calls, the server MUST send exactly one CPMSendNotifyOut message to the client and MUST specify the change in the _watchNotify field.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMGetApproximatePositionIn Request
When the server receives a CPMGetApproximatePositionIn message request from the client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMGetApproximatePositionIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Call the ClientQueryHasCursorHandle abstract interface to the GSS with the HANDLE of the named pipe over which the server has received the CPMGetApproximatePositionIn message as its QueryIdentifier argument and with the _hCursor handle as its CursorHandle argument. If the ContainsHandle output parameter is not true, the server MUST report an E_FAIL (0x80004005) error.
Call the GetApproximatePosition abstract interface with the HANDLE of the named pipe over which the server has received the CPMGetApproximatePositionIn message as its QueryIdentifier argument, with the _hCursor handle as its CursorHandle argument, and with _bmk as its Bmk argument. Use the riRowBmk output parameter as the numerator and use the total number of rows for this cursor as the denominator for the CPMGetApproximatePositionOut message. The total number of rows is the value of the rcRowsTotal output parameter from a GetExpensiveProperties abstract interface call, using QueryIdentifier and _hCursor as arguments to the call.
Note If this step fails for any reason, the server MUST report any error code encountered in performing the request in accordance with Win32 Error Codes in [MS-ERREF].
Respond to the client with a CPMGetApproximatePositionOut message.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMCompareBmkIn Request
When the server receives a CPMCompareBmkIn message request from the client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMCompareBmkIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Call the ClientQueryHasCursorHandle abstract interface to the GSS with the HANDLE of the named pipe over which the server has received the CPMCompareBmkIn message as its QueryIdentifier argument and with the _hCursor handle as its CursorHandle argument. If the ContainsHandle output parameter is not true, the server MUST report an E_FAIL (0x80004005) error.
Prepare a CPMCompareBmkOut message.
If the bookmark handles are equal, _dwComparison MUST be set to DBCOMPARE_EQ.
Otherwise, the server MUST do the following:
Find rows that are referred to by each bookmark handle in the query results: the server MUST retrieve the indices of both rows within the rowset by calling the GetBookmarkPosition abstract interface twice, with the HANDLE of the named pipe over which the server has received the CPMCompareBmkIn message as its QueryIdentifier argument, with the _hCursor handle as its CursorHandle argument, and the bmkFirst and bmkSecond bookmark handles, respectively as the bmkHandle argument.
If the chapter handle in CPMCompareBmkIn is invalid, or if one or both of the rows are not in the given chapter, the behavior is undefined.
Otherwise, when both rows are in the same chapter, the server MUST then compare the position values obtained via a GetBookmarkPosition interface call and set _dwComparison to DBCOMPARE_LT if the position of the first row is smaller than the position of the second row; otherwise, _dwComparison MUST be set to DBCOMPARE_GT.
Respond to the client with the configured CPMCompareBmkOut message.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMRestartPositionIn Request
When the server receives the CPMRestartPositionIn message request from the client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMRestartPositionIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Call the ClientQueryHasCursorHandle abstract interface to the GSS with the HANDLE of the named pipe over which the server has received the CPMRestartPositionIn message as its QueryIdentifier argument, and with the _hCursor handle as its CursorHandle argument. If the ContainsHandle output parameter is not true, the server MUST report an E_FAIL (0x80004005) error.
Move the cursor to the beginning of the chapter identified by the chapter handle by calling the SetNextGetRowsPosition abstract interface with the HANDLE of the named pipe over which the server has received the CPMRestartPositionIn message as its QueryIdentifier argument, with the _hCursor handle as its CursorHandle argument, and with the _chapt handle as the chapter argument. When the chapter handle is DB_NULL_HCHAPTER, the corresponding chapter is the main rowset of the query.
Note If this step fails for any reason, the server MUST report any error code encountered in performing the request in accordance with Win32 Error Codes in [MS-ERREF].
Respond to the client with a CPMRestartPositionIn message.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMFreeCursorIn Request
When the server receives a CPMFreeCursorIn message request from the client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMFreeCursorIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Call the ClientQueryHasCursorHandle abstract interface to the GSS with the HANDLE of the named pipe over which the server has received the CPMFreeCursorIn message as its QueryIdentifier argument and with the _hCursor handle as its CursorHandle argument. If the ContainsHandle output parameter is not true, the server MUST report an error.<34>
Release the cursor and associated resources for this cursor handle by calling the ReleaseCursor abstract interface with the HANDLE of the named pipe over which the server has received the CPMFreeCursorIn message as its QueryIdentifier argument and with the _hCursor handle as its CursorHandle argument.
Respond with a CPMFreeCursorOut message, setting the _cCursorsRemaining field to the number of cursors remaining in this client's list, as returned in the NumCursorsRemaining output parameter to the ReleaseCursor abstract interface call made in the previous step.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMDisconnect Request
When the server receives a CPMDisconnect message request from the client, the server MUST do the following:
Remove the HANDLE of the named pipe over which the server has received the CPMDisconnect message from the ConnectedClientsIdentifiers list.
Remove the corresponding entry from the ConnectedClientVersions list.
Call the ReleaseQuery abstract interface to the GSS with the HANDLE of the named pipe over which the server has received the CPMDisconnect message as its QueryIdentifier argument.
Receiving a CPMFindIndicesIn Request
When the server receives a CPMFindIndicesIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMFindIndicesIn message. If it is not present, the server MUST report an E_INVALIDARG (0x80070057) error.
Prepare a CPMFindIndicesOut message. If this step fails for any reason, the server MUST report any error code encountered in performing the request in accordance with Win32 Error Codes in [MS-ERREF].
The CPMFindIndicesOut message MUST contain one hierarchical group coordinate to the next occurrence of one of the document identifiers specified in the CPMFindIndicesIn message or, if no such occurrence was found, the server MUST indicate this by setting _cDepthNext to zero. In the case of a non-grouping query, _cDepthNext will be 1, indicating a single offset into the current rowset.
The next occurrence is found by calling the FindNextOccurrenceIndex abstract interface to the GSS, with the HANDLE of the named pipe over which the server has received the CPMFindIndicesIn message, _prgiRowPrev as the previous coordinates list (or NULL if _cDepthPrev is zero), and array _pwids[0] as arguments.
Note Currently, the server only supports a single document identifier lookup and discounts any workids in _pwids other than the first one. The next occurrence coordinate list is returned in the NextOccCoordinatesList output parameter, or if not found, then the NextOccExists parameter is not true.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMGetRowsetNotifyIn
When the server receives a CPMGetRowsetNotifyIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMGetRowsetNotifyIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Prepare a CPMGetRowsetNotifyOut message. If this step fails for any reason, the server MUST report any error code encountered in performing the request in accordance with Win32 Error Codes in [MS-ERREF].
The server MUST make a call to the GetLastUnretrievedEvent abstract interface of the GSS with the HANDLE of the named pipe over which the server has received the CPMGetRowsetNotifyOut message as its QueryIdentifier argument and populate the CPMGetRowsetNotifyOut message with the corresponding output parameters.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMGetScopeStatisticsIn
When the server receives a CPMGetScopeStatisticsIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMGetScopeStatisticsIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Prepare a CPMGetScopeStatisticsOut message. If this step fails for any reason, the server MUST report any error code encountered in performing the request in accordance with Win32 Error Codes in [MS-ERREF].
Call the GetQueryStatistics abstract interface of the GSS, with the HANDLE of the named pipe over which the server has received the CPMGetScopeStatisticsIn message as the QueryIdentifier argument for the call. Populate the CPMGetScopeStatisticsOut message fields with the corresponding output arguments from this call.
Note The server SHOULD return zero for all statistics unless the client has explicitly requested their availability by setting the DBPROP_ENABLEROWSETEVENTS property to TRUE.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
E_ACCESSDENIED: generated when the client does not have permissions to access a needed resource such as a file result or a catalog.
Any other error code may be returned, but it will only be treated as informative.
Receiving a CPMSetScopePrioritizationIn
This message is currently implemented only in the Windows 7 operating system. If the server fails implementation of this message, it can report a STATUS_INVALID_PARAMETER error. Otherwise, when the server receives a CPMSetScopePrioritizationIn message request from a client, the server MUST do the following:
Search the ConnectedClientsIdentifiers list for the HANDLE of the named pipe over which the server has received the CPMSetScopePrioritizationIn message. If it is not present, the server MUST report a STATUS_INVALID_PARAMETER (0xC000000D) error.
Prepare a CPMSetScopePrioritizationOut message. If this step fails for any reason, the server MUST report any error code encountered in performing the request in accordance with Win32 Error Codes in [MS-ERREF].
Call the SetScopePriority abstract interface of the GSS, with the HANDLE of the named pipe over which the server has received the CPMSetScopePrioritizationIn message and the priority field as arguments.
If eventFrequency is not zero, start an EventTimer timer that expires after an interval defined by eventFrequency, in milliseconds. Otherwise, if eventFrequency is zero, then call the FilterOutScopeStatisticsMessages abstract interface of the GSS, with the HANDLE of the named pipe over which the server has received the CPMSetScopePrioritizationIn message as the argument for the call.
The CPMSetScopePrioritizationOut message MUST simply acknowledge successful receipt of the CPMSetScopePrioritizationIn message and that the SetScopePriority abstract interface has been called, with the HANDLE of the named pipe over which the server has received the CPMSetScopePrioritizationIn message and the priority field as arguments to the call.
Report any errors encountered during message preparation or during any abstract interface call to the GSS. Errors that are specific to this request:
E_OUTOFMEMORY: generated by any resource allocation failure on the server or service side.
STATUS_INVALID_PARAMETER: generated when any of the parameters passed in by the client is invalid. Invalid parameters are those that do not obey the corresponding data structure layout as defined for their types in this document.
Any other error code may be returned, but it will only be treated as informative.
34>33>32>31>30>29>28>27>26>25>
|