mozilla
Your Search Results

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

    Document Tags and Contributors

    Contributors to this page: BenjaminSmedberg, Sheppy, Nickolay, trevorh, Grubshka
    Last updated by: Sheppy,