3.1.7 Other Local Events

  • Article

This section describes the use of several abstract interfaces.

IsCatalogAvailable

This abstract interface is used to determine whether the specified catalog is available for querying.

Inputs: CatalogName, a VT_BSTR, the name of the desired catalog.

Outputs: IsAvailable, a Boolean, true if and only if all of the following conditions are met.

  • The catalog name matches a supported catalog implemented by the service (case-insensitive). All versions of WSS covered in this document support only the catalog with name "Windows\SYSTEMINDEX".

  • The Generic Search Service (GSS) is currently able to return results for queries. This is implementation-specific and can be used by other implementations, for example, to communicate the temporary unavailability of the server during initialization.

GetServerVersions

This abstract interface is used to retrieve the Generic Search Service (GSS) version, as well as version information about the operating system and the natural language components on the operating system on which GSS runs.

Inputs: None.

Outputs: DWORD dwWinVerMajor, DWORD dwWinVerMinor, DWORD dwNLSVerMajor, DWORD dwNLSVerMinor, DWORD serverVersion, Boolean supportsVersioningInfo.

Constraints: If the server supports reporting versioning information, return dwWinVerMajor, dwWinVerMinor, dwNLSVerMajor, and dwNLSVerMinor according to section 3.1.5.2.1, and set supportsVersioningInfo to true. Otherwise, set supportsVersioningInfo to false. In both cases, serverVersion MUST be returned.

GetState

This abstract interface returns information about the Generic Search Service (GSS).

Inputs: None.

Outputs: The parameters of a CPMCiStateInOut message, as described in section 2.2.3.1.

Constraints: None.

StoreClientInformation

This abstract interface is used to communicate the client information to the GSS upon client connection via a CPMConnectIn (section 2.2.3.2) message. This information will be used later for access checks on query results for this client. This information is released upon the call to ReleaseQuery.

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • ConnectMessage, a CPMConnectIn message.

  • NamedPipeHandle, the named pipe handle over which the client has connected.

Outputs: None.

RunNewQuery

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • Query information:

    • ProjectionColumnsOffsets: A CColumnSet structure containing the property offsets for properties in CPidMapper that are returned as columns. For example, if RunNewQuery was being generated from SQL, these columns would correspond to the arguments of the SELECT statement.

    • RestrictionSet: A CRestrictionArray structure containing the command tree of the query. In the case of a multi-level grouping query, these restrictions apply only to the filtered set found at the leaf level.

    • SortOrders: A CSortSet structure indicating the sort order of the query. The sort set also applies only to the set of results found at the leaf level, in the case of a multi-level grouping query.

    • Groupings: A CCategorizationSet structure that contains the groups for the query, aggregate properties to return and any sort orders for non-leaf levels in the hierarchical rowset.

    • RowSetProperties: A CRowsetProperties structure providing configuration information for the query.

    • PidMapper: A CPidMapper structure that maps from property offsets to full property descriptions.

    • GroupArray: A CColumnGroupArray structure, describing property weights for probabilistic ranking.

    • Lcid: A 32-bit unsigned integer, indicating the user's locale for this query, as specified in [MS-LCID].

Outputs:

  • CanRunQueryNow: Boolean, true if and only if another query is not already in progress. A query is defined to be in progress at any time between (a) and (b):

    • Any time when RunNewQuery was called with QueryIdentifier as an argument and returned true and QueryParametersError (see following) was returned as zero.

    • The first time ReleaseQuery was called with QueryIdentifier as an argument after (a) and returned true.

  • QueryParametersError: This is a DWORD set either to 0 for success or one of the values below:

    Value

    Description

    QUERY_E_ALLNOISE

    0x80041605

    The query contained only ignored words.

    QUERY_E_DIR_ON_REMOVABLE_DRIVE

    0x8004160B

    Specified directory is on a removable medium.

    QUERY_E_DUPLICATE_OUTPUT_COLUMN

    0x80041608

    One or more columns in the output column list are duplicate.

    QUERY_E_FAILED

    0x80041600

    Call failed for unknown reason.

    QUERY_E_INVALIDQUERY

    0x80041601

    Invalid parameter.

    QUERY_E_INVALIDRESTRICTION

    0x80041602

    The query restriction could not be parsed.

    QUERY_E_TIMEDOUT

    0x80041607

    The query exceeded its execution time limit. The time limit is defined by the _cCmdTimeout property in the RowSetProperties argument.

    QUERY_E_TOOCOMPLEX

    0x80041606

    The query was too complex to be executed. Normally this refers to the maximum number of nodes in the restriction tree. Currently, the WSS maximum is set in the Windows Registry to 520,000.

    QUERY_S_NO_QUERY

    0x8004160C

    The catalog is in a state where indexing continues, but queries are not allowed.

  • CursorHandlesList: If QueryParametersError is 0, return a list of cursor handles, otherwise return an empty list.

  • fTrueSequential: A Boolean. In GSS, its meaning is as described in CPMCreateQueryOut (section 2.2.3.5).<36>

  • fWorkidUnique: A Boolean. This is set to true unless the GSS is unable to return results.

