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 has not been initialized, the provider returns the values of all properties in the Initialization property group for which values have been set or defaults exist. If the data source object or enumerator has been initialized, the provider returns the values of all properties in the Data Source, Data Source Information, and Initialization property groups, for data source objects, or 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 the Initialization property group, for enumerators. The provider returns the values of the properties specified in these structures. If cPropertyIDSets is zero, then 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 Properties," "Data Source Information Properties," and "Initialization Properties" in Appendix C. For information about the DBPROPIDSET structure, see "DBPROPIDSET Structure" in Chapter 11.

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 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, then 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 the Initialization property group (if the enumerator is initialized). If cPropertyIDSets is not zero, then 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 11.

Return Code

S_OK
The method succeeded. In all DBPROP structures returned by the method, dwStatus is set to DBPROPSTATUS_OK.

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. GetProperties can fail to return properties for a number of reasons, including:

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 returns DB_E_ERRORSOCCURRED, the consumer can immediately call GetProperties with the DBPROPSET_PROPERTIESINERROR property set to return all the properties that were in error. For more information, see "Property Sets" in Chapter 11.