IDBProperties::GetPropertyInfo

OLE DB Programmer's Reference

Returns information about all properties supported by the provider.

HRESULT GetPropertyInfo(    ULONG               cPropertyIDSets,    const DBPROPIDSET   rgPropertyIDSets[],    ULONG              *pcPropertyInfoSets,    DBPROPINFOSET     **prgPropertyInfoSets,    OLECHAR           **ppDescBuffer);

Parameters

cPropertyIDSets

[in]
The number of DBPROPIDSET structures in rgPropertyIDSets.

If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets. When called on the enumerator, the provider returns information about all properties in the Initialization property group. When called on the data source object, if the data source object is in an uninitialized state, the provider returns information about all properties in the Initialization property group. This should include any provider-specific properties belonging to this group. If the data source object is in an initialized state, the provider returns information about all of the properties in all of the property sets it supports.

If cPropertyIDSets is not zero, the provider returns information about the requested properties. If a property is not supported or if the method is called on an enumerator or an uninitialized data source object and the value of a property in a group other than the Initialization property group is requested, the returned value of dwStatus in the returned DBPROPINFO structure for that property is DBPROPFLAGS_NOTSUPPORTED and the values of the pwszDescription, vtType, and vValues elements are undefined. For information about the DBPROPINFO structure, see "DBPROPINFO Structure" in Chapter 14: Properties.

rgPropertyIDSets

[in]
An array of cPropertyIDSets DBPROPIDSET structures. When called on the enumerator, the properties specified in these structures must belong to the Initialization property group. When called on the data source object, if the data source object has not been initialized, the properties must belong to the Initialization property group. If the data source object has been initialized, the properties can belong to any property group. The provider returns information about the properties specified in these structures. If cPropertyIDSets is zero, this parameter is ignored. For information about the DBPROPIDSET structure, see "DBPROPIDSET Structure" in Chapter 14: Properties.

The following special GUIDs are defined for use with IDBProperties::GetPropertyInfo. All of these GUIDs can be used on data source objects; only the DBPROPSET_DBINITALL GUID can be used on enumerators. If any of these GUIDs are specified in the guidPropertySet element of a DBPROPIDSET structure, the cPropertyIDs and rgPropertyIDs elements of that structure are ignored. However, the consumer should set these to zero and a null pointer, respectively, because the provider might attempt to verify that they are valid values. Consumers cannot pass special GUIDs and the GUIDs of other property sets in the same call to IDBProperties::GetPropertyInfo. That is, if one element of rgPropertyIDSets contains a special GUID, all elements of rgPropertyIDSets must contain special GUIDs. These GUIDs are not returned in the guidPropertySet element of the DBPROPINFOSET structures returned in prgPropertyInfoSets. Instead, the GUID of the property set to which the property belongs is returned.

Property set GUID	Description
DBPROPSET_COLUMNALL	Returns all properties in the Column property group, including provider-specific properties.
DBPROPSET_CONSTRAINTALL	Returns all properties in the Constraint property group, including provider-specific properties.
DBPROPSET_DATASOURCEALL	Returns all properties in the Data Source property group, including provider-specific properties.
DBPROPSET_DATASOURCEINFOALL	Returns all properties in the Data Source Information property group, including provider-specific properties.
DBPROPSET_DBINITALL	Returns all properties in the Initialization property group, including provider-specific properties.
DBPROPSET_INDEXALL	Returns all properties in the Index property group, including provider-specific properties.
DBPROPSET_ROWSETALL	Returns all properties in the Rowset property group, including provider-specific properties.
DBPROPSET_SESSIONALL	Returns all properties in the Session property group, including provider-specific properties.
DBPROPSET_STREAMALL	Returns all properties of the Stream property group, including provider-specific properties.
DBPROPSET_TABLEALL	Returns all properties in the Table property group, including provider-specific properties.
DBPROPSET_TRUSTEEALL	Returns all properties in the Trustee property group, including provider-specific properties.
DBPROPSET_VIEWALL	Returns all properties in the View property group, including provider-specific properties.

pcPropertyInfoSets

