CDataSource-Klasse

  • Artikel

Entspricht einem OLE DB-Datenquellenobjekt, das eine Verbindung über einen Anbieter zu einer Datenquelle darstellt.

Syntax

class CDataSource

Anforderungen

Header: atldbcli.h

Member

Methoden

Name Beschreibung
Abschließen Schließen der Verbindung.
GetInitializationString Ruft die Initialisierungszeichenfolge der zurzeit geöffneten Datenquelle ab.
GetProperties Ruft die Werte der Eigenschaften ab, die derzeit für die verbundene Datenquelle festgelegt sind.
GetProperty Ruft den Wert einer einzelnen Eigenschaft ab, die derzeit für die verbundene Datenquelle festgelegt ist.
Öffnen Erstellt eine Verbindung mit einem Anbieter (Datenquelle) mithilfe eines CLSIDvom ProgIDAufrufer bereitgestellten Monikers oder eines CEnumerator vom Aufrufer bereitgestellten Monikers.
OpenFromFileName Öffnet eine Datenquelle aus einer Datei, die durch den vom Benutzer bereitgestellten Dateinamen angegeben wird.
OpenFromInitializationString Öffnet die durch eine Initialisierungszeichenfolge angegebene Datenquelle.
OpenWithPromptFileName Ermöglicht dem Benutzer, eine zuvor erstellte Datenlinkdatei auszuwählen, um die entsprechende Datenquelle zu öffnen.
OpenWithServiceComponents Öffnet ein Datenquellenobjekt mithilfe des Dialogfelds "Datenverbindung".

Hinweise

Mindestens eine Datenbanksitzung kann für eine einzelne Verbindung erstellt werden. Diese Sitzungen werden durch CSession. Sie müssen CDataSource::Open aufrufen, um die Verbindung zu öffnen, bevor Sie eine Sitzung mit CSession::Open.

Ein Beispiel für die Verwendung CDataSourcefinden Sie im CatDB-Beispiel .

DataSource::Close

Schließt die Verbindung, indem der m_spInit Zeiger losgelassen wird.

Syntax

void Close() throw();

DataSource::GetInitializationString

Ruft die Initialisierungszeichenfolge einer aktuell geöffneten Datenquelle ab.

Syntax

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

Parameter

pInitializationString
[out] Ein Zeiger auf die Initialisierungszeichenfolge.

bIncludePassword
[in] true wenn eine Zeichenfolge ein Kennwort enthält; andernfalls false.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Die resultierende Initialisierungszeichenfolge kann verwendet werden, um diese Datenquellenverbindung später erneut zu öffnen.

CDataSource::GetProperties

Gibt die Eigenschafteninformationen zurück, die für das verbundene Datenquellenobjekt angefordert werden.

Syntax

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

Parameter

Siehe IDBProperties::GetProperties in der OLE DB-Programmierreferenz im Windows SDK.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Verwenden Sie GetProperty, um eine einzelne Eigenschaft abzurufen.

DataSource::GetProperty

Gibt den Wert einer angegebenen Eigenschaft für das verbundene Datenquellenobjekt zurück.

Syntax

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

Parameter

guid
[in] Eine GUID, die den Eigenschaftensatz angibt, für den die Eigenschaft zurückgegeben werden soll.

propid
[in] Eigenschafts-ID für die zurückzugebende Eigenschaft.

pVariant
[out] Ein Zeiger auf die Variante, in GetProperty der der Wert der Eigenschaft zurückgegeben wird.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Verwenden Sie GetProperties, um mehrere Eigenschaften abzurufen.

CDataSource::Open

Öffnet eine Verbindung mit einer Datenquelle mit einem CLSID, ProgIDoder moniker oder CEnumerator fordert den Benutzer mit einem Locator-Dialogfeld auf.

Syntax

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

Parameter

clsid
[in] Der CLSID Datenanbieter.

