CDataSource Classe

Corresponde a um objeto de fonte de dados OLE DB, que representa uma conexão por meio de um provedor a uma fonte de dados.

Sintaxe

class CDataSource

Requerimentos

Cabeçalho: atldbcli.h

Members

Methods

Observações

Uma ou mais sessões de banco de dados podem ser criadas para uma única conexão. Estas sessões são representadas por CSession. Você deve chamar CDataSource::Open para abrir a conexão antes de criar uma sessão com CSession::Open.

Para obter um exemplo de como usar CDataSourceo , consulte o exemplo CatDB .

CDataSource::Fechar

Fecha a conexão liberando o m_spInit ponteiro.

Sintaxe

void Close() throw();

CDataSource::GetInitializationString

Recupera a cadeia de caracteres de inicialização de uma fonte de dados que está aberta no momento.

Sintaxe

HRESULT GetInitializationString(BSTR* pInitializationString,
   bool bIncludePassword = false) throw();

Parâmetros

pInitializationString
[saídas] Um ponteiro para a cadeia de caracteres de inicialização.

bIncludePassword
[em] true se a string incluir uma senha; caso contrário false.

Valor de retorno

Um HRESULT padrão.

Observações

A cadeia de caracteres de inicialização resultante pode ser usada para reabrir posteriormente essa conexão de fonte de dados.

CDataSource::GetProperties

Retorna as informações de propriedade solicitadas para o objeto de fonte de dados conectado.

Sintaxe

HRESULT GetProperties(ULONG ulPropIDSets,
   constDBPROPIDSET* pPropIDSet,
   ULONG* pulPropertySets,
   DBPROPSET** ppPropsets) const throw();

Parâmetros

Consulte IDBProperties::GetProperties na referência do programador OLE DB no SDK do Windows.

Valor de retorno

Um HRESULT padrão.

Observações

Para obter uma única propriedade, use GetProperty.

CDataSource::GetProperty

Retorna o valor de uma propriedade especificada para o objeto de fonte de dados conectado.

Sintaxe

HRESULT GetProperty(const GUID& guid,
   DBPROPID propid,
   VARIANT* pVariant) const throw();

Parâmetros

GUID
[em] Um GUID que identifica o conjunto de propriedades para o qual a propriedade deve ser devolvida.

Propid
[em] ID da propriedade a ser retornada.

pVariante
[saídas] Um ponteiro para a variante onde GetProperty retorna o valor da propriedade.

Valor de retorno

Um HRESULT padrão.

Observações

Para obter várias propriedades, use GetProperties.

CDataSource::Aberto

Abre uma conexão com uma fonte de dados usando um CLSID, ProgIDou CEnumerator moniker ou solicita ao usuário uma caixa de diálogo localizador.

Sintaxe

