Click here to Skip to main content
Click here to Skip to main content

Using the Windows RunFile dialog - The documented and undocumented way

, 8 Aug 2002 CPOL
Rate this:
Please Sign up or sign in to vote.
An article describing how to use system RunFile dialog both documented and undocumented way

RunFile Dialog

Introduction

In this article I am going to describe how to start the Run file dialog that you see when launching applications from the Start/Run menu. There are two ways of doing this - first documented, using the Shell object, and the second - using the undocumented Windows shell API function which is much more flexible.

Going the Documented Way

We should create an instance of the Shell object and call its FileRun method:

// Do not forget to add AfxOleInit() in the InitInstance() of the app !!!

BOOL CRunFileDlgDlg::RunDocumented( void )
{	
    IShellDispatch* pShellDisp = NULL;
    
    HRESULT hr =  ::CoCreateInstance( CLSID_Shell, NULL, 
        CLSCTX_SERVER, IID_IShellDispatch, (LPVOID*)&pShellDisp );

    if( hr == S_OK )
    {
        pShellDisp->FileRun();  
        pShellDisp->Release();
        pShellDisp = NULL;
    }
    
    return ( hr == S_OK );
}

We can just launch run file dialog and that is all - it starts stuck to the Start menu.

Going the Undocumented Way

Declaration

This way is much more flexible - it allows us to define the dialog icon, title and description. I will not jump in the deeps of the implementation; you can look it in the header and source files I have provided. The function is exported from the shell32.dll by ordinal 61 (dynamically loaded) and its declaration is as follows:

BOOL
FASTCALL
RunFileDlg( 
    IN HWND    hwndOwner,       // Owner window, receives notifications
    IN HICON   hIcon,           // Dialog icon handle, if NULL default icon is used
    IN LPCTSTR lpszDirectory,   // Working directory
    IN LPCTSTR lpszTitle,       // Dialog title, if NULL default is displayed
    IN LPCTSTR lpszDescription, // Dialog description, if NULL default is displayed
    IN UINT    uFlags           // Dialog flags (see below)
);

Parameters

You can specify one or more of the following values in the uFlags parameter:

RFF_NOBROWSE - Remove the browse button.
RFF_NODEFAULT - No default item selected.
RFF_CALCDIRECTORY - Calculate the working directory from the file name.
RFF_NOLABEL - Remove the edit box label.
RFF_NOSEPARATEMEM - Remove the Separate Memory Space check box, NT only.

Notification Handling

Other nice feature of this dialog is that it allows us to control which applications the user should run. When the user selects the OK button, it sends a notification message with the details of the program, that should be started, to the window, whose handle you passed in to this function. The notification is in the form of a WM_NOTIFY message with the wParam set to RFN_VALIDATE (-510) code and the lParam pointing to an NMRUNFILEDLG structure:

typedef struct tagNMRUNFILEDLG {
    NMHDR       hdr;           // NMHDR structure
    LPCWSTR     lpszFile;      // File that should be started
    LPCWSTR     lpszDirectory; // Working directory
    int         nShow;         // How an application is to be displayed when open
} NMRUNFILEDLG, *LPNMRUNFILEDLG, *PNMRUNFILEDLG;

RunFile Dialog Test A

Notification Handling Unicode Issue

As far as this is undocumented function, it has differenet signatures in Windows NT and Windows 9x - Windows NT uses UNICODE version and Windows 9x - ANSI version despite you call RunFileA or RunFileW functions. In the implementation the operating system version is checked and all nesessary conversions are done. But when handling notificaton message, you should check it once again, because under Windows NT you will receive NMRUNFILEDLGW and in Windows 9x - NMRUNFILEDLGA, no matter defined UNICODE or not. See the sample:

MFC Application Sample

// ...
// Add the notify handler:
// ON_NOTIFY( RFN_VALIDATE, 0, OnRunFileDlgOK )
// ...

void CSomeDlg::OnRunFileDlgOK( NMHDR* pNMHDR, LRESULT* pResult )
{
    LPNMRUNFILEDLG lpNMRFD = (LPNMRUNFILEDLG)pNMHDR;
    TCHAR szFile[ MAX_PATH ] = { 0 };
    
    #ifndef UNICODE // If NT we get a unicode string anyway.
        if( ::GetVersion() <  0x80000000 )	// NT4/2K/XP
             ::WideCharToMultiByte( CP_ACP, 0, (LPCWSTR)lpNMRFD->lpszFile, 
                                    -1, szFile, 2 * MAX_PATH, NULL, NULL );
    #else
        if( ::GetVersion() >  0x80000000 )	// 95/98/Me
             ::MultiByteToWideChar( CP_ACP, 0, (LPCSTR)lpNMRFD->lpszFile, 
                                   -1, szFile, 2 * MAX_PATH );
    #endif
    
    CString strMsg( _T("") );
    strMsg.Format( _T("Run the file %s ?"), szFile );
    
    int nRet = ::MessageBox( GetSafeHwnd(), strMsg, 
        _T("RunFile Dialog notification test"),
        MB_YESNOCANCEL | MB_ICONQUESTION | MB_DEFBUTTON2 );
	
    switch ( nRet )
    {
        case IDYES: *pResult = RF_OK;     break;
        case IDNO:  *pResult = RF_RETRY;  break;
        default:    *pResult = RF_CANCEL;
    }
}