pPropSet
[in] Ein Zeiger auf ein Array von DBPROPSET-Strukturen , die Eigenschaften und Werte enthalten, die festgelegt werden sollen. Siehe Eigenschaftensätze und Eigenschaftengruppen in der OLE DB-Programmierreferenz im Windows SDK.

nPropertySets
[in] Die Anzahl der im pPropSet-Argument übergebenen DBPROPSET-Strukturen.

pName
[in] Der Name der Datenbank, zu der eine Verbindung hergestellt werden soll.

pUserName
[in] Der Name des Benutzers.

pPassword
[in] Das Benutzerkennwort.

nInitMode
[in] Initialisierungsmodus der Datenbank. Eine Liste der gültigen Initialisierungsmodi finden Sie unter "Initialisierungseigenschaften" in der OLE DB-Programmierreferenz im Windows SDK. Wenn nInitMode null ist, ist kein Initialisierungsmodus im Eigenschaftensatz enthalten, der zum Öffnen der Verbindung verwendet wird.

szProgID
[in] Ein Programmbezeichner.

enumerator
[in] Ein CEnumerator -Objekt, das verwendet wird, um einen Moniker zum Öffnen der Verbindung zu erhalten, wenn der Aufrufer keine .CLSID

hWnd
[in] Handle für das Fenster, das als das übergeordnete Element des Dialogfelds festgelegt werden soll. Die Verwendung der Funktionsüberladung, die den hWnd-Parameter verwendet, ruft automatisch Dienstkomponenten auf. Weitere Informationen finden Sie in den Hinweisen.

dwPromptOptions
[in] Bestimmt den Stil des anzuzeigenden Locatordialogfelds. Mögliche Werte sind in Msdasc.h aufgeführt.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Die Methodenüberladung, die den hWnd-Parameter verwendet, öffnet ein Datenquellenobjekt mit den Dienstkomponenten in oledb32.dll. Diese DLL enthält die Implementierung von Dienstkomponentenfeatures wie Ressourcenpooling, automatische Transaktionsauflistung usw. Weitere Informationen finden Sie in der OLE DB-Referenz im OLE DB-Programmierhandbuch.

Die Methodenüberladungen, die den hWnd-Parameter nicht verwenden, öffnen ein Datenquellenobjekt, ohne die Dienstkomponenten in oledb32.dll zu verwenden. Ein mit diesen Funktionsüberladungen geöffnetes CDataSource-Objekt kann keine der Funktionen von Dienstkomponenten verwenden.

Beispiel

Der folgende Code zeigt, wie eine Jet 4.0-Datenquelle mit OLE DB-Vorlagen geöffnet werden kann. Die Jet-Datenquelle wird OLE DB-Datenquelle behandelt. Ihr Aufruf benötigt Open jedoch zwei Eigenschaftensätze: eine für DBPROPSET_DBINIT und die andere für DBPROPSET_JETOLEDB_DBINIT, sodass Sie DBPROP_JETOLEDB_DATABASEPASSWORD festlegen können.

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

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

CDataSource::OpenFromFileName

Öffnet eine Datenquelle aus einer Datei, die durch den vom Benutzer bereitgestellten Dateinamen angegeben wird.

Syntax

HRESULT OpenFromFileName(LPCOLESTR szFileName) throw();

Parameter

szFileName
[in] Der Name einer Datei, in der Regel eine Datenquellenverbindungsdatei (UDL-Datei).

Weitere Informationen zu Datenlinkdateien (UDL-Dateien) finden Sie unter Data Link API Overview in the Windows SDK.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Diese Methode öffnet ein Datenquellenobjekt mit den Dienstkomponenten im oledb32.dll; Diese DLL enthält die Implementierung von Dienstkomponentenfeatures wie z. B. Ressourcenpooling, automatische Transaktionseintragung usw. Weitere Informationen finden Sie in der OLE DB-Referenz im OLE DB-Programmierhandbuch.

CDataSource::OpenFromInitializationString

Öffnet eine datenquelle, die durch die vom Benutzer bereitgestellte Initialisierungszeichenfolge angegeben wird.

Syntax

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

Parameter

