CDataSource, classe

Correspond à un objet de source de données OLE DB, qui représente une connexion via un fournisseur à une source de données.

Syntaxe

class CDataSource

Spécifications

En-tête : atldbcli.h

Membres

Méthodes

Notes

Une ou plusieurs sessions de base de données peuvent être créées pour une connexion unique. Ces sessions sont représentées par CSession. Vous devez appeler CDataSource ::Open pour ouvrir la connexion avant de créer une session avec CSession::Open.

Pour obtenir un exemple d’utilisation CDataSource, consultez l’exemple CatDB .

CDataSource::Close

Ferme la connexion en libérant le m_spInit pointeur.

Syntaxe

void Close() throw();

CDataSource::GetInitializationString

Récupère la chaîne d’initialisation d’une source de données actuellement ouverte.

Syntaxe

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

Paramètres

pInitializationString
[out] Pointeur vers la chaîne d’initialisation.

bIncludePassword
[in] true si la chaîne inclut un mot de passe ; sinon false.

Valeur de retour

HRESULT standard.

Notes

La chaîne d’initialisation résultante peut être utilisée pour rouvrir ultérieurement cette connexion de source de données.

CDataSource::GetProperties

Retourne les informations de propriété demandées pour l’objet source de données connecté.

Syntaxe

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

Paramètres

Consultez IDBProperties ::GetProperties dans la référence du programmeur OLE DB dans le Kit de développement logiciel (SDK) Windows.

Valeur de retour

HRESULT standard.

Notes

Pour obtenir une propriété unique, utilisez GetProperty.

CDataSource::GetProperty

Retourne la valeur d’une propriété spécifiée pour l’objet source de données connecté.

Syntaxe

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

Paramètres

guid
[in] GUID identifiant le jeu de propriétés pour lequel retourner la propriété.

propid
[in] ID de propriété de la propriété à retourner.

pVariant
[out] Pointeur vers la variante où GetProperty retourne la valeur de la propriété.

Valeur de retour

HRESULT standard.

Notes

Pour obtenir plusieurs propriétés, utilisez GetProperties.

CDataSource::Open

Ouvre une connexion à une source de données à l’aide d’un moniker ProgIDou CEnumerator d’un CLSIDmoniker ou invite l’utilisateur à utiliser une boîte de dialogue localisateur.

Syntaxe

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();

Paramètres

clsid
[in] Fournisseur CLSID de données.

pPropSet
[in] Pointeur vers un tableau de structures DBPROPSET contenant des propriétés et des valeurs à définir. Consultez Les ensembles de propriétés et les groupes de propriétés dans la référence du programmeur OLE DB dans le Kit de développement logiciel (SDK) Windows.

nPropertySets
[in] Nombre de structures DBPROPSET passées dans l’argument pPropSet .

pName
[in] Nom de la base de données à laquelle se connecter.

pUserName
[in] Nom de l'utilisateur.

pPassword
[in] Mot de passe de l'utilisateur.

nInitMode
[in] Mode d'initialisation de la base de données. Consultez les propriétésd’initialisation dans la référence du programmeur OLE DB dans le Kit de développement logiciel (SDK) Windows pour obtenir la liste des modes d’initialisation valides. Si nInitMode est égal à zéro, aucun mode d’initialisation n’est inclus dans le jeu de propriétés utilisé pour ouvrir la connexion.

szProgID
[in] Identificateur de programme.

enumerator
[in] Objet CEnumerator utilisé pour obtenir un moniker pour ouvrir la connexion lorsque l’appelant ne spécifie pas un CLSID.

hWnd
[in] Handle de fenêtre devant être le parent de la boîte de dialogue. L’utilisation de la surcharge de fonction qui utilise le paramètre hWnd appelle automatiquement les composants de service . Pour plus d’informations, consultez les remarques.

dwPromptOptions
[in] Détermine le style de la boîte de dialogue de recherche à afficher. Consultez Msdasc.h pour connaître les valeurs possibles.

Valeur de retour

HRESULT standard.

Notes

La surcharge de méthode qui utilise le paramètre hWnd ouvre un objet de source de données avec les composants de service dans oledb32.dll ; cette DLL contient l’implémentation des fonctionnalités de composants de service telles que le regroupement de ressources, l’inscription automatique des transactions, etc. Pour plus d’informations, consultez la référence OLE DB dans le Guide du programmeur OLE DB.

Les surcharges de méthode qui n’utilisent pas le paramètre hWnd ouvrent un objet source de données sans utiliser les composants de service dans oledb32.dll. Un objet CDataSource ouvert avec ces surcharges de fonction ne pourra pas utiliser l’une des fonctionnalités des composants de service.

Exemple

Le code suivant montre comment ouvrir une source de données Jet 4.0 avec les modèles OLE DB. Même si vous traitez la source de données Jet comme une source de données OLE DB, Toutefois, votre appel a besoin de Open deux jeux de propriétés : un pour DBPROPSET_DBINIT et l’autre pour DBPROPSET_JETOLEDB_DBINIT, afin que vous puissiez définir DBPROP_JETOLEDB_DATABASEPASSWORD.

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

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

