CCommandLineInfo Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CCommandLineInfo Class.

Aids in parsing the command line at application startup.

class CCommandLineInfo : public CObject  

Public Constructors

NameDescription
CCommandLineInfo::CCommandLineInfoConstructs a default CCommandLineInfo object.

Public Methods

NameDescription
CCommandLineInfo::ParseParamOverride this callback to parse individual parameters.

Public Data Members

NameDescription
CCommandLineInfo::m_bRunAutomatedIndicates the command-line /Automation option was found.
CCommandLineInfo::m_bRunEmbeddedIndicates the command-line /Embedding option was found.
CCommandLineInfo::m_bShowSplashIndicates if a splash screen should be shown.
CCommandLineInfo::m_nShellCommandIndicates the shell command to be processed.
CCommandLineInfo::m_strDriverNameIndicates the driver name if the shell command is Print To; otherwise empty.
CCommandLineInfo::m_strFileNameIndicates the file name to be opened or printed; empty if the shell command is New or DDE.
CCommandLineInfo::m_strPortNameIndicates the port name if the shell command is Print To; otherwise empty.
CCommandLineInfo::m_strPrinterNameIndicates the printer name if the shell command is Print To; otherwise empty.
CCommandLineInfo::m_strRestartIdentifierIndicates the unique restart identifier for the restart manager if the restart manager restarted the application.

An MFC application will typically create a local instance of this class in the InitInstance function of its application object. This object is then passed to CWinApp::ParseCommandLine, which repeatedly calls ParseParam to fill the CCommandLineInfo object. The CCommandLineInfo object is then passed to CWinApp::ProcessShellCommand to handle the command-line arguments and flags.

You can use this object to encapsulate the following command-line options and parameters:

Command-line argumentCommand executed
appNew file.
app filenameOpen file.
app /p filenamePrint file to default printer.
app /pt filename printer driver portPrint file to the specified printer.
app /ddeStart up and await DDE command.
app /AutomationStart up as an OLE automation server.
app /EmbeddingStart up to edit an embedded OLE item.
app /Register

 app /Regserver
Informs the application to perform any registration tasks.
app /Unregister

 app /Unregserver
Informs the application to perform any un-registration tasks.

Derive a new class from CCommandLineInfo to handle other flags and parameter values. Override ParseParam to handle the new flags.

CObject

CCommandLineInfo

Header: afxwin.h

This constructor creates a CCommandLineInfo object with default values.

CCommandLineInfo();

Remarks

The default is to show the splash screen ( m_bShowSplash=TRUE) and to execute the New command on the File menu ( m_nShellCommand=NewFile).

The application framework calls ParseParam to fill data members of this object.

Example

   CCommandLineInfo cmdInfo;
   ParseCommandLine(cmdInfo);

Indicates that the /Automation flag was found on the command line.

BOOL m_bRunAutomated;  

Remarks

If TRUE, this means start up as an OLE automation server.

Indicates that the /Embedding flag was found on the command line.

BOOL m_bRunEmbedded;  

Remarks

If TRUE, this means start up for editing an embedded OLE item.

Indicates that the splash screen should be displayed.

BOOL m_bShowSplash;  

Remarks

If TRUE, this means the splash screen for this application should be displayed during startup. The default implementation of ParseParam sets this data member to TRUE if m_nShellCommand is equal to CCommandLineInfo::FileNew.

Indicates the shell command for this instance of the application.

m_nShellCommand;  

Remarks

The type for this data member is the following enumerated type, which is defined in the CCommandLineInfo class.

enum{

FileNew,

FileOpen,

FilePrint,

FilePrintTo,

FileDDE,

AppRegister,

AppUnregister,

RestartByRestartManager,

FileNothing = -1

};

For a brief description of these values, see the following list.

  • CCommandLineInfo::FileNew Indicates that no file name was found on the command line.

  • CCommandLineInfo::FileOpen Indicates that a file name was found on the command line and that none of the following flags were found on the command line: /p, /pt, /dde.

  • CCommandLineInfo::FilePrint Indicates that the /p flag was found on the command line.

  • CCommandLineInfo::FilePrintTo Indicates that the /pt flag was found on the command line.

  • CCommandLineInfo::FileDDE Indicates that the /dde flag was found on the command line.

  • CCommandLineInfo::AppRegister Indicates that the /Register or /Regserver flag was found on the command line and the application was asked to register.

  • CCommandLineInfo::AppUnregister Indicates that the /Unregister or /Unregserver application was asked to unregister.

  • CCommandLineInfo::RestartByRestartManager Indicates that the application was restarted by the restart manager.

  • CCommandLineInfo::FileNothing Turns off the display of a new MDI child window on startup. By design, Application Wizard-generated MDI applications display a new child window on startup. To turn off this feature, an application can use CCommandLineInfo::FileNothing as the shell command when it calls ProcessShellCommand. ProcessShellCommand is called by the InitInstance( ) of all CWinApp derived classes.

