Public Member Functions | Public Attributes

nsICommandLine Interface Reference

Represents the command line used to invoke a XUL application. More...

import "nsICommandLine.idl";

Inheritance diagram for nsICommandLine:
Collaboration diagram for nsICommandLine:

List of all members.

Public Member Functions

AString getArgument (in long aIndex)
 Get an argument from the array of command-line arguments.
long findFlag (in AString aFlag, in boolean aCaseSensitive)
 Find a command-line flag.
void removeArguments (in long aStart, in long aEnd)
 Remove arguments from the command line.
boolean handleFlag (in AString aFlag, in boolean aCaseSensitive)
 A helper method which will find a flag and remove it in one step.
AString handleFlagWithParam (in AString aFlag, in boolean aCaseSensitive)
 Find a flag with a parameter and remove both.
nsIFile resolveFile (in AString aArgument)
 Resolve a file-path argument into an nsIFile.
nsIURI resolveURI (in AString aArgument)
 Resolves a URI argument into a URI.

Public Attributes

readonly attribute long length
 Number of arguments in the command line.
readonly attribute unsigned long state
 The type of command line being processed.
const unsigned long STATE_INITIAL_LAUNCH = 0
const unsigned long STATE_REMOTE_AUTO = 1
const unsigned long STATE_REMOTE_EXPLICIT = 2
attribute boolean preventDefault
 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).
readonly attribute nsIFile workingDirectory
 The working directory for this command line.
readonly attribute nsIDOMWindow windowContext
 A window to be targeted by this command line.

Detailed Description

Represents the command line used to invoke a XUL application.

This may be the original command-line of this instance, or a command line remoted from another instance of the application.

DEFINITIONS: "arguments" are any values found on the command line. "flags" are switches. In normalized form they are preceded by a single dash. Some flags may take "parameters", e.g. "-url <param>" or "-install-xpi <param>"

Status:
UNDER_REVIEW This interface is intended to be frozen, but isn't frozen yet. Please use with care.

Member Function Documentation

long nsICommandLine::findFlag ( in AString  aFlag,
in boolean  aCaseSensitive 
)

Find a command-line flag.

Parameters:
aFlag The flag name to locate. Do not include the initial hyphen.
aCaseSensitive Whether to do case-sensitive comparisons.
Returns:
The position of the flag in the command line.
AString nsICommandLine::getArgument ( in long  aIndex  ) 

Get an argument from the array of command-line arguments.

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

On *nix and mac flags of the form --flag are normalized to -flag. --flag=param are normalized to the form -flag param.

Parameters:
aIndex The argument to retrieve. This index is 0-based, and does not include the application name.
Returns:
The indexth argument.
Exceptions:
NS_ERROR_INVALID_ARG if aIndex is out of bounds.
boolean nsICommandLine::handleFlag ( in AString  aFlag,
in boolean  aCaseSensitive 
)

A helper method which will find a flag and remove it in one step.

Parameters:
aFlag The flag name to find and remove.
aCaseSensitive Whether to do case-sensitive comparisons.
Returns:
Whether the flag was found.
AString nsICommandLine::handleFlagWithParam ( in AString  aFlag,
in boolean  aCaseSensitive 
)

Find a flag with a parameter and remove both.

This is a helper method that combines "findFlag" and "removeArguments" in one step.

Returns:
null (a void astring) if the flag is not found. The parameter value if found. Note that null and the empty string are not the same.
Exceptions:
NS_ERROR_INVALID_ARG if the flag exists without a parameter
Parameters:
aFlag The flag name to find and remove.
aCaseSensitive Whether to do case-sensitive flag search.
void nsICommandLine::removeArguments ( in long  aStart,
in long  aEnd 
)

Remove arguments from the command line.

This normally occurs after a handler has processed the arguments.

Parameters:
aStart Index to begin removing.
aEnd Index to end removing, inclusive.
nsIFile nsICommandLine::resolveFile ( in AString  aArgument  ) 

Resolve a file-path argument into an nsIFile.

This method gracefully handles relative or absolute file paths, according to the working directory of this command line.

Parameters:
aArgument The command-line argument to resolve.
nsIURI nsICommandLine::resolveURI ( in AString  aArgument  ) 

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 ioservice if passed directly.

Parameters:
aArgument The command-line argument to resolve.

Member Data Documentation

readonly attribute long nsICommandLine::length

Number of arguments in the command line.

The application name is not part of the command line.

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.

readonly attribute unsigned long nsICommandLine::state

The type of command line being processed.

STATE_INITIAL_LAUNCH is the first launch of the application instance. STATE_REMOTE_AUTO is a remote command line automatically redirected to this instance. STATE_REMOTE_EXPLICIT is a remote command line explicitly redirected to this instance using xremote/windde/appleevents.

const unsigned long nsICommandLine::STATE_INITIAL_LAUNCH = 0
const unsigned long nsICommandLine::STATE_REMOTE_AUTO = 1
const unsigned long nsICommandLine::STATE_REMOTE_EXPLICIT = 2

A window to be targeted by this command line.

In most cases, this will be null (xremote will sometimes set this attribute).

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.


The documentation for this interface was generated from the following file: