CDataSource (Clase)

Artículo
04/03/2023

Corresponde a un objeto de origen de datos OLE DB, que representa una conexión a través de un proveedor a un origen de datos.

Sintaxis

class CDataSource

Requisitos

Encabezado: atldbcli.h

Miembros

Métodos

Nombre	Descripción
Cerrar	Cierra la conexión.
GetInitializationString	Recupera la cadena de inicialización del origen de datos que está abierto actualmente.
GetProperties	Obtiene los valores de las propiedades establecidas actualmente para el origen de datos conectado.
GetProperty	Obtiene el valor de una sola propiedad establecida actualmente para el origen de datos conectado.
Abierto	Crea una conexión con un proveedor (origen de datos) utilizando un moniker `CLSID`, `ProgID` o `CEnumerator` proporcionado por el autor de la llamada.
OpenFromFileName	Abre un origen de datos desde un archivo especificado por el nombre de archivo proporcionado por el usuario.
OpenFromInitializationString	Abre el origen de datos especificado por una cadena de inicialización.
OpenWithPromptFileName	Permite al usuario seleccionar un archivo de vínculo de datos creado anteriormente para abrir el origen de datos correspondiente.
OpenWithServiceComponents	Abre un objeto de origen de datos mediante el cuadro de diálogo Vínculo de datos.

Comentarios

Se pueden crear una o varias sesiones de base de datos para una sola conexión. Estas sesiones se representan mediante CSession. Debe llamar a CDataSource::Open para abrir la conexión antes de crear una sesión con CSession::Open.

Para obtener un ejemplo de cómo usar CDataSource, consulte el ejemplo de CatDB.

CDataSource::Close

Cierra la conexión liberando el puntero m_spInit.

Sintaxis

void Close() throw();

CDataSource::GetInitializationString

Recupera la cadena de inicialización de un origen de datos que está abierto actualmente.

Sintaxis

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

Parámetros

pInitializationString
[out] Puntero a la cadena de inicialización.

bIncludePassword
[in] true si la cadena incluye una contraseña; de lo contrario, false.

Valor devuelto

Un HRESULT estándar.

Comentarios

La cadena de inicialización resultante se puede usar para volver a abrir más adelante esta conexión de origen de datos.

CDataSource::GetProperties

Devuelve la información de propiedad solicitada para el objeto de origen de datos conectado.

Sintaxis

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

Parámetros

Consulte IDBProperties::GetProperties en la Referencia del programador de OLE DB en Windows SDK.

Valor devuelto

Un HRESULT estándar.

Comentarios

Para obtener una sola propiedad, use GetProperty.

CDataSource::GetProperty

Devuelve el valor de una propiedad especificada para el objeto de origen de datos conectado.

Sintaxis

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

Parámetros

guid
[in] GUID que identifica el conjunto de propiedades para el que se va a devolver la propiedad.

propid
[in] Identificador de propiedad de la propiedad que se va a devolver.

pVariant
[out] Puntero a la variante donde GetProperty devuelve el valor de la propiedad.

Valor devuelto

Un HRESULT estándar.

Comentarios

Para obtener varias propiedades, use GetProperties.

CDataSource::Open

Abre una conexión a un origen de datos con un moniker CLSID, ProgID o CEnumerator, o bien presenta al usuario un cuadro de diálogo del localizador.

Sintaxis

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] CLSID del proveedor de datos.

pPropSet
[in] Puntero a una matriz de estructuras DBPROPSET que contiene las propiedades y los valores que se van a establecer. Vea Conjuntos de propiedades y grupos de propiedades en la referencia del programador OLE DB de Windows SDK.

nPropertySets
[in] Número de estructuras DBPROPSET pasadas en el argumento pPropSet.

pName
[in] El nombre de la base de datos con la que se va a conectar.

pUserName
[in] El nombre de usuario.

pPassword
[in] La contraseña del usuario.

nInitMode
[in] El modo de inicialización de la base de datos. Vea Propiedades de inicialización en la Referencia del programador de OLE DB en Windows SDK para obtener una lista de modos de inicialización válidos. Si nInitMode es cero, no se incluye ningún modo de inicialización en el conjunto de propiedades que se usa para abrir la conexión.

szProgID
[in] Un identificador de programa.

enumerator
[in] Un objeto CEnumerator usado para obtener un moniker para abrir la conexión cuando el elemento que llama no especifica ningún CLSID.

hWnd
[in] Identificador de la ventana que va a ser el elemento primario del cuadro de diálogo. Usar la sobrecarga de función que utiliza el parámetro hWnd invocará automáticamente a los componentes de servicio. Vea la sección Comentarios para obtener más información.

dwPromptOptions
[in] Determina el estilo del cuadro de diálogo de localizador que se va a mostrar. Consulte los valores posibles en Msdasc.h.

Valor devuelto

Un HRESULT estándar.

Comentarios

La sobrecarga del método que usa el parámetro hWnd abre un objeto de origen de datos con los componentes del servicio en oledb32.dll; este archivo DLL contiene la implementación de características de componentes de servicio como la agrupación de recursos y la inscripción automática de transacciones, entre otras. Para obtener más información, vea la referencia de OLE DB en la guía del programador de OLE DB.

Las sobrecargas del método que no usan el parámetro hWnd abren un objeto de origen de datos sin utilizar los componentes del servicio en oledb32.dll. Un objeto CDataSource abierto con estas sobrecargas de función no podrá usar ninguna de las funciones de los componentes del servicio.

Ejemplo

En el código siguiente se muestra cómo abrir un origen de datos de Jet 4.0 con plantillas OLE DB. Trate el origen de datos de Jet como origen de datos OLE DB. Sin embargo, la llamada a Open necesita dos conjuntos de propiedades: uno para DBPROPSET_DBINIT y otro para DBPROPSET_JETOLEDB_DBINIT, de modo que pueda establecer 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 un origen de datos desde un archivo especificado por el nombre de archivo proporcionado por el usuario.

Sintaxis

HRESULT OpenFromFileName(LPCOLESTR szFileName) throw();

Parámetros

szFileName
[in] El nombre de un archivo, normalmente una conexión de origen de datos. Archivo (.UDL).

Para obtener más información acerca de los archivos de vínculo de datos (archivos .udl), vea Información general sobre la API de vínculos de datos en Windows SDK.

Valor devuelto

Un HRESULT estándar.

Comentarios

Este método abre un objeto de origen de datos con los componentes del servicio en oledb32.dll; este archivo DLL contiene la implementación de características de componentes de servicio, como la agrupación de recursos y la inscripción automática de transacciones, entre otras. Para obtener más información, vea la referencia de OLE DB en la guía del programador de OLE DB.

CDataSource::OpenFromInitializationString

Abre un origen de datos especificado por la cadena de inicialización proporcionada por el usuario.

Sintaxis

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

Parámetros

szInitializationString
[in] Cadena de inicialización.

fPromptForInfo
[in] Si este argumento se establece en true, OpenFromInitializationString establecerá la propiedad DBPROP_INIT_PROMPT en DBPROMPT_COMPLETEREQUIRED, que especifica que solo se pedirá más información al usuario en caso de que sea necesario. Esto es útil para situaciones en las que la cadena de inicialización especifica una base de datos que requiere una contraseña, pero la cadena no contiene la contraseña. Se pedirá al usuario una contraseña (o cualquier otra información que falte) al intentar conectarse a la base de datos.

El valor predeterminado es false, que especifica que nunca se le pedirá al usuario (establece DBPROP_INIT_PROMPT en DBPROMPT_NOPROMPT).

Valor devuelto

Un HRESULT estándar.

Comentarios

CDataSource::OpenWithPromptFileName

Este método muestra al usuario un cuadro de diálogo y después abre un origen de datos mediante el archivo especificado por el usuario.

Sintaxis

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

Parámetros

hWnd
[in] Identificador de la ventana que va a ser el elemento primario del cuadro de diálogo.

dwPromptOptions
[in] Determina el estilo del cuadro de diálogo de localizador que se va a mostrar. Consulte los valores posibles en Msdasc.h.

szInitialDirectory
[in] El directorio inicial para mostrar en el cuadro de diálogo del localizador.

Valor devuelto

Un HRESULT estándar.

Comentarios

CDataSource::OpenWithServiceComponents

Abre un objeto de origen de datos usando los componentes del servicio en oledb32.dll.

Sintaxis

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] CLSID de un proveedor de datos.

szProgID
[in] Identificador de programa del proveedor de datos.

pPropset
[in] Puntero a una matriz de estructuras DBPROPSET que contiene las propiedades y los valores que se van a establecer. Vea Conjuntos de propiedades y grupos de propiedades en la referencia del programador OLE DB de Windows SDK. Si el objeto de origen de datos se inicializa, las propiedades tienen que pertenecer al grupo de propiedades Data Source. Si la misma propiedad se especifica más de una vez en pPropset, el valor que se use será específico del proveedor. Si ulPropSets es cero, este parámetro no se tiene en cuenta.

ulPropSets
[in] Número de estructuras DBPROPSET pasadas en el argumento pPropSet. Si es cero, el proveedor omite pPropset.

Compartir a través de

CDataSource (Clase)

Sintaxis

Requisitos

Miembros

Métodos

Comentarios

CDataSource::Close

Sintaxis

CDataSource::GetInitializationString

Sintaxis

Parámetros

Valor devuelto

Comentarios

CDataSource::GetProperties

Sintaxis

Parámetros

Valor devuelto

Comentarios

CDataSource::GetProperty

Sintaxis

Parámetros

Valor devuelto

Comentarios

CDataSource::Open

Sintaxis

Parámetros

Valor devuelto

Comentarios

Ejemplo

CDataSource::OpenFromFileName

Sintaxis

Parámetros

Valor devuelto

Comentarios

CDataSource::OpenFromInitializationString

Sintaxis

Parámetros

Valor devuelto

Comentarios

CDataSource::OpenWithPromptFileName

Sintaxis

Parámetros

Valor devuelto

Comentarios

CDataSource::OpenWithServiceComponents

Sintaxis

Parámetros

Valor devuelto

Comentarios

Consulte también

Comentarios

Recursos adicionales