Share via

3.1.4.7.1 GetClientTableInfo (Opnum 3)

  • Article

This method is called by a client to retrieve the table metadata (section 3.1.1.2.1) for a catalog table.

 HRESULT GetClientTableInfo(
   [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] GUID* pRequiredFixedGuid,
   [out, size_is(, *pcbReserved1)] 
     char** ppReserved1,
   [out] ULONG* pcbReserved1,
   [out, size_is(, *pcAuxiliaryGuid)] 
     GUID** ppAuxiliaryGuid,
   [out] ULONG* pcAuxiliaryGuid,
   [out, size_is(, *pcProperties)] 
     PropertyMeta** ppPropertyMeta,
   [out] ULONG* pcProperties,
   [out] IID* piid,
   [out, iid_is(piid)] void** pItf,
   [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 by the table identified by pTableIdentifier.

pQueryCellArray: A QueryCellArray (section 2.2.1.5) structure, marshaled in the negotiated format, as specified in section 2.2.1.5, for a supported query (see section 3.1.1.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) on the table identified by pTableIdentifier.

cbQueryComparison: The size in bytes of pQueryComparison.

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

pRequiredFixedGuid:  A pointer to a variable that, upon successful completion, MUST be set to {92AD68AB-17E0-11D1-B230-00C04FB9473F} and SHOULD<285> be ignored on receipt.

ppReserved1: A pointer to a variable that, upon successful completion, MUST be set either to NULL or to the location of an empty string and MUST be ignored on receipt.

pcbReserved1: A pointer to a variable that, upon successful completion, MUST be set to two if ppReserved1 points to an empty string, or to zero if ppReserved1 points to NULL, and MUST be ignored on receipt.

ppAuxiliaryGuid: A pointer to a variable that, upon successful completion, MUST be set to the AuxiliaryGuid value specified in the definition of the table identified by pTableIdentifier, and NULL if the table definition specifies no such value. This value SHOULD<286> be ignored on receipt.

pcAuxiliaryGuid: A pointer to a variable that, upon successful completion, MUST be the number of elements in ppAuxiliaryGuids (zero or one).

ppPropertyMeta: A pointer to a variable that, upon successful completion, MUST be set to an array of PropertyMeta (section 2.2.1.7) structures representing the schema (see section 3.1.1.1) for the table identified by pTableIdentifier in the negotiated catalog version.

pcProperties: A pointer to a variable that, upon successful completion, MUST be set to the length of the array returned in ppPropertyMeta.

piid: A pointer to a variable that, upon successful completion, MUST be set to IID_ICatalogTableRead (see section 1.9).

pItf: A pointer to a variable that, upon successful completion, MUST be set to the ICatalogTableRead (section 3.1.4.8) interface of the server.

ppReserved2: A pointer to a variable that, upon successful completion, MUST be set to NULL.

pcbReserved2:  A pointer to a variable that, upon successful completion, MUST be set to zero.

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.

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.1.1.5), and fail the call if not.

The server then MUST perform parameter validation as follows:

  • The server SHOULD<287> 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<288> verify that the value reference by pTableIdentifier is the table identifier of a Table (section 3.1.1.3) defined in section 3.1.1.3 for the negotiated catalog version, and fail the call if not.

  • The server SHOULD <289> 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<290> verify that the query represented by the parameters pQueryCellArray, cbQueryCellArray, pQueryComparison, and cbQueryComparison is a supported query (see section 3.1.1.2) on the table identified by pTableIdentifier, and fail the call if not.

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

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

  • The values referenced ppAuxiliaryGuid, pcAuxiliaryGuid, ppPropertyMeta, and pcProperties MUST be set to the values specified in the table definition (see section 3.1.1.3) of the table identified by pTableIdentifier for the negotiated catalog version, and fail if it cannot.