Constraints:

  • The cursor handles in the returned CursorHandlesList MUST be different from each other.

  • The number of cursor handles returned is equal to the number of categories in the Groupings parameter and every returned handle identifies the results in the same-index category in the Groupings parameter. These handles will be referenced in later invocations of abstract interfaces such as GetRows.

  • For the query provided in the CPMCreateQueryIn message, the server can use the inverted index in such a way that query results will likely be delivered faster. Otherwise, there would be a greater latency in delivering query results.

  • fWorkidUnique: This is set to true as long as the GSS is able to return results.

  • GroupArray constraint: Any CColumnGroup present in GroupArray MUST have the _groupPid value high bits set to 0x7fff. In other words: (0xFFFF0000 & _groupPid) == 0x7FFF0000. Moreover, the low bits value: 0x0000ffff || _groupPid MUST represent the index of the group property entry in the PidMapper aPropSpec array. The abovementioned CfullPropspec entry in the PidMapper aPropSpec array MUST be identical to the _Property CfullPropspec of any CProbRestriction in the RestrictionSet that references this CColumnGroup.

ClientQueryHasCursorHandle

This abstract interface tests whether a client query has a given cursor handle associated.

Inputs:

  • QueryIdentifier: A 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle: A 32-bit unsigned integer.

Outputs:

  • ContainsHandle: A Boolean, true if and only if the last RunNewQuery call that didn't return an error and that had QueryIdentifier as its argument returned CursorHandle as one of the CursorHandlesList handles.

Constraints:

  • If ReleaseCursor has been called with the QueryIdentifier and CursorHandle parameters, then ContainsHandle MUST be set to false.

GetQueryStatus

This abstract interface retrieves information about the status of the query.

Inputs:

  • QueryIdentifier: A 32-bit unsigned integer. This value uniquely identifies a query to this server.

Outputs:

  • QueryStatus: A 32-bit unsigned integer.<37>

  • Error: An HRESULT set to 0 if no error was encountered. Otherwise, this value is set to any error code encountered in performing the request in accordance with Win32 Error Codes in [MS-ERREF].

GetRatioFinishedParams

This abstract interface retrieves information about the current state of query processing.

Inputs:

  • QueryIdentifier: A 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle: A 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

Outputs:

  • rdwRatioFinishedDenominator: A 32-bit unsigned integer identifying the number of currently computed results that satisfy the RestrictionSet passed in the last successful call to RunNewQuery with the same QueryIdentifier argument. In WSS, the number of computed results satisfying the RestrictionSet is known before the SortOrders + Groupings. This value represents the total number of results for the query.

  • rdwRatioFinishedNumerator: A 32-bit unsigned integer identifying the number of currently computed results that satisfy both the RestrictionSet and the SortOrders + Groupings passed in the last successful call to RunNewQuery with the same QueryIdentifier argument. In WSS, this number can differ from rdwRatioFinishedDenominator because it is possible to compute the denominator before calculating the SortOrders + Groupings. The rdwRatioFinishedNumerator represents the number of results that have currently been computed with the correct SortOrders + Groupings.

  • cRows: A 32-bit unsigned integer indicating the total number of results for the query. In WSS versions after Windows Search 4.0, this value was trivially set to zero because this output parameter is no longer used by any Windows clients.

  • fNewRows: A Boolean value that is true if and only if there are more results than have already been requested via the GetRows abstract interface. In WSS versions greater than or equal to Windows Search 4.0, this is true if and only if rdwRatioFinishedDenominator != rdwRatioFinishedNumerator.

Constraints:

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, the behavior of GetRatioFinishedParams is undefined.

  • rdwRatioFinishedDenominator MUST be greater than or equal to rdwRatioFinishedNumerator.

  • rdwRatioFinishedNumerator MUST be greater than or equal to the maximum index of any row returned via the GetRows abstract interface called with QueryIdentifier and CursorHandle arguments.

  • rdwRatioFinishedDenominator MUST be smaller than or equal to rcRowsTotal returned by calling the GetExpensiveProperties abstract interface called with QueryIdentifier and CursorHandle arguments.

  • cRows has the same semantics and has to have an identical value to that of rcRowsTotal returned by calling the GetExpensiveProperties abstract interface called with QueryIdentifier and CursorHandle arguments.

GetApproximatePosition

This abstract interface retrieves the approximate position of a bookmark within a rowset.

Inputs:

  • QueryIdentifier: A 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle: A 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

  • Bmk: A 32-bit value indicating the handle of a bookmark whose position is to be retrieved.