[out]
A pointer to memory in which to return the number of DBPROPINFOSET structures returned in *prgPropertyInfoSets. If cPropertyIDSets is zero, *pcPropertyInfoSets is the total number of property sets for which the provider supports at least one property. If *pcPropertyInfoSets is not zero and one of the special GUIDs listed in rgPropertyIDSets was used, *pcPropertyInfoSets may differ from cPropertyIDSets. If an error other than DB_E_ERRORSOCCURRED occurs, *pcPropertyInfoSets is set to zero.

prgPropertyInfoSets

[out]
A pointer to memory in which to return an array of DBPROPINFOSET structures. If cPropertyIDSets is zero, one structure is returned for each property set that contains at least one property supported by the provider. If cPropertyIDSets is not zero, one structure is returned for each property set specified in rgPropertyIDSets.

If cPropertyIDSets is not zero, the DBPROPINFOSET structures in *prgPropertyInfoSets are returned in the same order as the DBPROPIDSET structures in rgPropertyIDSets; that is, for corresponding elements of each array, the guidPropertySet elements are the same. If cPropertyIDs, in an element of rgPropertyIDSets, is not zero, the DBPROPINFO structures in the corresponding element of *prgPropertyInfoSets are returned in the same order as the DBPROPID values in rgPropertyIDs; that is, for corresponding elements of each array, the property IDs are the same. The only exception to these rules is when one of the special GUIDs listed in rgPropertyIDSets was used. In this case, the order of the property information returned may differ from the order specified in rgPropertyIDSets.

The provider allocates memory for the structures and returns the address to this memory; the consumer releases this memory with IMalloc::Free when it no longer needs the structures. Before calling IMalloc::Free for *prgPropertyInfoSets, the consumer should call IMalloc::Free for the rgPropertyInfos element within each element of *prgPropertyInfoSets. The consumer must also call VariantClear for the vValue property of each DBPROP structure in order to prevent a memory leak in cases where the variant contains a reference type (such as a BSTR.) If *pcPropertyInfoSets is zero on output or if an error other than DB_E_ERRORSOCCURRED occurs, *prgPropertyInfoSets must be a null pointer on output.

For information about the DBPROPINFOSET and DBPROPINFO structures, see "DBPROPINFOSET Structure" and "DBPROPINFO Structure" in Chapter 14: Properties.

ppDescBuffer

[out]
A pointer to memory in which to return a pointer to storage for all string values returned in the pwszDescription element of the DBPROPINFO structure. The provider allocates this memory with IMalloc, and the consumer frees it with IMalloc::Free when it no longer needs the property descriptions. If ppDescBuffer is a null pointer on input, IDBProperties::GetPropertyInfo does not return the property descriptions. If *pcPropertyInfoSets is zero on output or if an error occurs, the provider does not allocate any memory and ensures that *ppDescBuffer is a null pointer on output. Each of the individual string values stored in this buffer is terminated by a null-termination character. Therefore, the buffer may contain one or more strings, each with its own null-termination character, and may contain embedded null-termination characters.

Note For method calls that return multiple strings within an allocated string buffer, consumers should not make assumptions about the relationship between the individual string pointers and the returned string buffer. Specifically, the consumer should always treat the returned string values as read-only memory and should not assume that the individual string values all occur within the string buffer. The only requirement on the provider is that freeing the string buffer releases any task memory allocated for that call. This applies to the ppDescBuffer returned by IDBProperties::GetPropertyInfo to hold the pwszDescription elements of the DBPROPINFO structure, as well as to the ppStringsBuffer returned by IColumnsInfo::GetColumnInfo to return string values contained within the DBCOLUMNINFO structure.

Return Code

S_OK

The method succeeded. In all DBPROPINFO structures returned by the method, dwFlags is set to a value other than DBPROPFLAGS_NOTSUPPORTED.

DB_S_ERRORSOCCURRED

Information was successfully returned for at least one property. However, one of the following errors occurred:

