nsICommandLine

Represents the command line used to invoke a XUL application. This may be the original command line of this instance or a command line provided remotely by another instance of the application.
1.0
66
Introduced
Gecko 1.8
Inherits from: nsISupports Last changed in Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

Components may implement the nsICommandLineHandler interface to add custom command line handling behavior.

Definitions

arguments
Any values found on the command line.
switches
Flags. In normalized form, these are preceded by a single dash. Some flags may take parameters; for example: "-url <param>" or "-install-xpi <param>".

Method overview

long findFlag(in AString aFlag, in boolean aCaseSensitive);
AString getArgument(in long aIndex);
boolean handleFlag(in AString aFlag, in boolean aCaseSensitive);
AString handleFlagWithParam(in AString aFlag, in boolean aCaseSensitive);
void removeArguments(in long aStart, in long aEnd);
nsIFile resolveFile(in AString aArgument);
nsIURI resolveURI(in AString aArgument);

Attributes

Attribute Type Description
length long Number of arguments in the command line. The application name is not part of the command line. Read only.
preventDefault boolean There may be a command-line handler which performs a default action if there was no explicit action on the command line (open a default browser window, for example). This flag allows the default action to be prevented.
state unsigned long

The type of command line being processed. See State constants. Read only.
windowContext nsIDOMWindow A window to be targeted by this command line. In most cases, this will be null (xremote will sometimes set this attribute). Read only.
workingDirectory nsIFile The working directory for this command line. Use this property instead of the working directory for the current process, since a redirected command line may have had a different working directory. Read only.

Constants

State constants

Constant Value Description
STATE_INITIAL_LAUNCH 0 The first launch of the application instance.
STATE_REMOTE_AUTO 1 A remote command line automatically redirected to this instance.
STATE_REMOTE_EXPLICIT 2 A remote command line explicitly redirected to this instance using xremote/windde/appleevents.

Methods

findFlag()

Finds a command-line flag, returning its position on the command line.

long findFlag(
  in AString aFlag,
  in boolean aCaseSensitive
);
Parameters
aFlag
The flag name to locate. Do not include the initial hyphen.
aCaseSensitive
Whether to do case-sensitive comparisons.
Return value

The position of the flag in the command line, or -1 if the flag is not found.

getArgument()

Gets the value an argument from the array of command-line arguments, given the index into the argument list.

On Windows, flags of the form /flag are normalized to -flag. /flag:param are normalized to -flag param.

On Unix/Linux and Mac OS X, flags of the form --flag are normalized to -flag, and flags of the form --flag=param are normalized to the form -flag param.

AString getArgument(
  in long aIndex
);
Parameters
aIndex
The argument to retrieve. This index is 0-based, and does not include the application name.
Return value

The value of the specified argument. This is the full text of that argument, so if the argument is a flag, the returned value is "-flag [<flagvalue>]".

Exceptions thrown
NS_ERROR_INVALID_ARG
The specified index is out of bounds.

handleFlag()

Finds the specified flag, removing it from the array of flags. Reports whether or not the specified flag was found. This is useful for Boolean flags; that is, flags that don't accept a parameter. You can determine if the flag was provided and remove it from the list of flags waiting to be processed in one operation.

boolean handleFlag(
  in AString aFlag,
  in boolean aCaseSensitive
);
Parameters
aFlag
The flag name to find and remove.
aCaseSensitive
Whether to do case-sensitive comparisons.
Return value

true if the flag was found, otherwise false.

handleFlagWithParam()

Finds a flag in the list of flags waiting to be processed and returns its value, after removing both the flag and its value from the list of flags waiting to be handled. This is useful for processing flags that accept a value. This is, essentially, a helper method that combines findFlag() and removeArguments() into one operation.

AString handleFlagWithParam(
  in AString aFlag,
  in boolean aCaseSensitive
);
Parameters
aFlag
The flag name to find and remove.
aCaseSensitive
Whether to do case-sensitive flag search.
Return value

The value of the specified flag, an empty string if the flag's value is the empty string, or null if the specified parameter wasn't found.

Exceptions thrown
NS_ERROR_INVALID_ARG
The specified flag has no value.

removeArguments()

Removes a range of arguments from the command line; this is typically done once those arguments have been handled.

void removeArguments(
  in long aStart,
  in long aEnd
);
Parameters
aStart
The index to the first argument to remove from the command line; this is 0-based, and the name of the application is not included.
aEnd
The index to the last argument to remove from the command line.

resolveFile()

Resolves a file-path argument into an nsIFile object. This method gracefully handles relative or absolute file paths, according to the working directory of this command line.

nsIFile resolveFile(
  in AString aArgument
);
Parameters
aArgument
The command-line argument to resolve.
Return value

The file path as an nsIFile.

resolveURI()

Resolves a URI argument into a URI. This method has platform-specific logic for converting an absolute URI or a relative file-path into the appropriate URI object; it gracefully handles win32 C:\ paths which would confuse the I/O service if passed directly.

nsIURI resolveURI(
  in AString aArgument
);
Parameters
aArgument
The command-line argument to resolve.
Return value

A platform-specific URI.

See also