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.

Syntax

class CCommandLineInfo : public CObject  

Members

Public Constructors

Name	Description
CCommandLineInfo::CCommandLineInfo	Constructs a default CCommandLineInfo object.

Public Methods

Name	Description
CCommandLineInfo::ParseParam	Override this callback to parse individual parameters.

Public Data Members

Name	Description
CCommandLineInfo::m_bRunAutomated	Indicates the command-line /Automation option was found.
CCommandLineInfo::m_bRunEmbedded	Indicates the command-line /Embedding option was found.
CCommandLineInfo::m_bShowSplash	Indicates if a splash screen should be shown.
CCommandLineInfo::m_nShellCommand	Indicates the shell command to be processed.
CCommandLineInfo::m_strDriverName	Indicates the driver name if the shell command is Print To; otherwise empty.
CCommandLineInfo::m_strFileName	Indicates the file name to be opened or printed; empty if the shell command is New or DDE.
CCommandLineInfo::m_strPortName	Indicates the port name if the shell command is Print To; otherwise empty.
CCommandLineInfo::m_strPrinterName	Indicates the printer name if the shell command is Print To; otherwise empty.
CCommandLineInfo::m_strRestartIdentifier	Indicates the unique restart identifier for the restart manager if the restart manager restarted the application.

Remarks

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 argument	Command executed
app	New file.
app filename	Open file.
app /p filename	Print file to default printer.
app /pt filename printer driver port	Print file to the specified printer.
app /dde	Start up and await DDE command.
app /Automation	Start up as an OLE automation server.
app /Embedding	Start 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.

Inheritance Hierarchy

CObject

CCommandLineInfo

Requirements

Header: afxwin.h

CCommandLineInfo::CCommandLineInfo

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);

CCommandLineInfo::m_bRunAutomated

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.

CCommandLineInfo::m_bRunEmbedded

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.

CCommandLineInfo::m_bShowSplash

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.

CCommandLineInfo::m_nShellCommand

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;

CCommandLineInfo::m_strDriverName

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.

CCommandLineInfo::m_strFileName

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.

CCommandLineInfo::m_strPortName

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.

CCommandLineInfo::m_strPrinterName

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.

CCommandLineInfo::m_strRestartIdentifier

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.

CCommandLineInfo::ParseParam

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 argument	Command executed
app	New file.
app filename	Open file.
app /p filename	Print file to default printer.
app /pt filename printer driver port	Print file to the specified printer.
app /dde	Start up and await DDE command.
app /Automation	Start up as an OLE automation server.
app /Embedding	Start 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.

See Also

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