Returns information about the data source creation properties supported by the data provider.
HRESULT GetCreationProperties (
ULONG cPropertyIDSets,
const DBPROPIDSET rgPropertyIDSets[],
ULONG * pcPropertyInfoSets,
DBPROPINFOSET ** prgPropertyInfoSets,
OLECHAR ** ppDescBuffer);
Parameters
cPropertyIDSets
[in]
The number of DBPROPIDSET structures in rgPropertyIDSets.
If cPropertySets is zero, the provider ignores rgPropertyIDSets and returns information about all of the properties in the Data Source Creation and Session property groups it supports and all of the properties in the Initialization property group it supports for use in creating data sources.
If cPropertyIDSets is not zero, the provider returns information about the requested properties. If a property is not supported, or if a property in the Initialization property group cannot be used to create data sources, 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.
rgPropertyIDSets
[in]
An array of cPropertyIDSets DBPROPIDSET structures. The properties specified in these structures must belong to the Data Source Creation or Session property group or belong to the Initialization property group and be supported for use in creating data sources. The provider returns information about the properties specified in these structures. If cPropertyIDSets is zero, then this parameter is ignored.
For information about the properties in the Data Source Creation, Initialization, and Session property groups that are defined by OLE DB, see "Data Source Creation Properties," "Initialization Properties," and "Session Properties" in Appendix C. For information about the DBPROPIDSET structure, see "DBPROPIDSET Structure" in Chapter 11.
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 in the Data Source Creation, Initialization, or Session property groups. If cPropertyIDSets is greater than zero, *pcPropertyInfoSets is set to cPropertyIDSets. If an error 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, then one structure is returned for each property set that contains at least one property belonging to the Data Source Creation, Initialization, or Session property group. If cPropertyIDSets is not zero, then 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 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 in each element of *prgPropertyInfoSets. If *pcPropertyInfoSets is zero on output or an error occurs, then *prgPropertyInfoSets must be a null pointer on output.
For information about the DBPROPINFOSET and DBPROPINFO structures, see "DBPROPINFOSET Structure" and "DBPROPINFO Structure" in Chapter 11.
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, GetCreationProperties does not return the property descriptions. If *pcPropertyInfoSets is zero on output or an error occurs, the provider does not allocate any memory and ensures that *ppDescBuffer is a null pointer on output.
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
One or more properties specified in rgPropertyIDSets were not supported by the provider. The dwFlags element of the DBPROPINFO structure for such properties is set to DBPROPFLAGS_NOTSUPPORTED.
One or more properties specified in rgPropertyIDSets were not in the Data Source Creation, Initialization, or Session property groups. The dwFlags element of the DBPROPINFO structure for such properties is set to DBPROPFLAGS_NOTSUPPORTED.
One or more properties specified in rgPropertyIDSets were in the Initialization property group but could not be used to create data sources. The dwFlags element of the DBPROPINFO structure for such properties is set to DBPROPFLAGS_NOTSUPPORTED.
One or more property sets specified in rgPropertyIDSets were not supported by the provider. The dwFlags element of the DBPROPINFO structure for all specified properties in these sets is set to DBPROPFLAGS_NOTSUPPORTED. 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
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.
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
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
GetCreationProperties returns properties in the Data Source Creation and Session property groups and properties in the Initialization property group that can be used in data source creation. It is possible that there are properties in the Initialization property group that cannot be used in data source creation. The properties for which values must be set to create a data source are indicated in the dwFlags element of the DBPROPINFO structure as DBPROPFLAGS_REQUIRED.
This method can be called before the data source object has been initialized.
See Also