Classe CUtlProps

Implementa propriedades para uma variedade de interfaces de propriedade OLE DB (por exemplo, IDBProperties, IDBProperties e IRowsetInfo).

Sintaxe

template < class T >
class ATL_NO_VTABLE CUtlProps : public CUtlPropsBase

Parâmetros

T
A classe que contém o BEGIN_PROPSET_MAP.

Requisitos

Cabeçalho: atldb.h

Membros

Métodos

Nome	Descrição
GetPropValue	Obtém uma propriedade de um conjunto de propriedades.
IsValidValue	Usado para validar um valor antes de definir uma propriedade.
OnInterfaceRequested	Manipula solicitações de uma interface opcional quando um consumidor chama um método em uma interface de criação de objeto.
OnPropertyChanged	Chamado após definir uma propriedade para lidar com propriedades encadeadas.
SetPropValue	Define uma propriedade em um conjunto de propriedades.

Comentários

A maior parte dessa classe é um detalhe de implementação.

CUtlProps contém dois membros para definir propriedades internamente: GetPropValue e SetPropValue.

Para obter mais informações sobre as macros usadas em um mapa de conjunto de propriedades, confira BEGIN_PROPSET_MAP e END_PROPSET_MAP.

CUtlProps::GetPropValue

Obtém uma propriedade de um conjunto de propriedades.

Sintaxe

OUT_OF_LINE HRESULT GetPropValue(const GUID* pguidPropSet,
   DBPROPID dwPropId,
   VARIANT* pvValue);

Parâmetros

pguidPropSet
[entrada] O GUID para o PropSet.

dwPropId
[entrada] O índice de propriedades.

pvValue
[saída] Um ponteiro para uma variante que contém o novo valor da propriedade.

Valor de retorno

Failure em caso de falha e S_OK se bem-sucedido.

CUtlProps::IsValidValue

Usado para validar um valor antes de definir uma propriedade.

Sintaxe

virtual HRESULT CUtlPropsBase::IsValidValue(ULONG /* iCurSet */,
   DBPROP* pDBProp);

Parâmetros

iCurSet
O índice na matriz do conjunto de propriedades; zero se houver apenas um conjunto de propriedades.

pDBProp
A ID da propriedade e o novo valor em uma estrutura DBPROP.

Valor de retorno

Um valor HRESULT padrão. O valor retornado padrão é S_OK.

Comentários

Se você tiver alguma rotina de validação que deseja executar em um valor que está prestes a usar para definir uma propriedade, deverá substituir essa função. Por exemplo, você pode validar DBPROP_AUTH_PASSWORD em uma tabela de senha para determinar um valor válido.

CUtlProps::OnInterfaceRequested

Manipula solicitações de uma interface opcional quando um consumidor chama um método em uma das interfaces de criação de objeto.

Sintaxe

virtual HRESULT CUtlPropsBase::OnInterfaceRequested(REFIID riid);

Parâmetros

riid
[entrada] A IID para a interface solicitada. Para obter mais detalhes, confira a descrição do parâmetro riid de ICommand::Execute na Referência do Programador OLE DB (no SDK do MDAC).

Comentários

OnInterfaceRequested manipula solicitações de consumidor de uma interface opcional quando um consumidor chama um método em uma das interfaces de criação de objeto (como IDBCreateSession, IDBCreateCommand, IOpenRowset ou ICommand). Ele define a propriedade OLE DB correspondente para a interface solicitada. Por exemplo, se o consumidor solicitar IID_IRowsetLocate, OnInterfaceRequested definirá a interface DBPROP_IRowsetLocate. Isso mantém o estado correto durante a criação do conjunto de linhas.

Esse método é chamado quando o consumidor chama IOpenRowset::OpenRowset ou ICommand::Execute.

Se um consumidor abrir um objeto e solicitar uma interface opcional, o provedor deverá definir a propriedade associada a essa interface como VARIANT_TRUE. Para permitir o processamento específico da propriedade, OnInterfaceRequested é chamado antes da chamada ao método Execute do provedor. Por padrão, OnInterfaceRequested manipula as seguintes interfaces:

• IRowsetLocate

• IRowsetChange

• IRowsetUpdate

• IConnectionPointContainer

• IRowsetScroll

Se você quiser manipular outras interfaces, substitua essa função em sua classe de fonte de dados, sessão, comando ou conjunto de linhas para processar funções. Sua substituição deve passar pelas interfaces de propriedades get/set normais para garantir que a definição de propriedades também defina eventuais propriedades encadeadas (confira OnPropertyChanged).

CUtlProps::OnPropertyChanged

Chamado após definir uma propriedade para lidar com propriedades encadeadas.

Sintaxe

virtual HRESULT OnPropertyChanged(ULONG /* iCurSet */,
   DBPROP* pDBProp);

Parâmetros

iCurSet
O índice na matriz do conjunto de propriedades; zero se houver apenas um conjunto de propriedades.

pDBProp
A ID da propriedade e o novo valor em uma estrutura DBPROP.

Valor de retorno

Um valor HRESULT padrão. O valor retornado padrão é S_OK.

Comentários

Se você quiser lidar com propriedades encadeadas, como indicadores ou atualizações cujos valores dependem do valor de outra propriedade, você deve substituir essa função.

Exemplo

Nessa função, o usuário obtém a ID da propriedade do parâmetro DBPROP*. Agora, é possível comparar a ID com uma propriedade a ser encadeada. Quando a propriedade é encontrada, SetProperties é chamado com a propriedade que agora será definida em conjunto com a outra propriedade. Nesse caso, se alguém obtém a propriedade DBPROP_IRowsetLocate, DBPROP_LITERALBOOKMARKS ou DBPROP_ORDEREDBOOKMARKS, essa pessoa pode definir a propriedade DBPROP_BOOKMARKS.

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

Define uma propriedade em um conjunto de propriedades.

Sintaxe

HRESULT SetPropValue(const GUID* pguidPropSet,
   DBPROPID dwPropId,
   VARIANT* pvValue);

Parâmetros

pguidPropSet
[entrada] O GUID para o PropSet.

dwPropId
[entrada] O índice de propriedades.

pvValue
[entrada] Um ponteiro para uma variante que contém o novo valor da propriedade.

Valor de retorno

Failure em caso de falha e S_OK se bem-sucedido.

Confira também

Modelos de Provedor OLE DB
Arquitetura de modelo do provedor do OLE DB