HRESULT Open(const CLSID& clsid,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();

HRESULT Open(const CLSID& clsid,
   LPCTSTR pName,
   LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();HRESULT Open(LPCTSTR szProgID,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();HRESULT Open(LPCTSTR szProgID,
   LPCTSTR pName,  LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();

HRESULT Open(const CEnumerator& enumerator,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();

HRESULT Open(const CEnumerator& enumerator,
   LPCTSTR pName,
   LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();

HRESULT Open(HWND hWnd = GetActiveWindow(),
   DBPROMPTOPTIONS dwPromptOptions = DBPROMPTOPTIONS_WIZARDSHEET) throw();

HRESULT Open(LPCWSTR szProgID,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();

HRESULT Open(LPCSTR szProgID,
   LPCTSTR pName,LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();

Parâmetros

CLSID
[em] O CLSID do fornecedor de dados.

pPropSet
[em] Um ponteiro para uma matriz de estruturas DBPROPSET contendo propriedades e valores a serem definidos. Consulte Conjuntos de propriedades e grupos de propriedades na referência do programador OLE DB no SDK do Windows.

nPropertySets
[em] O número de estruturas DBPROPSET passadas no argumento pPropSet .

pNome
[em] O nome do banco de dados ao qual se conectar.

pUserName
[em] O nome do usuário.

pPalavra-passe
[em] A senha do usuário.

nInitMode
[em] Modo de inicialização do banco de dados. Consulte Propriedades de inicialização na referência do programador OLE DB no SDK do Windows para obter uma lista de modos de inicialização válidos. Se nInitMode for zero, nenhum modo de inicialização será incluído no conjunto de propriedades usado para abrir a conexão.

szProgID
[em] Um identificador de programa.

Recenseador
[em] Um objeto CEnumerator usado para obter um moniker para abrir a conexão quando o chamador não especifica um CLSIDarquivo .

hWnd
[em] Manipule a janela que será o pai da caixa de diálogo. Usar a sobrecarga de função que usa o parâmetro hWnd invocará automaticamente os Componentes de Serviço; consulte Observações para obter detalhes.

dwPromptOptions
[em] Determina o estilo da caixa de diálogo do localizador a ser exibida. Consulte Msdasc.h para valores possíveis.

Valor de retorno

Um HRESULT padrão.

Observações

A sobrecarga de método que usa o parâmetro hWnd abre um objeto de fonte de dados com os componentes de serviço em oledb32.dll; esta DLL contém a implementação de recursos de componentes de serviço, como pool de recursos, alistamento automático de transações e assim por diante. Para obter mais informações, consulte a referência OLE DB no Guia do programador OLE DB.

As sobrecargas de método que não usam o parâmetro hWnd abrem um objeto de fonte de dados sem usar os componentes de serviço em oledb32.dll. Um objeto CDataSource aberto com essas sobrecargas de função não poderá utilizar nenhuma das funcionalidades dos Componentes de Serviço.

Example

O código a seguir mostra como abrir uma fonte de dados do Jet 4.0 com modelos OLE DB. Você trata a fonte de dados Jet como uma fonte de dados OLE DB. No entanto, sua chamada para Open precisa de dois conjuntos de propriedades: um para DBPROPSET_DBINIT e outro para DBPROPSET_JETOLEDB_DBINIT, para que você possa definir DBPROP_JETOLEDB_DATABASEPASSWORD.

CDBPropSet rgDBPropSet[2];  // Declare two property sets;
                            // set properties elsewhere as appropriate.

hr = m_DataSource.Open(szProgId, rgDBPropSet, 2);

CDataSource::OpenFromFileName

Abre uma fonte de dados de um arquivo especificado pelo nome de arquivo fornecido pelo usuário.

Sintaxe

HRESULT OpenFromFileName(LPCOLESTR szFileName) throw();

Parâmetros

szFileName
[em] O nome de um arquivo, geralmente uma conexão de fonte de dados (. UDL).

Para obter mais informações sobre arquivos de link de dados (arquivos .udl), consulte Visão geral da API de link de dados no SDK do Windows.

Valor de retorno

Um HRESULT padrão.

Observações

Esse método abre um objeto de fonte de dados usando os componentes de serviço em oledb32.dll; esta DLL contém a implementação de recursos de componentes de serviço, como pool de recursos, alistamento automático de transações e assim por diante. Para obter mais informações, consulte a referência OLE DB no Guia do programador OLE DB.

CDataSource::OpenFromInitializationString

Abre uma fonte de dados especificada pela cadeia de caracteres de inicialização fornecida pelo usuário.

Sintaxe

HRESULT OpenFromInitializationString(LPCOLESTR szInitializationString,
   bool fPromptForInfo= false) throw();

Parâmetros

szInitializationString
[em] A cadeia de caracteres de inicialização.

fPromptForInfo
[em] Se esse argumento for definido como true, definirá OpenFromInitializationString a propriedade DBPROP_INIT_PROMPT como DBPROMPT_COMPLETEREQUIRED, o que especifica que o usuário será solicitado somente se mais informações forem necessárias. Isso é útil para situações em que a cadeia de caracteres de inicialização especifica um banco de dados que requer uma senha, mas a cadeia de caracteres não contém a senha. Será solicitada ao usuário uma senha (ou qualquer outra informação ausente) ao tentar se conectar ao banco de dados.

O valor padrão é false, que especifica que o usuário nunca será solicitado (define DBPROP_INIT_PROMPT como DBPROMPT_NOPROMPT).

Valor de retorno

Um HRESULT padrão.

Observações

Esse método abre um objeto de fonte de dados usando os componentes de serviço em oledb32.dll; esta DLL contém a implementação de recursos de componentes de serviço, como pool de recursos, alistamento automático de transações e assim por diante.

CDataSource::OpenWithPromptFileName

Esse método solicita ao usuário uma caixa de diálogo e, em seguida, abre uma fonte de dados usando o arquivo especificado pelo usuário.

Sintaxe

HRESULT OpenWithPromptFileName(HWND hWnd = GetActiveWindow(   ),
   DBPROMPTOPTIONS dwPromptOptions = DBPROMPTOPTIONS_NONE,
   LPCOLESTR szInitialDirectory = NULL) throw();

Parâmetros

hWnd
[em] Manipule a janela que será o pai da caixa de diálogo.

dwPromptOptions
[em] Determina o estilo da caixa de diálogo do localizador a ser exibida. Consulte Msdasc.h para valores possíveis.

szInitialDirectory
[em] O diretório inicial a ser exibido na caixa de diálogo do localizador.

Valor de retorno

Um HRESULT padrão.

Observações

Esse método abre um objeto de fonte de dados usando os componentes de serviço em oledb32.dll; esta DLL contém a implementação de recursos de componentes de serviço, como pool de recursos, alistamento automático de transações e assim por diante. Para obter mais informações, consulte a referência OLE DB no Guia do programador OLE DB.

CDataSource::OpenWithServiceComponents

Abre um objeto de fonte de dados usando os componentes de serviço no oledb32.dll.

Sintaxe

HRESULT OpenWithServiceComponents (const CLSID clsid,
   DBPROPSET* pPropset = NULL,
   ULONG ulPropSets = 1);

HRESULT OpenWithServiceComponents (LPCSTR szProgID,
   DBPROPSET* pPropset = NULL,
   ULONG ulPropSets = 1);

Parâmetros

CLSID
[em] O CLSID de um provedor de dados.

szProgID
[em] ID do programa de um provedor de dados.

pPropset
[em] Um ponteiro para uma matriz de estruturas DBPROPSET contendo propriedades e valores a serem definidos. Consulte Conjuntos de propriedades e grupos de propriedades na referência do programador OLE DB no SDK do Windows. Se o objeto de fonte de dados for inicializado, as propriedades deverão pertencer ao grupo de propriedades Fonte de Dados. Se a mesma propriedade for especificada mais de uma vez em pPropset, o valor usado será específico do provedor. Se ulPropSets for zero, esse parâmetro será ignorado.

ulPropSets
[em] O número de estruturas DBPROPSET passadas no argumento pPropSet . Se for zero, o provedor ignorará pPropset.

Valor de retorno

Um HRESULT padrão.

Observações

Esse método abre um objeto de fonte de dados usando os componentes de serviço em oledb32.dll; esta DLL contém a implementação de recursos de componentes de serviço, como pool de recursos, alistamento automático de transações e assim por diante. Para obter mais informações, consulte a referência OLE DB no Guia do programador OLE DB.

Consulte também

Modelos de consumidor OLE DB
Referência de modelos de consumidor OLE DB