nsICommandLine

IID:bc3173bd-aa46-46a0-9d25-d9867a9659b6
Inherits From:nsISupports
Status:UNDER_REVIEW This interface is intended to be frozen, but isn't frozen yet. Please use with care.

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>"

This interface is implemented by the following components:


Constants

PRUint32 STATE_INITIAL_LAUNCH = 0
PRUint32 STATE_REMOTE_AUTO = 1
PRUint32 STATE_REMOTE_EXPLICIT = 2

Properties

readonly PRInt32 length

Number of arguments in the command line. The application name is not part of the command line.

PRBool 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). This flag allows the default action to be prevented.

readonly PRUint32 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.

readonly nsIDOMWindow windowContext

A window to be targeted by this command line. In most cases, this will be null (xremote will sometimes set this attribute).

readonly nsIFile workingDirectory

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.


Methods

PRInt32 findFlag ( AString flag , PRBool caseSensitive ) AString getArgument ( PRInt32 index ) PRBool handleFlag ( AString flag , PRBool caseSensitive ) AString handleFlagWithParam ( AString flag , PRBool caseSensitive ) void removeArguments ( PRInt32 start , PRInt32 end ) nsIFile resolveFile ( AString argument ) nsIURI resolveURI ( AString argument )

PRInt32 findFlag ( AString flag , PRBool caseSensitive )

Find a command-line flag.

Arguments:
flag: The flag name to locate. Do not include the initial hyphen.
caseSensitive: Whether to do case-sensitive comparisons.
Returns:
The position of the flag in the command line.

AString getArgument ( PRInt32 index )

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.

Arguments:
index: The argument to retrieve. This index is 0-based, and does not include the application name.
Returns:
The indexth argument.

PRBool handleFlag ( AString flag , PRBool caseSensitive )

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

Arguments:
flag: The flag name to find and remove.
caseSensitive: Whether to do case-sensitive comparisons.
Returns:
Whether the flag was found.

AString handleFlagWithParam ( AString flag , PRBool caseSensitive )

Find a flag with a parameter and remove both. This is a helper method that combines "findFlag" and "removeArguments" in one step.

Arguments:
flag: The flag name to find and remove.
caseSensitive: Whether to do case-sensitive flag search.
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.

void removeArguments ( PRInt32 start , PRInt32 end )

Remove arguments from the command line. This normally occurs after a handler has processed the arguments.

Arguments:
start: Index to begin removing.
end: Index to end removing, inclusive.

nsIFile resolveFile ( AString argument )

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.

Arguments:
argument: The command-line argument to resolve.

nsIURI resolveURI ( AString argument )

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.

Arguments:
argument: The command-line argument to resolve.

References

This interface is passed as an argument to the following methods:

nsIBrowserHandler.getFeatures, nsICommandLineHandler.handle, nsIExtensionManager.handleCommandLineArgs, nsIExtensionManager.start

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
No comments available

Copyright © 1999 - 2005 XULPlanet.com