IDBPromptInitialize::PromptFileName

OLE DB Programmer's Reference

Opens the Select Data Link dialog box. Allows the user to browse and organize .udl files. Returns a fully qualified path to the user-selected .udl file.

HRESULT PromptFileName(    HWND                 hWndParent,    DBPROMPTOPTIONS      dwPromptOptions,    LPCOLESTR            pwszInitialDirectory,    LPCOLESTR            pwszInitialFile,    LPCOLESTR *          ppwszSelectedFile);

Parameters

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 the dialog box options.

Value	Meaning
DBPROMPTOPTIONS_BROWSEONLY	Prevents the user from creating new data link files.

pwszInitialDirectory [in]

A pointer to a string containing the initial directory for the dialog box. If NULL, the default path "<Program Files\Common Files>\System\OLE DB\Data Links" is used. The exact value for <Program Files\Common Files> is system dependent. It can be determined from the "CommonFilesDir" registry entry, at "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion".

pwszInitialFile [in]

A pointer to a string containing the initial file for the file name edit box of the dialog box. Wildcard characters ("*", "?") may be used to form a filtering expression.

ppwszSelectedFile [out]

*ppwszSelectedFile points to a string containing the full path to the file the user selected. ppwszSelectedFile cannot be null.

Return Code

S_OK

The method succeeded.

E_FAIL

A provider-specific error occurred.

DB_E_CANCELED

The user canceled the dialog.

E_INVALIDARG

ppwszSelectedFile was a null pointer.

dwPromptOptions was an invalid value.

STG_E_FILENOTFOUND

pwszInitialFile could not be located. The file name may be too long or contain invalid characters.

Comments

To load a data source object from a .udl file after calling PromptFileName, the consumer must call IDataInitialize::LoadStringFromStorage to obtain the connection string from the file and then call IDataInitialize::GetDatasource to obtain the data source object based on the connection string.

If the initial directory cannot be accessed, an error message is displayed to the user. If the user chooses to continue, an accessible initial directory will be chosen automatically.

Code Example

The following code fragment shows how a consumer might use IDBPromptInitialize::PromptFileName to prompt the user for a data link (.udl) file:

   WCHAR *     pwszSelectedFile      = NULL;    hr = pIDBPromptInitialize->PromptFileName(          hWndParent,          DBPROMPTOPTIONS_BROWSEONLY,          L"C:\\Public",          L"*.udl",          &pwszSelectedFile);

1998-2001 Microsoft Corporation. All rights reserved.