CDataSource::OpenFromFileName

Ouvre une source de données à partir d'un fichier spécifié par le nom de fichier fourni par l'utilisateur.

Syntaxe

HRESULT OpenFromFileName(LPCOLESTR szFileName) throw();

Paramètres

szFileName
[in] Nom d'un fichier, généralement un fichier de connexion de source de données au format .UDL.

Pour plus d’informations sur les fichiers de liaison de données (fichiers .udl), consultez Vue d’ensemble de l’API Data Link dans le Kit de développement logiciel (SDK) Windows.

Valeur de retour

HRESULT standard.

Notes

Cette méthode ouvre un objet source de données à l'aide des composants de service d'oledb32.dll ; cette DLL contient l'implémentation des fonctionnalités Composants de service, telles que la mise en pool de ressources, l'inscription de transaction automatique, etc. Pour plus d’informations, consultez la référence OLE DB dans le Guide du programmeur OLE DB.

CDataSource::OpenFromInitializationString

Ouvre une source de données spécifiée par la chaîne d’initialisation fournie par l’utilisateur.

Syntaxe

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

Paramètres

szInitializationString
[in] Chaîne d’initialisation.

fPromptForInfo
[in] Si cet argument est défini truesur , OpenFromInitializationString la propriété DBPROP_INIT_PROMPT est DBPROMPT_COMPLETEREQUIRED, qui spécifie que l’utilisateur est invité uniquement si des informations supplémentaires sont nécessaires. Cela est utile pour les situations dans lesquelles la chaîne d’initialisation spécifie une base de données qui requiert un mot de passe, mais la chaîne ne contient pas le mot de passe. L’utilisateur est invité à entrer un mot de passe (ou toute autre information manquante) lors de la tentative de connexion à la base de données.

La valeur par défaut est false, qui spécifie que l’utilisateur n’est jamais invité (définit DBPROP_INIT_PROMPT sur DBPROMPT_NOPROMPT).

Valeur de retour

HRESULT standard.

Notes

Cette méthode ouvre un objet source de données à l'aide des composants de service d'oledb32.dll ; cette DLL contient l'implémentation des fonctionnalités Composants de service, telles que la mise en pool de ressources, l'inscription de transaction automatique, etc.

CDataSource::OpenWithPromptFileName

Cette méthode présente une invite à l'utilisateur sous la forme d'une boîte de dialogue, puis ouvre une source de données correspondant au fichier spécifié par l'utilisateur.

Syntaxe

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

Paramètres

hWnd
[in] Handle de fenêtre devant être le parent de la boîte de dialogue.

dwPromptOptions
[in] Détermine le style de la boîte de dialogue de recherche à afficher. Consultez Msdasc.h pour connaître les valeurs possibles.

szInitialDirectory
[in] Répertoire initial à afficher dans la boîte de dialogue de recherche.

Valeur de retour

HRESULT standard.

Notes

Cette méthode ouvre un objet source de données à l'aide des composants de service d'oledb32.dll ; cette DLL contient l'implémentation des fonctionnalités Composants de service, telles que la mise en pool de ressources, l'inscription de transaction automatique, etc. Pour plus d’informations, consultez la référence OLE DB dans le Guide du programmeur OLE DB.

CDataSource::OpenWithServiceComponents

Ouvre un objet source de données à l'aide des composants de service d'oledb32.dll.

Syntaxe

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

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

Paramètres

clsid
[in] Fournisseur CLSID de données.

szProgID
[in] ID de programme d'un fournisseur de données.

pPropset
[in] Pointeur vers un tableau de structures DBPROPSET contenant des propriétés et des valeurs à définir. Consultez Les ensembles de propriétés et les groupes de propriétés dans la référence du programmeur OLE DB dans le Kit de développement logiciel (SDK) Windows. Si l'objet source de données est initialisé, les propriétés doivent appartenir au groupe de propriétés Source de données. Si la même propriété est spécifiée plusieurs fois dans pPropset, la valeur utilisée est spécifique au fournisseur. Si ulPropSets est égal à zéro, ce paramètre est ignoré.

ulPropSets
[in] Nombre de structures DBPROPSET passées dans l’argument pPropSet . S’il s’agit de zéro, le fournisseur ignore pPropset.

Valeur de retour

HRESULT standard.

Notes

Cette méthode ouvre un objet source de données à l'aide des composants de service d'oledb32.dll ; cette DLL contient l'implémentation des fonctionnalités Composants de service, telles que la mise en pool de ressources, l'inscription de transaction automatique, etc. Pour plus d’informations, consultez la référence OLE DB dans le Guide du programmeur OLE DB.

Voir aussi

Modèles du consommateur OLE DB
Référence des modèles du consommateur OLE DB