description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CUtlProps Class |
CUtlProps Class |
11/04/2016 |
|
|
bb525178-765c-4e23-a110-c0fd70c05437 |
Implements properties for a variety of OLE DB property interfaces (for example, IDBProperties
, IDBProperties
, and IRowsetInfo
).
template < class T >
class ATL_NO_VTABLE CUtlProps : public CUtlPropsBase
T
The class that contains the BEGIN_PROPSET_MAP
.
Header: atldb.h
Name | Description |
---|---|
GetPropValue | Gets a property from a property set. |
IsValidValue | Used to validate a value before setting a property. |
OnInterfaceRequested | Handles requests for an optional interface when a consumer calls a method on an object creation interface. |
OnPropertyChanged | Called after setting a property to handle chained properties. |
SetPropValue | Sets a property in a property set. |
Most of this class is an implementation detail.
CUtlProps
contains two members for setting properties internally: GetPropValue and SetPropValue.
For more information on the macros used in a property set map, see BEGIN_PROPSET_MAP and END_PROPSET_MAP.
Gets a property from a property set.
OUT_OF_LINE HRESULT GetPropValue(const GUID* pguidPropSet,
DBPROPID dwPropId,
VARIANT* pvValue);
pguidPropSet
[in] The GUID for the PropSet.
dwPropId
[in] The property index.
pvValue
[out] A pointer to a variant that contains the new property value.
Failure
on failure and S_OK if successful.
Used to validate a value before setting a property.
virtual HRESULT CUtlPropsBase::IsValidValue(ULONG /* iCurSet */,
DBPROP* pDBProp);
iCurSet
The index into the property-set array; zero if there is only one property set.
pDBProp
The property ID and new value in a DBPROP structure.
A standard HRESULT. The default return value is S_OK.
If you have any validation routines you want to run on a value that you are about to use to set a property, you should override this function. For example, you could validate DBPROP_AUTH_PASSWORD against a password table to determine a valid value.
Handles requests for an optional interface when a consumer calls a method on one of the object creation interfaces.
virtual HRESULT CUtlPropsBase::OnInterfaceRequested(REFIID riid);
riid
[in] The IID for the requested interface. For more details, see the description of the riid parameter of ICommand::Execute
in the OLE DB Programmer's Reference (in the MDAC SDK).
OnInterfaceRequested
handles consumer requests for an optional interface when a consumer calls a method on one of the object creation interfaces (such as IDBCreateSession
, IDBCreateCommand
, IOpenRowset
, or ICommand
). It sets the corresponding OLE DB property for the requested interface. For example, if the consumer requests IID_IRowsetLocate
, OnInterfaceRequested
sets the DBPROP_IRowsetLocate
interface. Doing so maintains the correct state during rowset creation.
This method is called when the consumer calls IOpenRowset::OpenRowset
or ICommand::Execute
.
If a consumer opens an object and requests an optional interface, the provider should set the property associated with that interface to VARIANT_TRUE. To allow property-specific processing, OnInterfaceRequested
is called before the provider's Execute
method is called. By default, OnInterfaceRequested
handles the following interfaces:
-
IRowsetLocate
-
IRowsetChange
-
IRowsetUpdate
-
IConnectionPointContainer
-
IRowsetScroll
If you wish to handle other interfaces, override this function in your data source, session, command, or rowset class to process functions. Your override should go through the normal set/get properties interfaces to ensure that setting properties also sets any chained properties (see OnPropertyChanged).
Called after setting a property to handle chained properties.
virtual HRESULT OnPropertyChanged(ULONG /* iCurSet */,
DBPROP* pDBProp);
iCurSet
The index into the property-set array; zero if there is only one property set.
pDBProp
The property ID and new value in a DBPROP structure.
A standard HRESULT. The default return value is S_OK.
If you want to handle chained properties, such as bookmarks or updates whose values are dependent on another property's value, you should override this function.
In this function, the user gets the property ID from the DBPROP*
parameter. Now, it is possible to compare the ID against a property to chain. When the property is found, SetProperties
is called with the property that will now be set in conjunction with the other property. In this case, if one gets the DBPROP_IRowsetLocate
, DBPROP_LITERALBOOKMARKS
, or DBPROP_ORDEREDBOOKMARKS
property, one can set the DBPROP_BOOKMARKS
property.
[!code-cppNVC_OLEDB_Provider#2]
Sets a property in a property set.
HRESULT SetPropValue(const GUID* pguidPropSet,
DBPROPID dwPropId,
VARIANT* pvValue);
pguidPropSet
[in] The GUID for the PropSet.
dwPropId
[in] The property index.
pvValue
[in] A pointer to a variant that contains the new property value.
Failure
on failure and S_OK if successful.
OLE DB Provider Templates
OLE DB Provider Template Architecture