CUtlProps Class
Implements properties for a variety of OLE DB property interfaces (for example, IDBProperties, IDBProperties, and IRowsetInfo).
Syntax
template < class T >
class ATL_NO_VTABLE CUtlProps : public CUtlPropsBase
Parameters
T
The class that contains the BEGIN_PROPSET_MAP.
Requirements
Header: atldb.h
Members
Methods
| 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. |
Remarks
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.
CUtlProps::GetPropValue
Gets a property from a property set.
Syntax
OUT_OF_LINE HRESULT GetPropValue(const GUID* pguidPropSet,
DBPROPID dwPropId,
VARIANT* pvValue);
Parameters
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.
Return Value
Failure on failure and S_OK if successful.
CUtlProps::IsValidValue
Used to validate a value before setting a property.
Syntax
virtual HRESULT CUtlPropsBase::IsValidValue(ULONG /* iCurSet */,
DBPROP* pDBProp);
Parameters
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.
Return Value
A standard HRESULT. The default return value is S_OK.
Remarks
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.
CUtlProps::OnInterfaceRequested
Handles requests for an optional interface when a consumer calls a method on one of the object creation interfaces.
Syntax
virtual HRESULT CUtlPropsBase::OnInterfaceRequested(REFIID riid);
Parameters
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).
Remarks
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:
IRowsetLocateIRowsetChangeIRowsetUpdateIConnectionPointContainerIRowsetScroll
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).
CUtlProps::OnPropertyChanged
Called after setting a property to handle chained properties.
Syntax
virtual HRESULT OnPropertyChanged(ULONG /* iCurSet */,
DBPROP* pDBProp);
Parameters
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.
Return Value
A standard HRESULT. The default return value is S_OK.
Remarks
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.
Example
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.
HRESULT OnPropertyChanged(ULONG /*iCurSet*/, DBPROP* pDBProp)
{
ATLASSERT(pDBProp != NULL);
DWORD dwPropertyID = pDBProp->dwPropertyID;
if (dwPropertyID == DBPROP_IRowsetLocate ||
dwPropertyID == DBPROP_LITERALBOOKMARKS ||
dwPropertyID == DBPROP_ORDEREDBOOKMARKS)
{
CComVariant var = pDBProp->vValue;
if (var.boolVal == VARIANT_TRUE)
{
// Set the bookmarks property as these are chained
CComVariant bookVar(true);
CDBPropSet set(DBPROPSET_ROWSET);
set.AddProperty(DBPROP_BOOKMARKS, bookVar);
return SetProperties(1, &set);
}
}
return S_OK;
}
CUtlProps::SetPropValue
Sets a property in a property set.
Syntax
HRESULT SetPropValue(const GUID* pguidPropSet,
DBPROPID dwPropId,
VARIANT* pvValue);
Parameters
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.
Return Value
Failure on failure and S_OK if successful.
See also
OLE DB Provider Templates
OLE DB Provider Template Architecture