3.1.4.8.1 ReadTable (Opnum 3)

  • Article

This method is called by a client to read entries from a catalog table according to a query.

 HRESULT ReadTable(
   [in] GUID* pCatalogIdentifier,
   [in] GUID* pTableIdentifier,
   [in] DWORD tableFlags,
   [in, size_is(cbQueryCellArray), unique] 
     char* pQueryCellArray,
   [in] ULONG cbQueryCellArray,
   [in, size_is(cbQueryComparison), unique] 
     char* pQueryComparison,
   [in] ULONG cbQueryComparison,
   [in] DWORD eQueryFormat,
   [out, size_is(, *pcbTableDataFixed)] 
     char** ppTableDataFixed,
   [out] ULONG* pcbTableDataFixed,
   [out, size_is(, *pcbTableDataVariable)] 
     char** ppTableDataVariable,
   [out] ULONG* pcbTableDataVariable,
   [out, size_is(, *pcbTableDetailedErrors)] 
     char** ppTableDetailedErrors,
   [out] ULONG* pcbTableDetailedErrors,
   [out, size_is(, *pcbReserved1)] 
     char** ppReserved1,
   [out] ULONG* pcbReserved1,
   [out, size_is(, *pcbReserved2)] 
     char** ppReserved2,
   [out] ULONG* pcbReserved2
 );

pCatalogIdentifier:  The catalog identifier of the COMA catalog. MUST be set to {6E38D3C4-C2A7-11D1-8DEC-00C04FC2E0C7}.

pTableIdentifier:  The table identifier for one of the tables defined in section 3.1.1.3 for the negotiated catalog version.

tableFlags:  An fTableFlags (section 2.2.1.1) value supported (see section 3.1.1.2.3) by the table identified by pTableIdentifier.

pQueryCellArray:  A QueryCellArray structure, marshaled in the negotiated format as specified in section 2.2.1.5, for a supported query (see section 3.1.1.2.2) on the table identified by pTableIdentifier.

cbQueryCellArray:  The size in bytes of pQueryCellArray.

pQueryComparison:  A QueryComparisonData (section 2.2.1.6) structure for a supported query (see section 3.1.1.2.2) on the table identified by pTableIdentifier.

cbQueryComparison:  The size in bytes of pQueryComparison.

eQueryFormat:  MUST be set to eQUERYFORMAT_1 (0x00000001).

ppTableDataFixed:  A pointer to a variable that, upon successful completion, MUST be set to a TableDataFixed structure, marshaled as specified in section 2.2.1.10.

pcbTableDataFixed:  A pointer to a value that, upon successful completion, MUST be set to the length in bytes of the TableDataFixed structure returned in ppTableDataFixed.

ppTableDataVariable:  A pointer to a pointer variable that, upon successful completion, MUST be set to a TableDataVariable structure, marshaled as specified in section 2.2.1.15.

pcbTableDataVariable: A pointer to a value that, upon successful completion, MUST be the length in bytes of the TableDataVariable structure returned in ppTableDataVariable.

ppTableDetailedErrors: A pointer to a variable that, upon successful completion, MUST be set to NULL, and that upon partial failure MAY<291> be set to a TableDetailedErrorArray structure, marshaled as specified in section 2.2.1.17.

pcbTableDetailedErrors: A pointer to a pointer variable that, upon completion, MUST be set to the length in bytes of the TableDetailedErrorArray structure returned in ppTableDetailedErrors if such a structure was returned, and MUST be set to zero otherwise.

ppReserved1: A pointer to a pointer variable that, upon successful completion, MUST be set to NULL when sent by the server and MUST be ignored on receipt by the client.

pcbReserved1: A pointer to a variable that, upon successful completion, MUST be set to zero when sent by the server and MUST be ignored on receipt by the client.

ppReserved2: A pointer to a pointer variable that, upon successful completion, MUST be set to NULL when sent by the server and MUST be ignored on receipt by the client.

pcbReserved2: A pointer to a variable that, upon successful completion, MUST be set to zero when sent by the server and MUST be ignored on receipt by the client.

Return Values: This method MUST return S_OK (0x00000000) on success, and a failure result, as specified in [MS-ERREF] section 2.1, on failure. All failure results MUST be treated identically, with the exception of E_DETAILEDERRORS (0x80110802).

Upon receiving a call to this method, the server MUST verify that catalog version negotiation has been performed by checking the negotiated catalog version (see section 3.2.1.1), and fail the call if not.

