OLE DB Programmer's Reference

IDBPromptInitialize::PromptDataSource

Opens the Data Link Properties dialog box. Returns an uninitialized data source object with the specified properties set.

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.
Value Meaning
DBPROMPTOPTIONS_DISABLE_PROVIDER_SELECTION Do not prompt for provider selection. Valid only if *ppDataSource is a pointer to an existing data source object. Setting this flag without specifying a valid data source object in ppDataSource on input returns the error E_INVALIDARG.
DBPROMPTOPTIONS_DISABLESAVEPASSWORD Disables the "Allow Saving password" checkbox. When set, the value of the property DBPROP_AUTH_PERSIST_SENSITIVE_AUTHINFO is set to VARIANT_FALSE on the provider.
DBPROMPTOPTIONS_PROPERTYSHEET Prompt with Data Link Properties dialog box.
DBPROMPTOPTIONS_WIZARDSHEET Deprecated. Retained for backward compatibility only.
cSourceTypeFilter [in]
Number of DBSOURCETYPE values in rgSourceTypeFilter. If cSourceTypeFilter is zero, the value of rgSourceTypeFilter is ignored and the Provider selection tab will list standard tabular OLE DB providers.
rgSourceTypeFilter [in]
Types of providers to display in the Provider selection tab. Must point to a valid array of DBSOURCETYPE values. Valid source types include the values described in the following table.
Value Meaning
DBSOURCETYPE_DATASOURCE_TDP OLE DB tabular data provider
DBSOURCETYPE_DATASOURCE_MDP OLE DB multidimensional data provider
pwszszzProviderFilter [in]
A double null-terminated string of ProgIDs.

This parameter must be a null pointer or must 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, the dialog is created with the connection tab displayed. If more than one provider is specified, the provider selection tab is displayed first.

Providers specified in pwszszzProviderFilter that are not registered on the machine are ignored. If none of the providers are registered, an error is returned.

riid [in]
The requested interface for the data link returned in *ppDataSource.
ppDataSource [in, out]
A pointer to a data source object.

If *ppDataSource is null on entry, IDBPromptInitialize::PromptDataSource generates a new data source object based on the information specified by the user and returns a pointer to that data source object in *ppDataSource.

If *ppDataSource is non-null on entry, IDBPromptInitialize::PromptDataSource uses the properties returned by IProperties::GetProperties as initial values. If the user selects a different provider, PromptDataSource will release the original *ppDataSource and create a new data source object. On exit, *ppDataSource will be set to a pointer to the interface specified by riid. If the user selects the same provider but requests a different interface by supplying a different value for riid, the output value of *ppDataSource will be a pointer to the required interface on the existing data source object.

If *ppDataSource is non-null on entry and the call returns an error, *ppDataSource is untouched. The caller is strongly advised to check the return value when calling IDBPromptInitialize::PromptDataSource on an existing data source object.

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 object did not support the interface specified in riid.

riid was IID_NULL.

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.

pUnkOuter and *ppDataSource were both non-null.

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.

*ppDataSource was a null pointer, and DBPROMPTOPTIONS_DISABLE_PROVIDER_SELECTION was specified in dwPromptOptions.

*ppDataSource did not refer to a valid data source object.

DB_E_NOPROVIDERSREGISTERED
No OLE DB providers of the type specified in rgSourceTypeFilter and matching the filter, if any, specified in pwszszzProviderFilter were found on the machine.
E_UNEXPECTED
The data source object cannot return the requested interface because the data source object is not initialized.

Comments

Providers that do not support aggregation cannot be initialized via IDBPromptInitialize::PromptDataSource.

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<IUnknown **>(&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_PROPERTYSHEET,
      0, NULL,
      NULL,
      IID_IDBProperties,
      reinterpret_cast<IUnknown **>(&pIDBProperties));