Classe CDataSource
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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 Devolução
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.
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 Devolução
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::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.
Valor de Devolução
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.
Confira também
Modelos de consumidor OLE DB
Referência de modelos de consumidor do OLE DB
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de