IDBProperties::GetProperties

Returns the values of properties in the Data Source, Data Source Information, and Initialization property groups that are currently set on the data source object or the values of properties in the Initialization property group that are currently set on the enumerator.

HRESULT GetProperties (
   ULONG               cPropertyIDSets,
   const DBPROPIDSET   rgPropertyIDSets[],
   ULONG              *pcPropertySets,
   DBPROPSET         **prgPropertySets);

Parameters

cPropertyIDSets

[in]
The number of DBPROPIDSET structures in rgPropertyIDSets.

If cPropertyIDSets is zero, the provider ignores rgPropertyIDSets. If the data source object or enumerator is in an uninitialized state, the provider returns the values of all properties in the Initialization property group for which values have been set or defaults exist. This should include any provider-specific properties belonging to this group. If the data source object or enumerator is in an initialized state, the provider returns the values of all properties in the Data Source, Data Source Information, and Initialization property groups (for data source objects) or just in the Initialization property group (for enumerators), for which values have been set or defaults exist. The provider does not return the values of properties in any of these property groups for which values have not been set and no defaults exist.

If cPropertyIDSets is not zero, the provider returns the values of the requested properties. If a property is not supported or if the data source object or enumerator is not initialized 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 DBPROP structure for that property is DBPROPSTATUS_NOTSUPPORTED and the value of dwOptions is undefined.

rgPropertyIDSets

[in]
An array of cPropertyIDSets DBPROPIDSET structures. If the data source object or enumerator has not been initialized, the properties specified in these structures must belong to the Initialization property group. If the data source object or enumerator has been initialized, the properties specified in these structures must belong to the Data Source, Data Source Information, or Initialization property group, for data source objects, or to the Initialization property group, for enumerators. The provider returns the values of the properties specified in these structures. If cPropertyIDSets is zero, this argument is ignored.

For information about the properties in the Data Source, Data Source Information, and Initialization property groups that are defined by OLE DB, see "Data Source Property Group," "Data Source Information Property Group," and "Initialization Properties" in Appendix C. For information about the DBPROPIDSET structure, see "DBPROPIDSET Structure" in Chapter 14: Properties.

pcPropertySets

[out]
A pointer to memory in which to return the number of DBPROPSET structures returned in *prgPropertySets. If cPropertyIDSets is zero, *pcPropertySets is the total number of property sets for which the provider supports at least one property in the Data Source, Data Source Information, or Initialization property group, for data source objects, or in the Initialization property group, for enumerators. If cPropertyIDSets is greater than zero, *pcPropertySets is set to cPropertyIDSets. If an error other than DB_E_ERRORSOCCURRED occurs, *pcPropertySets is set to zero.

prgPropertySets

[out]
A pointer to memory in which to return an array of DBPROPSET structures. If cPropertyIDSets is zero, one structure is returned for each property set that contains at least one property belonging to the Initialization property group (if the data source object or enumerator is not initialized), the Data Source, Data Source Information, or Initialization property group (if the data source object is initialized), or to the Initialization property group (if the enumerator is initialized). If cPropertyIDSets is not zero, one structure is returned for each property set specified in rgPropertyIDSets.

In the case of properties in the Initialization property group and for a previously persisted data source object, those properties related to sensitive authentication information such as password will be returned in an encrypted form if DBPROP_AUTH_PERSIST_ENCRYPTED is VARIANT_TRUE.

If cPropertyIDSets is not zero, the DBPROPSET structures in *prgPropertySets 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 DBPROP structures in the corresponding element of *prgPropertySets 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 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 *prgPropertySets, the consumer should call IMalloc::Free for the rgProperties element within each element of *prgPropertySets. If *pcPropertySets is zero on output or an error other than DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgPropertySets is a null pointer on output.

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

Return Code

S_OK

The method succeeded. For property sets other than DBPROPSET_PROPERTIESINERROR, dwStatus is set to DBPROPSTATUS_OK in all DBPROP structures returned. If the requested property set is DBPROPSET_PROPERTIESINERROR, dwStatus reflects the individual error for each DBPROP structure returned from the method.

DB_S_ERRORSOCCURRED

No value was returned for one or more properties. The consumer checks dwStatus in the DBPROP structure to determine the properties for which values were not returned. IDBProperties::GetProperties can fail to return properties for a number of reasons, including the following:

• The property was not supported by the provider.
• The data source object or enumerator was not initialized, and the property was not in the Initialization property group.
• The method was called on the data source object, the data source object was initialized, and the property was not in the Data Source, Data Source Information, or Initialization property groups.
• The method was called on the enumerator, the enumerator was initialized, and the property was not in the Initialization property group.
• The property set was not supported by the provider. If cPropertyIDs in the DBPROPIDSET structure for the property set was zero, the provider cannot set dwStatus in the DBPROP structure because it does not know the IDs of any properties in the property set. Instead, it sets cProperties to zero in the DBPROPSET structure returned for the property set.

E_FAIL

A provider-specific error occurred.

E_INVALIDARG

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

pcPropertySets or prgPropertySets was a null pointer.

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

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

cPropertyIDSets was greater than 1, and in an element of rgPropertyIDSets, guidPropertySet was DBPROPSET_PROPERTIESINERROR.

E_OUTOFMEMORY

The provider was unable to allocate sufficient memory in which to return the DBPROPSET or DBPROP structures.

DB_E_ERRORSOCCURRED

Values were not returned for any properties. The provider allocates memory for *prgPropertySets, and the consumer checks dwStatus in the DBPROP structures to determine why properties were not returned. The consumer frees this memory when it no longer needs the information.

Comments

If IDBInitialize::Initialize, IBindResource::Bind, or ICreateRow::CreateRow returns DB_E_ERRORSOCCURRED or DB_S_ERRORSOCCURRED, the consumer can immediately call IDBProperties::GetProperties with the DBPROPSET_PROPERTIESINERROR property set to return all the properties that were in error. IDBProperties::GetProperties will return S_OK, *pcPropertySets will contain the number of property sets having properties in error, and *prgPropertySets will contain an array of DBPROPSET structures. For more information, see "Property Sets" in Appendix C: OLE DB Properties.

When called on the root binder object, which supports no properties, IDBProperties::GetProperties returns the values of properties that have been set on the root binder.

• If cPropertyIDSets is zero, the root binder returns the value of any properties that have been set by the consumer and returns S_OK, sets *pcPropertySets to 0, and sets *prgPropertySets to NULL.
• If cPropertyIDSets is not zero, the root binder returns the value of any requested properties. If a requested property has not been set, the root binder returns a status of DBPROPSTATUS_NOTSET.

See Also

IDBProperties::GetPropertyInfo | IDBProperties::SetProperties