In an element of rgPropertyIDSets, a property specified in rgPropertyIDs was not supported by the provider; this includes the case in which the property set to which the property belongs is not supported by the provider. In the DBPROPINFO structures returned for the property, dwFlags is set to DBPROPFLAGS_NOTSUPPORTED.
In an element of rgPropertyIDSets, the property set specified in guidPropertySet was not supported by the provider. In the DBPROPINFOSET structure returned for the property set, cPropertyInfos is set to zero and rgPropertyInfos is set to a null pointer.
The method was called on the enumerator, and in an element of rgPropertyIDSets, a property belonged to a group other than the Initialization property group.
The method was called on an uninitialized data source object, and in an element of rgPropertyIDSets, a property belonged to a group other than the Initialization property group.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

pcPropertyInfoSets or prgPropertyInfoSets was a null pointer.

cPropertyIDSets was not equal to zero, and rgPropertyIDSets was a null pointer.

In an element of rgPropertyIDSets, cPropertyIDs was not zero and rgPropertyIDs was a null pointer.

In one element of rgPropertyIDSets, guidPropertySet specified one of the special GUIDs listed in the description of rgPropertyIDSets. In a different element of rgPropertyIDSets, guidPropertySet specified the GUID of a normal property set.

E_OUTOFMEMORY

The provider was unable to allocate sufficient memory in which to return the DBPROPINFOSET or DBPROPINFO structures or the property descriptions.

DB_E_ERRORSOCCURRED

Errors occurred while attempting to return information about all properties. No property information was returned. The provider allocates memory for *prgPropertyInfoSets, and the consumer checks dwFlags in the DBPROPINFO structures to determine why information about each property was not returned. The consumer frees this memory when it no longer needs the information. The method can fail to return information about properties for any of the reasons specified in DB_S_ERRORSOCCURRED.

Comments

IDBProperties::GetPropertyInfo returns information about supported properties, including the property set to which they belong, their ID, their data type, the object to which they apply, and whether they can be read or written. Properties in the Initialization and Data Source Creation property groups for which the consumer must supply a value before calling IDBInitialize::Initialize are marked with the DBPROPFLAGS_REQUIRED bit in the dwFlags element of the DBPROPINFO structure.

Whether a property is supported is different from its value. For example, if a provider supports IRowsetLocate, it supports the DBPROP_IRowsetLocate property. Whether a rowset actually exposes IRowsetLocate depends on whether the consumer sets the value of the corresponding property to VARIANT_TRUE or VARIANT_FALSE.

The rowset properties returned by IDBProperties::GetPropertyInfo indicate the set of properties that the provider knows about. The properties that may actually be supported for any particular rowset can be a subset of these properties. For example, a schema rowset might not be able to support all of the same properties as a rowset resulting from calling IOpenRowset::OpenRowset, or the properties that can be supported on a rowset generated from a command might vary depending on the command text. In general, consumers should not make assumptions based on the information returned by IDBProperties::GetPropertyInfo. When opening a rowset, consumers should specify DBPROPOPTIONS_REQUIRED for the minimum number of properties required to be able to consume the rowset and should set dwOptions for properties that provide the consumer additional functionality to DBPROPTIONS_OPTIONAL.

For OLE DB 2.5 providers that support direct URL binding, IDBProperties::GetPropertyInfo is implemented on binder objects via IDBBinderProperties:IDBProperties. The behavior of IDBProperties::GetPropertyInfo on a binder object depends on the type of binder object and the argument cPropertyIDSets.

When called on the root binder object, which supports no properties, IDBProperties::GetPropertyInfo behaves as follows:

If cPropertyIDSets is zero, the root binder returns S_OK; *pcPropertyInfoSets is set to zero and sets *prgPropertyInfoSets and *ppDescBuffer to null pointers on output.
If cPropertyIDSets is not zero, the root binder returns DB_E_ERRORSOCCURRED and sets each requested property to DBPROPFLAGS_NOTSUPPORTED.

When called on provider binder objects, IDBProperties::GetPropertyInfo behaves as follows:

If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets and returns information about all of the properties in all of the property sets it supports.
If cPropertyIDSets is not zero, the provider returns information about the requested properties. If a property is not supported, the returned value of dwStatus in the returned DBPROPINFO structure for that property is DBPROPFLAGS_NOTSUPPORTED and the values of the pwszDescription, vtType, and vValues elements are undefined.

See Also