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

Server Details

1. Abstract Data Model

The Generic Search Service (GSS) implementing the Windows Search Protocol MUST maintain the following abstract data elements:

2. Timers

The following input or state is required for this timer.

3. Initialization

4. Higher-Layer Triggered Events

5. Processing and Sequencing Rules

• 
  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.
  

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)
  

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.

1. Remote Windows Search Service Catalog Management

   1. Receiving a CPMCiStateInOut Request

2. Remote Windows Search Service Querying

   1. Receiving a CPMConnectIn Request

1. 
   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.
   
2. 
   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>
   
3. 
   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.
   
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.
   
5. 
   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.
   
6. 
   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).
   
7. 
   Respond to the client with the CPMConnectOut message.
   
8. 
   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.
  

2. Receiving a CPMCreateQueryIn Request

1. 
   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.
   
2. 
   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.
   
3. 
   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.
   
4. 
   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.
  

3. Receiving a CPMGetQueryStatusIn Request

1. 
   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.
   
2. 
   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>
   
3. 
   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.
   
4. 
   Respond to the client with the CPMGetQueryStatusOut message.
   
5. 
   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.
  

4. Receiving a CPMGetQueryStatusExIn Request

1. 
   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.
   
2. 
   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>
   
3. 
   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:
    
    • 
      QStatus = QStatus
      
• 
  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:
    
    • 
      iRowBmk = riRowBmk
      
• 
  GetWhereID
  
  • 
    Parameters:
    
    • 
      The HANDLE of the named pipe over which the server has received the CPMGetQueryStatusExIn message.
      
  • 
    Use Output parameters:
    
    • 
      whereID = whereid
      
• 
  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
      

4. 
   Respond to the client with the CPMGetQueryStatusExOut message.
   
5. 
   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.
  

5. Receiving a CPMRatioFinishedIn Request

1. 
   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.
   
2. 
   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>
   
3. 
   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.
   
4. 
   Prepare a CPMRatioFinishedOut message; the server MUST set the CPMRatioFinishedOut parameters as follows.
   

• 
  ulNumerator = rdwRatioFinishedNumerator
  
• 
  ulDenominator = rdwRatioFinishedDenominator
  
• 
  cRows = cRows
  
• 
  fNewRows = fNewRows
  

5. 
   Respond to the client with the CPMRatioFinishedOut message.
   
6. 
   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.
  

6. Receiving a CPMGetRowsIn Request

1. 
   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.
   
2. 
   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>
   
3. 
   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>
   
4. 
   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.
    

5. 
   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.
   
6. 
   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.
   
7. 
   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.
   
8. 
   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).
   
9. 
   Copy the _chapt field from the CPMGetRowsIn message to a CPMGetRowsOut message to be sent.
   
10. 
    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.
  

• 
  CRowSeekByBookmark is specified.
  

11. 
    Store the fetched rows in the Rows field (see section 2.2.3.12 for details on the structure of the Rows field).
    

12. 
    Respond to the client with the CPMGetRowsOut message.
    

13. 
    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.
  

7. Receiving a CPMFetchValueIn Request

1. 
   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.
   
2. 
   Prepare a CPMFetchValueOut message. If this step fails for any reason, the server MUST report an error.
   
3. 
   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].
   
4. 
   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.
  

5. 
   Respond to the client with the CPMFetchValueOut message.
   
6. 
   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.
  

8. Receiving a CPMSetBindingsIn Request

1. 
   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.
   
2. 
   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>
   
3. 
   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>
   
4. 
   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.
   
5. 
   Respond to the client with a message header (only), with _msg set to CPMSetBindingsIn and _status set to the results of the specified binding.
   
6. 
   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.
  

9. Receiving a CPMGetNotify Request

1. 
   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>
   
2. 
   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.
   
3. 
   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.
   
4. 
   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.
  

10. Receiving a CPMGetApproximatePositionIn Request

1. 
   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.
   
2. 
   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.
   
3. 
   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.
   

4. 
   Respond to the client with a CPMGetApproximatePositionOut message.
   
5. 
   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.
  

11. Receiving a CPMCompareBmkIn Request

1. 
   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.
   
2. 
   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.
   
3. 
   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.
    

4. 
   Respond to the client with the configured CPMCompareBmkOut message.
   
5. 
   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.
  

12. Receiving a CPMRestartPositionIn Request

1. 
   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.
   
2. 
   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.
   
3. 
   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.
   

4. 
   Respond to the client with a CPMRestartPositionIn message.
   
5. 
   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.
  

13. Receiving a CPMFreeCursorIn Request

1. 
   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.
   
2. 
   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>
   
3. 
   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.
   
4. 
   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.
   
5. 
   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.
  

14. Receiving a CPMDisconnect Request

• 
  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.
  

15. Receiving a CPMFindIndicesIn Request

1. 
   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.
   
2. 
   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].
   
3. 
   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.
   

4. 
   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.
  

16. Receiving a CPMGetRowsetNotifyIn

1. 
   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.
   
2. 
   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].
   
3. 
   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.
   
4. 
   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.
  

17. Receiving a CPMGetScopeStatisticsIn

1. 
   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.
   
2. 
   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].
   
3. 
   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.
   

4. 
   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.
  

18. Receiving a CPMSetScopePrioritizationIn

1. 
   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.
   
2. 
   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].
   
3. 
   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.
   
4. 
   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.
   
5. 
   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.
   
6. 
   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.
  

6. 
   
   Download 349,46 Kb.