Outputs:

  • riRowBmk: A 32-bit unsigned integer identifying the approximate position of the bookmark in the rowset identified by CursorHandle for the query identified by QueryIdentifier.

Constraints:

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, the behavior of GetApproximatePosition is undefined.

GetWhereID

This abstract interface retrieves the query identifier of a given query.<38>

Inputs:

  • QueryIdentifier: A 32-bit unsigned integer. This value uniquely identifies a query to this server.

Outputs:

  • whereID: A 32-bit unsigned integer that defines a unique WHEREID for referring to the RestrictionSet CRestrictionArray argument to the latest successful RunNewQuery abstract interface call. This restriction can be reused as a restriction in future calls to RunNewQuery as long as there is still a cursor corresponding to the cursor handles returned by the latest successful call to RunNewQuery that has not been freed using ReleaseQuery. This provides the GSS the option of sharing the evaluation of the restriction across queries.

Constraints:

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, then the behavior of GetRatioFinishedParams is undefined.

  • The same value for whereID is provided during any subsequent calls to GetWhereID that have the same QueryIdentifier argument.

GetExpensiveProperties

This abstract interface retrieves expensive properties. Specifically, these are properties that are evaluated over the entirety of the result set and are thus expensive to compute.

Inputs:

  • QueryIdentifier: A 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle: A 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

Outputs:

  • rcRowsTotal: A 32-bit unsigned integer specifying the total number of rows in the rowset.

  • rdwResultCount: A 32-bit unsigned integer specifying the number of unique results returned in the rowset.

  • Maxrank: A 32-bit unsigned integer specifying the maximum rank found in the rowset.

Constraints:

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, then the behavior of GetExpensiveProperties is undefined.

  • The GSS MUST NOT output any parameters if the DONOTCOMPUTEEXPENSIVEPROPERTIES property wasn't set in the RowSetProperties argument to the last successful RunNewQuery abstract interface call with the QueryIdentifier argument.

  • rcRowsTotal MUST be greater than or equal to the maximum index of any row returned via the GetRows abstract interface called with QueryIdentifier and CursorHandle arguments at any time in the past or future.

  • rdwResultCount MUST be smaller than rcRowsTotal.

  • Maxrank MUST be greater than or equal to maximum rank of any row returned via the GetRows abstract interface called with QueryIdentifier and CursorHandle arguments at any time in the past or future.

HasBindings

This abstract interface informs the caller about whether the GSS has a set of bindings for the specified query and cursor.

Inputs:

  • QueryIdentifier: A 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle: A 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

Outputs:

  • hasBindings: A Boolean, true if and only if the SetBindings abstract interface was called successfully with QueryIdentifier and CursorHandle as arguments.

Constraints:

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, then the behavior of GetRatioFinishedParams is undefined.

  • Bindings cannot be set for cursors identifying rowsets for non-leaf categorization levels.

GetBookmarkPosition

This abstract interface retrieves the position within a rowset of a given bookmark.

Inputs:

  • QueryIdentifier: A 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle: A 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

  • bmkHandle: A 32-bit unsigned integer identifying the bookmark within this rowset.

Outputs:

  • bmkIndex: A 32-bit unsigned integer identifying the position within the rowset of the bookmark provided.

Constraints:

  • Stability: This abstract interface needs to provide the same bmkIndex if and only if its arguments: QueryIdentifier, CursorHandle, and bmkHandle are the same.

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, then the behavior of this interface is undefined.

SetNextGetRowsPosition

This abstract interface allows the caller to instruct the GSS to store the index within the rowset where to return results from next via the GetRows abstract interface.

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle, a 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

  • Chapter, a chapter identifying the range of rows of interest within the rowset identified by CursorHandle.

  • Index, a 32-bit unsigned integer identifying where the next row will be retrieved from.

Outputs: None.

Constraints:

  • If no error occurred, then any subsequent call to GetNextGetRowsPosition with the QueryIdentifier, CursorHandle and chapter arguments will return the Index value.

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, then the behavior of this interface is undefined.

GetNextGetRowsPosition

This abstract interface retrieves the index within the rowset where the GSS will return results from next via the GetRows abstract interface.

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle, a 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

  • Chapter, a chapter identifying the range of rows of interest within the rowset identified by CursorHandle.

Outputs:

  • Index, a 32-bit unsigned integer identifying the location of the next row to be retrieved.

Constraints:

  • See the first constraint under the SetNextGetRowsPosition abstract interface.

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, then the behavior of this interface is undefined.

GetRows

This abstract interface returns rows requested for the specified query and cursor. The position from which it returns rows can be set through the SetNextRowsPosition abstract interface.

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle, a 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

  • NumRowsRequested, a 32-bit unsigned integer identifying the number of rows to be retrieved.

  • FetchForward, a 32-bit unsigned integer identifying whether the rows are to be fetched in forward order or in reverse. (0x00000000 for forward, 0x00000001 for reverse)

  • Workid, a 32-bit unsigned integer representing the document ID identifying the document for which a property is to be fetched.

