Classe CDataSource

Artigo
10/12/2023

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

Sintaxe

class CDataSource

Requisitos

Cabeçalho: atldbcli.h

Membros

Métodos

Nome	Descrição
Fechar	Encerra a conexão.
GetInitializationString	Recupera a cadeia de caracteres de inicialização da fonte de dados que está aberta no momento.
GetProperties	Obtém os valores das propriedades atualmente definidas para a fonte de dados conectada.
GetProperty	Obtém o valor de uma única propriedade atualmente definida para a fonte de dados conectada.
Aberto	Cria uma conexão com um provedor (fonte de dados) usando um moniker `CLSID`, `ProgID` ou um `CEnumerator` fornecido pelo chamador.
OpenFromFileName	Abre uma fonte de dados de um arquivo especificado pelo nome do arquivo fornecido pelo usuário.
OpenFromInitializationString	Abre a fonte de dados especificada por uma cadeia de caracteres de inicialização.
OpenWithPromptFileName	Permite que o usuário selecione um arquivo do link de dados criado anteriormente para abrir a fonte de dados correspondente.
OpenWithServiceComponents	Abre um objeto de fonte de dados usando a caixa de diálogo Link de Dados.

Comentários

Uma ou mais sessões de banco de dados podem ser criadas para uma única conexão. Essas 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 CDataSource, consulte o exemplo de CatDB.

CDataSource::Close

Fecha a conexão liberando o ponteiro m_spInit.

Sintaxe

void Close() throw();

CDataSource::GetInitializationString

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

Sintaxe

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

Parâmetros

pInitializationString
[out] Um ponteiro para a cadeia de caracteres de inicialização.

bIncludePassword
[in] true se a cadeia de caracteres incluir uma senha; caso contrário false.

Valor de retorno

Um valor HRESULT padrão.

Comentários

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 conectado da fonte de dados.

Sintaxe

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

Parâmetros

Confira IDBProperties::GetProperties na Referência do programador OLE DB no SDK do Windows.

Valor de retorno

Um valor HRESULT padrão.

Comentários

Para obter uma única propriedade, use GetProperty.

CDataSource::GetProperty

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

Sintaxe

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

Parâmetros

guid
[in] Um GUID que identifica o conjunto de propriedades para o qual retornar a propriedade.

propid
[in] ID da propriedade a ser retornada.

pVariant
[out] Um ponteiro para a variante em que GetProperty retorna o valor da propriedade.

Valor de retorno

Um valor HRESULT padrão.

Comentários

Para obter várias propriedades, use GetProperties.

CDataSource::Open

Abre uma conexão com uma fonte de dados usando um moniker CLSID, ProgID ou CEnumerator ou solicita ao usuário por meio de uma caixa de diálogo do 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
[in] O CLSID do provedor de dados.

pPropSet
[in] Um ponteiro para uma matriz de estruturas DBPROPSET que contêm propriedades e valores a serem definidos. Confira Conjuntos de propriedades e grupos de propriedades na Referência do programador OLE DB no SDK do Windows.

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

pName
[in] O nome do banco de dados ao qual conectar.

pUserName
[in] O nome do usuário.

pPassword
[in] A senha do usuário.

nInitMode
[in] 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
[in] Um identificador do programa.

enumerator
[in] Um objeto CEnumerator usado para obter um moniker para abrir a conexão quando o chamador não especificar um CLSID.

hWnd
[in] Identificador da 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 Comentários para obter detalhes.

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

Valor de retorno

Um valor HRESULT padrão.

Comentários

A sobrecarga do método que usa o parâmetro hWnd abre um objeto da fonte de dados com os componentes de serviço no oledb32.dll. Essa DLL contém a implementação de recursos dos Componentes de Serviço, como Pool de Recursos, Inscrição Automática de Transações e assim por diante. Para obter mais informações, confira a referência de OLE DB no Guia do Programador OLE DB.

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

Exemplo

O código a seguir mostra como abrir uma fonte de dados 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 do arquivo fornecido pelo usuário.

Sintaxe

HRESULT OpenFromFileName(LPCOLESTR szFileName) throw();

Parâmetros

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

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

Valor de retorno

Um valor HRESULT padrão.

Comentários

Esse método abre um objeto da fonte de dados usando os componentes de serviço no oledb32.dll; essa DLL contém a implementação de recursos dos Componentes de Serviço, como Pool de Recursos, Inscrição Automática de Transações e assim por diante. Para obter mais informações, confira a referência de 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
[in] A cadeia de caracteres de inicialização.

fPromptForInfo
[in] Se esse argumento estiver definido como true, então OpenFromInitializationString definirá 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. O usuário será solicitado a fornecer uma senha (ou qualquer outra informação ausente) ao tentar se conectar ao banco de dados.

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

Valor de retorno

Um valor HRESULT padrão.

Comentários

CDataSource::OpenWithPromptFileName

Esse método faz solicitações ao usuário por meio de caixa de diálogo e, em seguida, abre uma fonte de dados usando o arquivo especificado por ele.

Sintaxe

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

Parâmetros

hWnd
[in] Identificador da janela que será o pai da caixa de diálogo.

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

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

Valor de retorno

Um valor HRESULT padrão.

Comentários

CDataSource::OpenWithServiceComponents

Abre um objeto da 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
[in] O CLSID de um provedor de dados.

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

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

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

Partilhar via

Classe CDataSource

Sintaxe

Requisitos

Membros

Métodos

Comentários

CDataSource::Close

Sintaxe

CDataSource::GetInitializationString

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDataSource::GetProperties

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDataSource::GetProperty

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDataSource::Open

Sintaxe

Parâmetros

Valor de retorno

Comentários

Exemplo

CDataSource::OpenFromFileName

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDataSource::OpenFromInitializationString

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDataSource::OpenWithPromptFileName

Sintaxe

Parâmetros

Valor de retorno

Comentários

CDataSource::OpenWithServiceComponents

Sintaxe

Parâmetros

Valor de retorno

Comentários

Confira também

Comentários

Recursos adicionais