The server then MUST perform parameter validation as follows:

  • The server SHOULD<292> verify that the value referenced by pCatalogIdentifier is the catalog identifier of the COMA catalog {6E38D3C4-C2A7-11D1-8DEC-00C04FC2E0C7}, and fail the call if not.

  • The server SHOULD<293> verify that the value referenced by pTableIdentifier is the table identifier of a table defined in section 3.1.1.3 for the negotiated catalog version, and fail the call if not.

  • The server SHOULD<294> verify that tableFlags is a supported table flags value (see section 3.1.1.2.3) for the table identified by pTableIdentifier, and fail the call if not.

  • The server SHOULD<295> verify that the query represented by the parameters pQueryCellArray, cbQueryCellArray, pQueryComparison, and cbQueryComparison is a supported query (see section 3.1.1.2.2) on the table identified by pTableIdentifier, and fail the call if not.

  • The server MUST verify that all other parameters meet the preceding constraints specified.

The server then MUST select from the entries in the table identified by pTableIdentifier the subset of entries that match the query, as specified here. This conceptual procedure describes a possible procedure for selection, provided to facilitate the explanation of how the protocol behaves. This document does not mandate that implementations perform the procedure as described as long as their external behavior is consistent with that described here.

Starting with the full set of entries in the table as the result set, the server MUST perform the following:

  • If the table as defined in section 3.1.1.3 is specified to use table flags as a constraint on a hidden property (see section 3.1.1.2.3), the server MUST remove from the result set all entries that do not conform to this constraint.

  • For each QueryCell (section 2.2.1.4) structure and its corresponding comparison value (together known as a query element) in the query represented by the parameters pQueryCellArray, cbQueryCellArray, pQueryComparison, and cbQueryComparison, the server MUST perform the following:

    • If the IndexOrOption field of the QueryCell structure is a special query option value (indicated by a value greater than or equal to 0xF00000000), the query element represents a special option rather than a constraint. If this value is eSQO_OPTHINT (see section 2.2.1.3), this option is an optimization hint and MUST NOT affect the results of this selection procedure. Behavior of the server on receipt of special options other than eSQO_OPTHINT is undefined, because clients MUST NOT send these values, and they do not affect interoperability.<296>

    • If the IndexOrOption field of the QueryCell structure is an index of a property in the table (indicated by a value strictly less than 0xF00000000), the query element represents a constraint on the property. The server MUST remove from the result set all entries that do not conform to this constraint.

Having selected from the table the result set, the server then MUST construct the structures to be returned in the values referenced by ppTableDataFixed, pcbTableDataFixed, ppTableDataVariable, and pcbTableDataVariable. An empty result set MUST NOT be considered a failure.

The server MUST perform the following:

  • The server MUST arbitrarily order the entries in the result set, assigning to each a unique, zero-based index. These indices MUST be assigned consecutively.

  • For each entry in the result set, in order by index, the server MUST perform the following:

    • For each property in the table, in order by index, the server MUST perform the following:

      • If the property is a non-fixed length property for which the value is non-NULL, the server MUST add a field to the variable-length results as specified for the TableEntryVariable (section 2.2.1.14) structure.

      • The server MUST set the appropriate fields in the fixed-length results as specified for the TableEntryFixed (section 2.2.1.9) structure.

      • If for any reason the server was unable to retrieve the value of the property from its data store, it MUST either fail the call immediately, setting no results and returning an implementation-specific failure result, or replace the property value in the results with an implementation-specific default value and continue. If the server does the latter, it MUST add a TableDetailedError (section 2.2.1.16) record to the detailed error results, using the zero-based index of the entry and the zero-based index of the property to indicate to the client that the value of that property might not be accurate.

    • The server then MUST append the fixed-length and variable-length results for the entry to the TableDataFixed (section 2.2.1.10) and TableDataVariable (section 2.2.1.15) structures.

The server MUST then set the values referenced by the out parameters as follows:

  • The server then MUST set the values referenced by ppTableDataFixed, pcbTableDataFixed, ppTableDataVariable, and pcbTableDataVariable to the constructed TableDataFixed and TableDataVariable structures.

  • If the server generated any TableDetailedError records, it MUST set the values referenced by ppTableDetailedErrors and pcbDetailedErrors to the constructed TableDetailedErrorArray structure. Otherwise, it MUST set the value referenced by ppTableDetailedErrors to NULL and the value referenced by pcbDetailedErrors to zero.

Upon success, the server MUST return S_OK (0x00000000). Upon partial failure (indicated by returning detailed error results), the server MUST return E_DETAILEDERRORS (0x80110802).