Outputs:

  • RowsArray, an array of rows, with properties consistent with the bindings set via the last successful SetBindings call. See the second constraint.

  • NoMoreRowsToReturn, a Boolean, true if and only if there are no more results to return that satisfy the query associated with NamedPipe for the cursor associated with CursorHandle.

  • NumRowsReturned, a 32-bit unsigned integer identifying the number of rows returned.

  • Error, a 32-bit unsigned integer identifying the error HRESULT of any error incurred during row retrieval.

Constraints:

  • Results MUST be stable with respect to latest position set in SetNextGetRowsPosition. Mathematically, these conditions need to be met:

    • for any 32-bit unsigned integer i satisfying 1 <= i <= totalNumberOfResults, calling SetNextGetRowsPosition(QueryIdentifier, CursorHandle, i), and then GetRows(QueryIdentifier, CursorHandle, 1, 0) MUST produce the same result at any time this query is active (a query is active between a successful RunNewQuery call and a ReleaseQuery call with the QueryIdentifier argument)

    • for any 32-bit unsigned integers i, j, k satisfying 1 <= i  <= k <= j <= totalNumberOfResults, calling SetNextGetRowsPosition(QueryIdentifier, CursorHandle, i), and then GetRows(QueryIdentifier, CursorHandle, j-i+1, 0) MUST produce the same (k – i +1)th  row as the first and only row obtained by calling SetNextGetRowsPosition(QueryIdentifier, CursorHandle, k), and then GetRows(QueryIdentifier, CursorHandle, 1, 0)

    • same stability conditions MUST hold true when fetching results in reverse (FetchForward = 0x00000001)

  • Index must be updated by any retrieval: Any GetNextGetRowsPosition call with the same NamedPipeHandle and CursorHandle arguments made after the GetRows call must reflect the updated index: its value is incremented by NumRowsReturned or, if FetchForward was set to 0x00000001, then minus-NumRowsReturned.

  • Result consistence with bindings:

    • When fetching rows, the GSS MUST compare each selected column's property value type to the type that is specified in the client's current set of bindings as set in the SetBindings abstract interface call with the same QueryIdentifier and CursorHandle as arguments. If the type in the binding was not VT_VARIANT, the GSS MUST attempt to convert the column's property value to that type. Otherwise, if the DBPROP_USEEXTENDEDDBTYPES flag was set in the client's DBPROPSET_QUERYEXT property set, or if the column's property value was not a VT_VECTOR type, the property value MUST be returned in its normal type. If none of these are the case (that is, the server has a VT_VECTOR type, and the client does not support VT_VECTOR), the server MUST attempt to convert it to a VT_ARRAY type as follows:

      • VT_I8, VT_UI8, VT_FILETIME, and VT_CLSID array elements cannot be converted and instead fail.

      • VT_LPSTR and VT_LPWSTR array elements MUST be converted to VT_BSTR.

      • Array elements of all other types MUST remain unchanged.

        Aggregates are returned as individual columns. They are mostly simple types except for ByFrequency, First, DateRange, and RepresentativeOf which are returned as compound types.

      • ByFrequency: Returns a VT_VECTOR of 3 VT_VECTORs. The first vector contains up to N values (as specified in the ulMaxNumToReturn field in the CAggregSpec). Their types are those specified by the idColumn field in the CAggregSpec. The second vector contains the corresponding count for each value. Their types are numeric (VT_UI4). The third vector contains a representative document identifier for each unique value. Their types are also numeric (VT_UI4).

      • First: Returns a VT_VECTOR of VT_VARIANT values. The number of values is at most N (as specified in the corresponding CAggregSpec)

      • DateRange: Returns a VT_VECTOR containing 2 VT_FILETIME structures. They define the lower bound of the requested range and the upper bound, respectively.

      • RepresentativeOf: Returns a VT_VECTOR of two VT_VECTORs. The first one contains the representative property values as specified in the corresponding CAggregSpec. These returned values are of type VT_VARIANT. There are at most N such values, as specified in the ulMaxNumToReturn field in the CAggregSpec. The second vector contains a corresponding document identifier for each of the values in the first vector. Each of the documents denoted by the above identifiers has the value of the specified property equal to that of the corresponding value in the first vector. The document identifiers returned are of (VT_UI4) types.

  • Results SHOULD satisfy the restrictions passed in the last successful RunNewQuery abstract interface call.

  • Results retrieved from the same chapter as set in SetNextGetRowsPosition SHOULD satisfy the corresponding Groupings entry in the last RunNewQuery abstract interface call with the same NamedPipeHandle argument. Specifically, the returned results SHOULD have the same property as defined by the above mentioned Groupings entry.

  • If the query was a hierarchical grouping query, and if the retrieval in this GetRows call did not refer to the leaf level rowset, then one of the returned properties MUST be a chapter handle that identifies the range of rows in the next level rowset that have the same property as defined by the corresponding Grouping in the previous RunNewQuery call with the same NamedPipeHandle argument.

  • If the requested number of rows was larger than the numbers left between the Index (as returned by a GetNextGetRowsPosition call with the same NamedPipeHandle and CursorHandle arguments) and the end of the rowset, NoMoreRowsToReturn MUST be set to true, and only as many rows as are present MUST be returned.

  • Every row returned by the GSS MUST be ACL checked:

    When returning a row, the GSS MUST take the document identifier field of that row and call the HasAccessToWorkid abstract interface with QueryIdentifier and Workid as arguments. If it does not return true, then the GSS MUST skip this row.

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, then the behavior of this interface is undefined.

