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:

• 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).

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