IDBDataSourceAdmin::GetCreationProperties

OLE DB Programmer's Reference

Returns information about the data store 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 cPropertyIDSets is zero, the provider ignores rgPropertyIDSets and returns information about all of the properties in the Data Source Creation property group it supports and about all of the properties in the Initialization property group it supports for use in creating data stores.

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 stores, 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 property group or belong to the Initialization property group and be supported for use in creating data stores. The provider returns information about the properties specified in these structures. If cPropertyIDSets is zero, this parameter is ignored.

For information about the properties in the Data Source Creation and Initialization property groups that are defined by OLE DB, see "Data Source Creation Property Group," "Initialization Property Group," and "Session Property Group" in Appendix C. For information about the DBPROPIDSET structure, see "DBPROPIDSET Structure" in Chapter 14: 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 in the Data Source Creation or Initialization property group. 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, one structure is returned for each property set that contains at least one property belonging to the Data Source Creation or Initialization property group. 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 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, *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, IDBDataSourceAdmin::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 or Initialization property group. 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 stores. 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

IDBDataSourceAdmin::GetCreationProperties returns properties in the Data Source Creation property group as well as properties in the Initialization property group that can be used in data store creation. It is possible that there are properties in the Initialization property group that cannot be used in data store creation. The properties for which values must be set to create a data store 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