HasAccessToWorkid

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • Workid, a 32-bit unsigned integer representing the document ID identifying the document for which permissions need to be checked.

Outputs:

  • HasAccess, a Boolean, set to true if and only if the client as identified by the information passed during the StoreClientInformation abstract interface call with the same QueryIdentifier argument has file system access to the file identified by Workid.

    Specifically, this is done based on the Windows security permissions of the user identified by the security credentials received via the named pipe connection corresponding to the NamedPipeHandle argument passed to the last call to StoreClientInformation with the QueryIdentifier argument.

HasAccessToProperty

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • PropSpec, a CFullPropSpec structure specifying the property to determine access to

Outputs:

  • HasAccess, a Boolean, set to true if and only if the client as identified by the information passed during the StoreClientInformation abstract interface call with the same QueryIdentifier argument has file system access to the property identified by PropSpec.

    The access check is the same as the one in HasAccessToProperty.

GetPropertyValueForWorkid

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • Workid, a 32-bit unsigned integer representing the document ID identifying the document for which a property is to be fetched.

  • PropSpec, a CFullPropSpec structure specifying the property to retrieve.

Outputs:

  • Property, a SERIALIZEDPROPERTYVALUE structure containing the property specified in PropSpec for the document identified by Workid.

  • ValueExists, a Boolean set to true if and only if the specified property exists on the server and if the client has access to it. This MUST be determined by calling the HasAccessToProperty abstract interface with QueryIdentifier and PropSpec as arguments.

Constraints:

  • Consistency across calls: Any two calls to GetPropertyValueForWorkid with the same arguments must return the same result.

  • Consistency with the properties returned from GetRows: any row returned as part of the GetRows abstract interface call with the same QueryIdentifier argument that has the workid field identical to Workid MUST have the same value of the property identified by PropSpec (if requested and present) as the one returned here as the Property output parameter.

SetBindings

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle, a 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

  • Columns, an array of CTableColumn structures describing the columns of a row in the rowset.

Outputs:

  • Error, a 32-bit unsigned integer identifying any error for this operation. If this step fails for any reason, the GSS MUST report any error code encountered in performing the request in accordance with Win32 Error Codes in [MS-ERREF].

Constraints:

  • Other abstract interfaces such as GetRows have documented constraints that refer to the Columns passed in this call.

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, then the behavior of this interface is undefined.

GetQueryStatusChanges

This abstract interface provides information about any query status changes that have occurred since the last time it was called.<39>

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle, a 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

Outputs:

  • LatestChange, a 32-bit unsigned integer representing the change to the query. It MUST be one of the following values.

    Value

    Meaning

    DBWATCHNOTIFY_ROWSCHANGED

    0x00000001

    The number of rows in the query rowset has changed.

    DBWATCHNOTIFY_QUERYDONE

    0x00000002

    The query has completed.

    DBWATCHNOTIFY_QUERYREEXECUTED

    0x00000003

    The query has been executed again.

  • ChangesPresent, a Boolean indicating whether there have been any changes in query status.

Constraints:

  • If there were no changes in the query result set since the last GetQueryStatusChanges call with the same NamedPipe and CursorHandle arguments, or if this is the first GetQueryStatusChanges call for this query/cursor pair, set ChangesPresent to false.

  • In the case of many changes to query results, DBWATCHNOTIFY_ROWSCHANGED takes priority (that is, if the query was performed, re-executed, and then the number of rows changed and the query was performed again, then the event reported would be DBWATCHNOTIFY_ROWSCHANGED).

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, then the behavior of this interface is undefined.

ReleaseCursor

This interface instructs the GSS to release all resources associated with a cursor of a query.

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • CursorHandle, a 32-bit unsigned integer identifying the rowset of interest in the query identified by the QueryIdentifier.

Outputs:

  • NumCursorsRemaining, a 32-bit unsigned integer representing the number of cursors remaining for this query.

Constraints:

  • This abstract interface assumes that the caller has already called ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments, respectively, and that the abstract interface has returned true. If this is not the case, then the behavior of this interface is undefined.

  • Any further calls to ClientQueryHasCursorHandle with the QueryIdentifier and CursorHandle arguments will return false.

  • NumCursorsRemaining has an initial value equal to the number of cursor handles returned by the previous call to RunNewQuery with the QueryIdentifier argument. It gets decremented with every ReleaseCursor call with the QueryIdentifier argument.

  • If the NumCursorsRemaining is zero, then the GSS MUST call ReleaseQuery with the QueryIdentifier argument.

ReleaseQuery

This interface instructs the GSS to release all resources associated with a query, including the information stored during StoreClientInformation.

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

Outputs: None.

Constraints:

  • The GSS MUST call ReleaseCursor with the QueryIdentifier argument for all cursor handles that were returned by the RunNewQuery that haven't already been released via ReleaseCursor with the QueryIdentifier argument.

FindNextOccurrenceIndex

This interface allows retrieval of the next occurrence of a document within the result set of a hierarchicaly grouped query.<40>

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • PrevOccCoordinatesList, a list of 32-bit unsigned integer signifying the group coordinates of the previous occurrence of the desired document within the query results. This is NULL if the caller requests the first occurrence within the rowset of the specified document.

  • Workid, the document identifier for the desired document.

Outputs:

  • NextOccExists, a Boolean set to true if and only if a "next" occurrence exists.

  • NextOccCoordinatesList, a list of 32-bit unsigned integers signifying the group coordinates of the next occurrence of the desired document within the query results.

Constraints:

  • Coordinates start at "1" rather than "0".

  • Example: Consider grouping the following 4 results on Author at the top level and Keywords at the second level:

     file1.txt
 Author: 'author1'
 Keywords: 'key1'
  
 file2.txt
 Author: 'author1'
 Keywords: 'key2'
  
 file3.txt
 Author: 'author1'
 Keywords: 'key2'
  
 file4.txt
 Author: 'author2'
 Keywords: 'key3'

    That grouping generates the following groups:

     Author = 'author1'
     Keywords = 'key1'
         file1.txt
     Keywords = 'key2'
         file2.txt
         file3.txt
 Author = 'author2'
     Keywords = 'key2'
         file4.txt

    Then, the hierarchical grouping coordinate of the 'file3.txt' result will be <1, 2, 2>. The first integer in the coordinate, '1', represents the first Author category (labeled 'author1'). The second integer, '2', represents the second Keywords category within the 'author1' top level group (labeled 'key2'). Finally, the third integer, '2', represents the second result in the 'key2' category within the top level 'author1' group.

GetLastUnretrievedEvent

This abstract interface retrieves the last event that hasn't been reported yet. Events are scoped only to the result set of the current query.<41>

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

Outputs:

  • Wid, a 32-bit unsigned integer containing the document identifier that the event is for. This value MUST be zero if eventType is PROPAGATE_NONE or PROPAGATE_ROWSET.

  • EventType, a 7-bit unsigned integer that MUST be one of the following values, indicating the type of event this message represents.

    Value

    Meaning

    PROPAGATE_NONE

    0

    This event indicates that there were no available rowset events waiting on the server.

    PROPAGATE_ADD

    1

    This event indicates that an item was added to the index that could be relevant to the query originating the rowset.

    PROPAGATE_DELETE

    2

    This event indicates that an item was deleted from the index that could be relevant to the query originating the rowset.

    PROPAGATE_MODIFY

    3

    This event indicates that an item was re-indexed that could be relevant to the query originating the rowset.

    PROPAGATE_ROWSET

    4

    This event is a rowset specific notification whose meaning is interpreted by the rowsetEvent field of this message.

  • MoreEvents, a single bit that is set to 1 only if there are additional rowset events remaining.

  • RowsetItemState, an 8-bit unsigned integer that MUST be one of the following values if EventType is PROPAGATE_ADD, PROPAGATE_DELETE, or PROPAGATE_MODIFY. This number indicates the state of the document identifier specified by Wid within the originating rowset associated with the query identified by the QueryIdentifier argument. For other EventType values this value MUST be set to zero.

    Value

    Meaning

    ROWSETEVENT_ITEMSTATE_NOTINROWSET

    0

    The document identifier specified by Wid MUST NOT have been contained within the originating rowset.

    ROWSETEVENT_ITEMSTATE_INROWSET

    1

    The document identifier specified by wid MUST be contained within the originating rowset.

    ROWSETEVENT_ITEMSTATE_UNKNOWN

    2

    The document identifier specified by wid's containment within the originating rowset is unknown to the GSS.

  • ChangedItemState, an 8-bit unsigned integer that MUST be one of the following values if EventType is PROPAGATE_MODIFY. This number indicates the state of the document identifier specified by Wid within the originating rowset associated with the query identified by the QueryIdentifier argument if the same query were to be run again following the change. For other EventType values, this value MUST be set to zero.

    Value

    Meaning

    ROWSETEVENT_ITEMSTATE_NOTINROWSET

    0

    The document identifier specified by Wid would NOT be contained within a subsequent query.

    ROWSETEVENT_ITEMSTATE_INROWSET

    1

    The document identifier specified by Wid would be contained within a subsequent query.

    ROWSETEVENT_ITEMSTATE_UNKNOWN

    2

    Whether or not the document identifier specified by wid would be contained within a subsequent query is unknown to the GSS.

  • RowsetEvent, an 8-bit unsigned integer that MUST be one of the following values if EventType is PROPAGATE_ROWSET. This number indicates the type of rowset event that this message represents. For other EventType values, this value MUST be set to zero.

    Value

    Meaning

    ROWSETEVENT_TYPE_DATAEXPIRED

    0

    The data backing the rowset is no longer valid.

    RowsetEventData1 and RowsetEventData2 MUST be set to zero.

    ROWSETEVENT_TYPE_FOREGROUNDLOST

    1

    The rowset no longer has foreground priority and has been reverted to high priority. Items that apply to this query will be indexed at a decreased rate. See section 2.2.3.34 for meaning of foreground and high priority.

    RowsetEventData1 and RowsetEventData2 MUST be set to zero.

    ROWSETEVENT_TYPE_SCOPESTATISTICS

    2

    The number of indexed items, number of items that need to be indexed, or number of items that need indexing has changed.

    RowsetEventData1's high 32 bits contain a 32-bit unsigned integer indicating the number of items that need to be indexed that could be relevant to the originating rowset.

    RowsetEventData1's low 32 bits contain a 32-bit unsigned integer indicating the number of items that need to be re-indexed that could be relevant to the originating rowset.

    RowsetEventData2's high 32 bits MUST be set to zero.

    RowsetEventData2's low 32 bits contain a 32-bit unsigned integer indicating the number of indexed items that could be relevant to the originating rowset.

  • RowsetEventData1, a 64 bit unsigned number whose meaning is dependent on RowsetEvent.

  • RowsetEventData2, a 64 bit unsigned number whose meaning is dependent on RowsetEvent.