szInitializationString
[in] Die Initialisierungszeichenfolge.

fPromptForInfo
[in] Wenn dieses Argument auf true festgelegt ist, wird die OpenFromInitializationString DBPROP_INIT_PROMPT Eigenschaft auf DBPROMPT_COMPLETEREQUIRED festgelegt, wodurch angegeben wird, dass der Benutzer nur dann aufgefordert wird, wenn weitere Informationen erforderlich sind. Dies ist nützlich für Situationen, in denen die Initialisierungszeichenfolge eine Datenbank angibt, die ein Kennwort erfordert, die Zeichenfolge jedoch nicht das Kennwort enthält. Der Benutzer wird beim Versuch, eine Verbindung mit der Datenbank herzustellen, zur Eingabe eines Kennworts (oder anderer fehlender Informationen) aufgefordert.

Der Standardwert ist false, der angibt, dass der Benutzer nie aufgefordert wird (legt DBPROP_INIT_PROMPT auf DBPROMPT_NOPROMPT fest).

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Diese Methode öffnet ein Datenquellenobjekt mit den Dienstkomponenten im oledb32.dll; Diese DLL enthält die Implementierung von Dienstkomponentenfeatures wie z. B. Ressourcenpooling, automatische Transaktionseintragung usw.

CDataSource::OpenWithPromptFileName

Mit dieser Methode wird dem Benutzer ein Dialogfeld angezeigt und anschließend eine Datenquelle mithilfe der vom Benutzer angegebenen Datei geöffnet.

Syntax

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

Parameter

hWnd
[in] Handle für das Fenster, das als das übergeordnete Element des Dialogfelds festgelegt werden soll.

dwPromptOptions
[in] Bestimmt den Stil des anzuzeigenden Locatordialogfelds. Mögliche Werte sind in Msdasc.h aufgeführt.

szInitialDirectory
[in] Das im Locatordialogfeld anzuzeigende Ausgangsverzeichnis.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Diese Methode öffnet ein Datenquellenobjekt mit den Dienstkomponenten im oledb32.dll; Diese DLL enthält die Implementierung von Dienstkomponentenfeatures wie z. B. Ressourcenpooling, automatische Transaktionseintragung usw. Weitere Informationen finden Sie in der OLE DB-Referenz im OLE DB-Programmierhandbuch.

CDataSource::OpenWithServiceComponents

Öffnet ein Datenquellenobjekt mithilfe der Dienstkomponenten in „oledb32.dll“.

Syntax

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

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

Parameter

clsid
[in] Der CLSID Datenanbieter.

szProgID
[in] Programm-ID eines Datenanbieters.

pPropset
[in] Ein Zeiger auf ein Array von DBPROPSET-Strukturen , die Eigenschaften und Werte enthalten, die festgelegt werden sollen. Siehe Eigenschaftensätze und Eigenschaftengruppen in der OLE DB-Programmierreferenz im Windows SDK. Wenn das Datenquellenobjekt initialisiert wird, müssen die Eigenschaften zur Eigenschaftsquelle „Datenquelle“ gehören. Wenn dieselbe Eigenschaft mehrmals in pPropset angegeben wird, ist der verwendete Wert anbieterspezifisch. Wenn ulPropSets null ist, wird dieser Parameter ignoriert.

ulPropSets
[in] Die Anzahl der im pPropSet-Argument übergebenen DBPROPSET-Strukturen. Wenn dies null ist, ignoriert der Anbieter pPropset.

Rückgabewert

Ein Standard-HRESULT.

Hinweise

Diese Methode öffnet ein Datenquellenobjekt mit den Dienstkomponenten im oledb32.dll; Diese DLL enthält die Implementierung von Dienstkomponentenfeatures wie z. B. Ressourcenpooling, automatische Transaktionseintragung usw. Weitere Informationen finden Sie in der OLE DB-Referenz im OLE DB-Programmierhandbuch.

Siehe auch

OLE DB-Consumervorlagen
Referenz der OLE DB-Consumervorlagen