Partager via

IColumnsInfo2::GetRestrictedColumnInfo

  • Article

Retrieves column names or column metadata for a row or rowset. Column names are returned in an array of column IDs (DBIDs). Column metadata is returned in an array of DBCOLUMNINFO structures.

For information about column IDs, see Column IDs. For information about DBCOLUMNINFO structures, see IColumnsInfo::GetColumnInfo.

Syntax

HRESULT GetRestrictedColumnInfo(
   DBORDINAL         cColumnIDMasks,
   const DBID        rgColumnIDMasks[ ],
   DWORD             dwFlags,
   DBORDINAL        *pcColumns,
   DBID            **prgColumnIDs,
   DBCOLUMNINFO    **prgColumnInfo,
   OLECHAR         **ppStringsBuffer);

Parameters

  • cColumnIDMasks
    [in] The count of column name masks in rgColumnIDMasks. If cColumnIDMasks is zero, IColumnsInfo2::GetRestrictedColumnInfo enumerates all columns in the row.

  • rgColumnIDMasks
    [in] An array of cColumnIDMasks column name masks used to restrict the set of columns enumerated. All columns whose DBID matches the elements of rgColumnIDMasks or whose names begin with the string contained in the pwszName element of any of the DBIDs in this array will be returned in the enumeration. If cColumnIDMasks is zero, rgColumnIDMasks is ignored.

  • dwFlags
    [in] Reserved. Must be zero.

  • pcColumns
    [out] A pointer to memory in which to return a count of the column names and DBCOLUMNINFO structures returned in prgColumnIDs and prgColumnInfo, respectively. If no columns are described or if the method terminates with an error, ***pcColumns is set to zero.

  • prgColumnIDs
    [out] A pointer to memory in which to return an array of column IDs (DBIDs) containing the requested column names. IColumnsInfo2::GetRestrictedColumnInfo returns either all columns or the columns selected by rgColumnIDMasks. This argument duplicates the DBIDs provided in the prgColumnInfo argument but is provided for direct use with methods such as IRowSchemaChange::DeleteColumns that require an array of DBIDs. The provider allocates memory for the DBIDs. The consumer is responsible for releasing this memory with IMalloc::Free. If an error code is returned and prgColumnIDs is not a null pointer, ***prgColumnIDs should be set to NULL.

  • prgColumnInfo
    [out] A pointer to memory in which to return an array of DBCOLUMNINFO structures containing the requested column names. IColumnsInfo2::GetRestrictedColumnInfo returns either all columns or the columns selected by rgColumnIDMasks. The provider allocates memory for the DBCOLUMNINFO structures. The consumer is responsible for releasing this memory with IMalloc::Free. If an error code is returned and prgColumnInfo is not a null pointer, ***prgColumnInfo should be set to NULL.

  • ppStringsBuffer
    [out] A pointer to memory in which to return a pointer to storage for all string values (names used with either columnid or *pwszName of the DBCOLUMNINFO structure) within a single allocation block. If no columns are returned, ppStringsBuffer should be set to NULL. If there are any string names, ppStringsBuffer points to a buffer containing all the values of those names. The consumer is responsible for releasing this memory with IMalloc::Free. If an error code is returned and ppStringsBuffer is not a null pointer, ***ppStringsBuffer should be set to NULL.

Return Code

  • S_OK
    The requested columns were successfully enumerated.

  • DB_E_BADCOLUMNID
    An element of rgColumnIDMasks was an invalid DBID.

  • DB_E_DELETEDROW
    The row was deleted or moved.

  • DB_E_NOCOLUMN
    No columns matched the mask criteria. The provider sets ***pcColumns to zero and other output arguments to NULL.

  • DB_E_NOTREENTRANT
    The provider called a method from IRowsetNotify in the consumer that had not yet returned, and the provider does not support reentrancy in this method.

  • DB_SEC_E_PERMISSIONDENIED
    The consumer did not have sufficient permission to retrieve the column information.

  • E_INVALIDARG
    cColumnIDMasks was not zero, and rgColumnIDMasks was a null pointer.

    pcColumns was a null pointer.

    ppStringsBuffer was a null pointer.

    prgColumnIDs and prgColumnInfo are both null pointers.

  • E_FAIL
    A provider-specific error occurred.

  • E_OUTOFMEMORY
    The provider was unable to allocate sufficient memory in which to return the column information structures or string buffer.

  • E_UNEXPECTED
    ITransaction::Commit or ITransaction::Abort was called, and the object is in a zombie state.

Comments

If prgColumnIDs is a null pointer, the array of column names is not returned.

If prgColumnInfo is a null pointer, the array of DBCOLUMNINFO structures is not returned.

prgColumnIDs points to a filtered list of columns that can be used directly as input to methods such as IRowSchemaChange::DeleteColumns.

If a column ID mask element in rgColumnIDMasks is any GUID or PROPID kind of DBID, IColumnsInfo2::GetRestrictedColumnInfo matches all columns with that GUID and/or PROPID. For example, passing in a DBID of kind DBKIND_GUID, containing the GUID that denotes the resource rowset, will match all columns of the resource rowset (since they differ only by PROPID).

If the column ID mask element is a name kind of DBID, IColumnsInfo2::GetRestrictedColumnInfo matches any columns whose name (pwszName of the DBID) begins with the pwszName string in the column ID mask DBID. Names may be used to further qualify a GUID-based match.

For more information on the use of DBCOLUMNINFO and the string buffer, see IColumnsInfo::GetColumnInfo. For information about DBID structures, see Column IDs.

The order in which the columns in the row are enumerated is implementation-dependent. Each column is enumerated only once.

DBCOLUMNINFO Structure Elements for Row Objects

Providers must implement the following elements of the DBCOLUMNINFO structure for row objects:

  • pwszName
    Wide-character string containing the name of the column.

  • wType
    DBTYPE of the column.

  • columnid
    Row columns are identified using column IDs, which are DBID structures. DBIDs allow columns to be identified by GUID, name (URL), or PROPID (a ULONG). This allows providers to access and set columns by name, GUID, or number. For information about column IDs, see Column IDs.

    If ordinals are used to identify row columns, the following rules apply:

  • The ordinal zero is used to denote a bookmark column. It cannot be used to denote an ordinary column.

  • Ordinal values must remain constant throughout the life of a row object. This is true even if one or more row columns are deleted.

  • Rowset column ordinals start at 1 and are numbered sequentially in increasing order (for example, 1, 2, 3, and so on).

  • When a row object is derived from a rowset, the row-specific column ordinals must come after the rowset column ordinals.

    Rowset ordinals are faster to use than row column IDs. To retrieve column ordinals from column IDs, a consumer calls IColumnsInfo::MapColumnIDs.

    The columnid may specify the type of an object stored in a column when wType has one of the following values:

    • DBTYPE_IUNKNOWN

    • DBTYPE_ IDISPATCH

    • DBTYPE_VARIANT and vt = VT_UNKNOWN or VT_DISPATCH

    When identifying an object, within the columnid DBID, the eKind element should be set to DBKIND_GUID and the guid element should identify the object type.