Example

   // From CMyWinApp::InitInstance

   // Parse command line for standard shell commands, DDE, file open
   CCommandLineInfo cmdInfo;
   ParseCommandLine(cmdInfo);

   // DON'T display a new MDI child window during startup!!!
   cmdInfo.m_nShellCommand = CCommandLineInfo::FileNothing;

   // Dispatch commands specified on the command line
   if (!ProcessShellCommand(cmdInfo))
      return FALSE;

Stores the value of the third non-flag parameter on the command line.

CString m_strDriverName;  

Remarks

This parameter is typically the name of the printer driver for a Print To shell command. The default implementation of ParseParam sets this data member only if the /pt flag was found on the command line.

Stores the value of the first non-flag parameter on the command line.

CString m_strFileName;  

Remarks

This parameter is typically the name of the file to open.

Stores the value of the fourth non-flag parameter on the command line.

CString m_strPortName;  

Remarks

This parameter is typically the name of the printer port for a Print To shell command. The default implementation of ParseParam sets this data member only if the /pt flag was found on the command line.

Stores the value of the second non-flag parameter on the command line.

CString m_strPrinterName;  

Remarks

This parameter is typically the name of the printer for a Print To shell command. The default implementation of ParseParam sets this data member only if the /pt flag was found on the command line.

The unique restart identifier on the command line.

CString m_strRestartIdentifier;  

Remarks

The restart identifier is unique for each instance of the application.

If the restart manager exits the application and is configured to restart it, the restart manager executes the application from the command line with the restart identifier as an optional parameter. When the restart manager uses the restart identifier, the application can reopen the previously open documents and recover autosaved files.

The framework calls this function to parse/interpret individual parameters from the command line. The second version differs from the first only in Unicode projects.

virtual void ParseParam(
    const char* pszParam,  
    BOOL bFlag,  
    BOOL bLast);

 
virtual void ParseParam(
    const TCHAR* pszParam,  
    BOOL bFlag,  
    BOOL bLast);

Parameters

pszParam
The parameter or flag.

bFlag
Indicates whether pszParam is a parameter or a flag.

bLast
Indicates if this is the last parameter or flag on the command line.

Remarks

CWinApp::ParseCommandLine calls ParseParam once for each parameter or flag on the command line, passing the argument to pszParam. If the first character of the parameter is a ' -' or a ' /', then it is removed and bFlag is set to TRUE. When parsing the final parameter, bLast is set to TRUE.

The default implementation of this function recognizes the following flags: /p, /pt, /dde, /Automation, and /Embedding, as shown in the following table:

Command-line argumentCommand executed
appNew file.
app filenameOpen file.
app /p filenamePrint file to default printer.
app /pt filename printer driver portPrint file to the specified printer.
app /ddeStart up and await DDE command.
app /AutomationStart up as an OLE automation server.
app /EmbeddingStart up to edit an embedded OLE item.
app /Register

 app /Regserver
Informs the application to perform any registration tasks.
app /Unregister

 app /Unregserver
Informs the application to perform any un-registration tasks.

This information is stored in m_bRunAutomated, m_bRunEmbedded, and m_nShellCommand. Flags are marked by either a forward-slash ' /' or hyphen ' -'.

The default implementation puts the first non-flag parameter into m_strFileName. In the case of the /pt flag, the default implementation puts the second, third, and fourth non-flag parameters into m_strPrinterName, m_strDriverName, and m_strPortName, respectively.

The default implementation also sets m_bShowSplash to TRUE only in the case of a new file. In the case of a new file, the user has taken action involving the application itself. In any other case, including opening existing files using the shell, the user action involves the file directly. In a document-centric standpoint, the splash screen does not need to announce the application starting up.

Override this function in your derived class to handle other flag and parameter values.

CObject Class
Hierarchy Chart
CWinApp::ParseCommandLine
CWinApp::ProcessShellCommand

Show: