IDBPromptInitialize::PromptDataSource

Opens the Data Link Properties dialog box. Returns a connection string.

HRESULT PromptDataSource(

   IUnknown *          pUnkOuter
   HWND                hWndParent,
   DBPROMPTOPTIONS     dwPromptOptions,
   ULONG               cSourceTypeFilter,
   DBSOURCETYPE *      rgSourceTypeFilter,
   LPCOLESTR           pwszszzProviderFilter,
   REFIID              riid,
   IUnknown **         ppDataSource);

Parameters

pUnkOuter [in]

A pointer to the controlling IUnknown interface if the data source object is being created as a part of an aggregate; otherwise, it is a null pointer.

hWndParent [in]

The parent window handle for dialog boxes to be displayed. The dialog box will always be centered within this window.

dwPromptOptions [in]

Specifies whether to prompt with the Create New Data Link wizard or the Data Link Properties dialog box.

cSourceTypeFilter [in]

Count of elements in rgSourceTypeFilter. The only valid value is zero.

This is reserved for future use.

rgSourceTypeFilter [in]

This parameter is ignored unless cSourceTypeFilter is greater than zero. Otherwise, this parameter points to a valid array of DBSOURCETYPE values. If it is non-null, the providers presented to the user will be limited to those that match the SOURCE_TYPEs specified in rgSourceTypeFilter.

This is reserved for future use.

pwszszzProviderFilter [in]

A double null-terminated string of ProgIDs.

This parameter must be null, or point to a valid string. If it is non-null, the providers presented to the user will be limited to those that match the providers' ProgIDs specified in pwszszzProviderFilter. If only one provider is specified, and DBPROMPTOPTIONS_WIZARDSHEET is specified, the provider selection page is not displayed.

riid [in]

The requested interface for the data link returned in *ppDataSource.

ppDatasource [in, out]

A pointer to a data source object (DSO).

If *ppDataSource is null on entry, then Prompt generates a new DSO based on the information specified by the user, and returns a pointer to that DSO in *ppDataSource.

If *ppDataSource is non-null on entry, Prompt uses the properties returned by IProperties::GetProperties() as initial values. If the user selects a different provider, Prompt will release the original *ppDataSource and create a new data source. On exit, *ppDataSource will be set to a pointer to the interface specified by riid.

Return Code

S_OK

The method succeeded.

E_FAIL

A provider-specific error occurred.

DB_E_CANCELED

The user canceled the dialog.

E_NOINTERFACE

The data source did not support the interface specified in riid.

riid was IID_NULL.

*ppDatasource was not null and did not indicate an OLE DB data source generated from IDataInitialize or IDBPromptInitialize.

DB_E_NOAGGREGATION

pUnkOuter was not a null pointer and riid was something other than IID_IUnknown.

pUnkOuter was not a null pointer and the provider does not support aggregation.

E_INVALIDARG

ppDatasource was a null pointer.

cSourceTypeFilter was not zero and rgSourceTypeFilter was a null pointer.

An element in rgSourceTypeFilter was not a valid filter.

dwPromptOptions was an invalid value.

Comments

None.

Code Example

The following code fragment shows how a consumer might use IDBPromptInitialize::PromptDataSource to prompt the user for connection information:

// First CoCreate the OLE DB Service Component Manager
//

HRESULT               hr                    =S_OK;
IDataInitialize      *pIDataInitialize      =NULL;

hr = CoCreateInstance(
         CLSID_DataLinks, 
         NULL, 
         CLSCTX_INPROC_SERVER, 
         IID_IDataInitialize, 
         reinterpret_cast<void **>(pIDataInitialize));


// CreateDBInstance to instantiate previously stored provider
//

CLSID               clsidProvider     (GetProviderCLSID());
IDBProperties       *pIDBProperties   =NULL;

hr = pIDataInitialize->CreateDBInstance(
          clsidProvider,
          NULL,
          CLSCTX_INPROC_SERVER,
          NULL,
          IID_IDBProperties,
          reinterpret_cast<void **>(&pIDBProperties));


// Set some previously stored properties
//

ULONG             cPropertySets           (GetPropertySetsCount());
DBPROPSET         (*rgPropertySets)        (GetPropertySets());

hr = pIDBProperties->SetProperties(cPropertySets, rgPropertySets);


// Prompt the user to view/edit the connection information
//

IDBPromptInitialize   *pIDBPromptInitialize   =NULL;

hr = pIDataInitialize ->QueryInterface(
         IID_IDBPromptInitialize, 
         reinterpret_cast<void **>(&pIDBPromptInitialize));

hr = pIDBPromptInitialize->PromptDataSource(
         NULL,
         hWndParent,
         DBPROMPTOPTIONS_WIZARD,
         0, NULL, 
         NULL,
         IID_IDBProperties,
         &pIDBProperties);