Constraints:

  • The GSS MUST indicate the type of event response in EventType. All output parameters MUST be zero when not contributing to the value specified by EventType. The following fields MUST be set based upon the following event types.

    • PROPAGATE_NONE—EventType MUST be set to this value to indicate that there are no events available. No other fields are relevant to this response.

      Note:  This is the only response possible if the last call to RunNewQuery with the QueryIdentifier argument did not have eEnableRowsetEvents set in the RowSetProperties argument.

    • PROPAGATE_ADD— EventType MUST be set to this value to indicate that a new item was added to the index that could be relevant to the associated query (the query identified by the NamedPipeHandle argument). Wid MUST be set to the document identifier for the newly added document. RowsetItemState MUST be set either to indicate if the item would be included in the associated query if the query were executed again, or to indicate that this is unknown. MoreEvents SHOULD be set to indicate whether there is another event of any non-PROPAGATE_NONE type immediately available.

    • PROPAGATE_DELETE— EventType MUST be set to this value to indicate that an existing item was deleted from the index that could be relevant to the associated query. Wid MUST be set to the document identifier for the deleted document. RowsetItemState MUST be set either to indicate whether the document identifier is contained within the rowset, or to indicate that this is unknown. MoreEvents SHOULD be set to indicate whether there is another event of any non-PROPAGATE_NONE type immediately available.

    • PROPAGATE_MODIFY— EventType MUST be set to this value to indicate that an existing item was re-indexed and this item could have been previously relevant to the associated query or could have become relevant to the associated query as a result of being re-indexed. Wid MUST be set to the document identifier for the re-indexed document. rowsetItemState MUST be set either to indicate if the document identifier is contained within the rowset, or to indicate that this is unknown. ChangedItemState MUST be set to indicate if the item would be included in the associated query if the query were executed again or MUST be set to indicate that this is unknown. MoreEvents SHOULD be set to indicate if there is another event of any non PROPAGATE_NONE type immediately available.

    • PROPAGATE_ROWSET— EventType MUST be set to this value when the event is a non-item based event. Wid MUST be zero and RowsetEvent SHOULD be set to a value indicating the type of rowset event. Other fields MUST be set based upon this type as follows. Any field not specified explicitly below MUST be set to zero.

      • ROWSETEVENT_TYPE_DATAEXPIRED—RowsetEvent MUST be set to this value when the server wants to indicate that the data associated with the backing query could no longer be valid.

      • ROWSETEVENT_TYPE_FOREGROUNDLOST— RowsetEvent MUST be set to this value when the server wants to indicate that the associated query's explicitly requested priority has been changed from FOREGROUND to HIGH via a SetScopePriority abstract interface call with the same QueryIdentifier argument.

      • ROWSETEVENT_TYPE_SCOPESTATISTICS— RowsetEvent MUST be set to this value when sending an update due to a change in the number of indexed items, number of items that need to be indexed, or number of items that need to be re-indexed when these items are relevant to the associated query. RowsetEventData1's high 32 bits MUST contain an unsigned integer indicating the number of items that need to be indexed that could be relevant to the associated query. RowsetEventData1's low 32 bits MUST contain an unsigned integer indicating the number of items that need to be re-indexed that could be relevant to the associated query. RowsetEventData2's high 32 bits MUST be zero. RowsetEventData2's low 32 bits MUST contain the number of indexed items that could be relevant to the originating rowset.

  • The GSS SHOULD NOT cache events unless they have explicitly requested by having called the RunNewQuery abstract interface with the same QueryIdentifier argument and with DBPROP_ENABLEROWSETEVENTS property to TRUE in the RowSetProperties argument. If this hasn't been the case, this call to GetLastUnretrievedEvent MUST return a PROPOGATE_NONE event.

  • If the FilterOutScopeStatisticsMessages was called with the QueryIdentifier argument, then the GSS MUST NOT return ROWSETEVENT_TYPE_SCOPESTATISTICS events.

