xpcom/threads/nsIEnvironment.idl

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 /**
   9  * Scriptable access to the current process environment.
  10  *
  11  */
  12 [scriptable, uuid(101d5941-d820-4e85-a266-9a3469940807)]
  13 interface nsIEnvironment : nsISupports
  14 {
  15     /**
  16      * Set the value of an environment variable.
  17      *
  18      * @param aName   the variable name to set.
  19      * @param aValue  the value to set.
  20      */
  21     void set(in AString aName, in AString aValue);
  22
  23     /**
  24      * Get the value of an environment variable.
  25      *
  26      * @param aName   the variable name to retrieve.
  27      * @return        returns the value of the env variable. An empty string
  28      *                will be returned when the env variable does not exist or
  29      *                when the value itself is an empty string - please use
  30      *                |exists()| to probe whether the env variable exists
  31      *                or not.
  32      */
  33     AString get(in AString aName);
  34
  35     /**
  36      * Check the existence of an environment variable.
  37      * This method checks whether an environment variable is present in
  38      * the environment or not.
  39      *
  40      * - For Unix/Linux platforms we follow the Unix definition:
  41      * An environment variable exists when |getenv()| returns a non-NULL value.
  42      * An environment variable does not exist when |getenv()| returns NULL.
  43      * - For non-Unix/Linux platforms we have to fall back to a
  44      * "portable" definition (which is incorrect for Unix/Linux!!!!)
  45      * which simply checks whether the string returned by |Get()| is empty
  46      * or not.
  47      *
  48      * @param aName   the variable name to probe.
  49      * @return        if the variable has been set, the value returned is
  50      *                PR_TRUE. If the variable was not defined in the
  51      *                environment PR_FALSE will be returned.
  52      */
  53     boolean exists(in AString aName);
  54 };