Returns information about all properties supported by the provider.
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.
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.