GetQueryStatistics

This abstract interface retrieves information about results of the specified query.<42>

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

Outputs:

  • NumIndexedItems, a 32-bit unsigned integer containing the number of items that are currently indexed that are relevant to the originating query (as identified by the QueryIdentifier argument).

  • NumOutstandingAdds, a 32-bit unsigned integer containing the number of items that have yet to be indexed that could be relevant to the originating query.

  • NumOutstandingModifies, a 32-bit unsigned integer containing the number of items that need to be re-indexed and that are relevant to the originating query.

Constraints:

  • All output arguments MUST be set to zero if their availability has not been explicitly requested by having called the RunNewQuery abstract interface with the same QueryIdentifier argument and with DBPROP_ENABLEROWSETEVENTS property to TRUE in the RowSetProperties argument.

SetScopePriority

This abstract interface instructs the GSS to prioritize indexing of items on a per query basis.<43>

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

  • Priority, a 32-bit unsigned integer containing the type of prioritization requested for documents that could be relevant to the originating query (as defined by QueryIdentifier).

    Value

    Meaning

    PRIORITY_LEVEL_FOREGROUND

    0

    Process items that could be relevant to the originating query before others as quickly as possible.

    PRIORITY_LEVEL_HIGH

    1

    Process items that could be relevant to the originating query before others at the normal rate.

    PRIORITY_LEVEL_LOW

    2

    Process items that could be relevant to the originating query before others, but after any other prioritization requests at the normal rate.

    PRIORITY_LEVEL_DEFAULT

    3

    Process items at the normal rate.

Outputs: None.

Constraints:

  • As a result of this call, the GSS MUST:

    • Prioritize indexing and re-indexing items according to the Priority specified in the Priority argument.

    • Respond with a RowsetEvent ROWSETEVENT_TYPE_SCOPESTATISTICS on the when the GetLastUnretrievedEvent abstract interface is called with the QueryIdentifier argument and there has been a change to the statistics for the originating query.

  • The GSS SHOULD NOT prioritize rowsets unless this has been explicitly requested by having called the RunNewQuery abstract interface with the same QueryIdentifier argument and with DBPROP_ENABLEROWSETEVENTS property to TRUE in the RowSetProperties argument.

FilterOutScopeStatisticsMessages

This abstract interface instructs the GSS against propagating events of type ROWSETEVENT_TYPE_SCOPESTATISTICS from GetLastUnretrievedEvent calls.

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

Outputs: None.

Constraints:

  • The GSS MUST NOT return ROWSETEVENT_TYPE_SCOPESTATISTICS events as part of any GetLastUnretrievedEvent abstract interface call made with the QueryIdentifier argument.

Inflect

This abstract interface retrieves a list of inflected words based on a passed-in string.

Inputs:

  • phrase, a non-null-terminated Unicode string containing the word/phrase to inflect.

Outputs:

  • inflections, an array of non-null-terminated Unicode strings representing inflected versions of the phrase argument.

  • inflectionsCount, a 32-bit unsigned integer representing the count of the inflections array.

Constraints: None – this is left at the latitude of the implementation.

GenerateScopeStatisticsEvent

This abstract interface causes the GSS to generate an event if any new information about the result set is available. The types of new information are described in the GetLastUnretrievedEvent abstract interface to the GSS. GetLastUnretrievedEvent consumes events generated through the GenerateScopeStatisticsEvent abstract interface call and returns them to the user when called.

Inputs:

  • QueryIdentifier, a 32-bit unsigned integer. This value uniquely identifies a query to this server.

Outputs: None.

Constraints:

  • Events generated through this abstract interface to the GSS MUST be the same events that are later returned by the GetLastUnretrievedEvent abstract interface call.