Win32 Application Sample

//...
// In the WindowProc
//...
case WM_NOTIFY:
{
    LPNMHDR lpNMHDR = (LPNMHDR)lParam;
    if( lpNMHDR->code == RFN_VALIDATE )
    {
        LPNMRUNFILEDLG lpNMRFD = (LPNMRUNFILEDLG)lpNMHDR;
        // lpNMRFD->lpszFile ...
        return RF_OK;
    }
}
//...

Return Values

The return value determines whether the application will be run or not.

RunFile Dialog Test B

You can use the following return values:

RF_OK - Allow the application to run.
RF_CANCEL - Cancel the operation and close the dialog.
RF_RETRY - Cancel the operation, but leave the dialog open.

Compatibility

Windows 9x - Requires Windows 95/98/Me.
Windows NT - Requires Windows NT4.0/2000/XP.

Related Links

History

  • 08-Aug-2002 - Posted the article.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Armen Hakobyan
Software Developer (Senior) SafeNet Inc
United States United States
No Biography provided

Comments and Discussions

 
BugWrong explanation of WM_NOTIFY in your article PinmemberKerem Guemruekcue19-Dec-12 18:43 
GeneralMy vote of 5 PinmemberMember 803644618-Aug-11 5:44 
GeneralInitial position of the 'Run dialog', when going the undocumented way [modified] PinmemberAlexandru Matei9-Aug-06 3:21 
QuestionHow did you find out the parameters of RunFileDlg? [modified] PinmemberAlexandru Matei9-Aug-06 1:54 
GeneralRunFileDlg on VB 6.0 PinsussWillian.BR29-Apr-04 5:06 
GeneralAnsi vs. Unicode Pinmembersvn@windojitsu.com12-Oct-03 12:23 
I don't know for sure, but I'll bet this callback function's handling of Ansi vs. Unicode strings is based on the Unicode-ness of the HWND passed in.
 
(Think: the implementation of Shell32!Ordinal61 calls IsUnicodeWindow() on the supplied HWND callback argument.)
 
That's the way DDE handles window-to-window string marshalling, for example.
 
As you say, it's obviously it's not based on any client's compile-time settings: there's only one export (ordinal 61) after all -- no place to append an "A" or "W"!
 
When you build your client against Win9X, you were probably calling CreateWindowA(). And on NT, CreateWindowW(). And that's why you were seeing the strings come in, the way they do.
 
Try calling CreateWindowA(), explicitly, on NT, then look at how the strings come back.
 
-S
QuestionBut if I don't want to see the run dialog ? PinmemberZjxin10-Nov-02 17:03 
AnswerRe: But if I don't want to see the run dialog ? PinmemberArmen Hakobyan11-Nov-02 2:40 
AnswerRe: But if I don't want to see the run dialog ? PinmemberZjxin11-Nov-02 15:05 
GeneralRe: But if I don't want to see the run dialog ? PinmemberArmen Hakobyan12-Nov-02 7:24 
AnswerRe: But if I don't want to see the run dialog ? PinsussAnonymous7-Jan-04 5:12 
GeneralRe: But if I don't want to see the run dialog ? PinmemberArmen Hakobyan7-Jan-04 14:38 
QuestionClear RUN dialog? PinmemberFrank.NET10-Aug-02 5:47 
AnswerRe: Clear RUN dialog? PinmemberArmen Hakobyan10-Aug-02 10:55 
GeneralRe: Clear RUN dialog? PinsussAnonymous15-Aug-02 2:35 
AnswerRe: Clear RUN dialog? PinmemberArmen Hakobyan16-Aug-02 1:57 
GeneralRe: Clear RUN dialog? PinsussAnonymous11-Sep-02 4:08 
GeneralRe: Clear RUN dialog? PinmemberArmen Hakobyan28-Jul-04 7:38 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web04 | 2.8.1411028.1 | Last Updated 9 Aug 2002
Article Copyright 2002 by Armen Hakobyan
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid