IEnvironment
- IEnvironment is a mechanism for building and manipulating environmental variables for passing
to the IExternalProcess class. It can certainly have other uses, but that is its primary reason for
being added to the OpenClass system. IEnvironment objects are little associative maps, in which
the key is a string (the name of the environment variable) and the associated data is also a string
(the value of the environment variable.)
IEnvironment objects can be iterated, in order to step through all of the environment variables that
it holds. It also allows you to add or remove variables, and to modify the contents of existing
variables.
IEnvironment - Member Functions and Data by Group
Constructors & Destructor
Construct and destruct IEnvironment objects.
- ~IEnvironment
- Cleans up the list of variable/value nodes maintained by the object.
public:
~IEnvironment()
- The destructor will destroy the internal list of variable and and value strings.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- IEnvironment
- Constructing an environment object sets up the internal data structures to get it ready for use. It
can also optionally suck in all of the existing environmental variables from the process'
environment.
Overload 1
- Copies another environment object's contents.
public:
IEnvironment(const IEnvironment& toCopy)
- The copy constructor just replicates the contents of the passed environment object.
- toCopy
- is the source object to copy construct from
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 2
- Constructs an IEnvironment object with all existing process environment variables
public:
IEnvironment(const bool copyCurrentEnv)
- This version will optionally create the environment object and initialize it to hold all of the process' current environmental variables. This is often very
convenient since you will want to pass along all of your own environment to your child processes.
- copyCurrentEnvironment
- indicates whether the object should initialize itself to represent the process' current environment
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 3
- Constructs an empty IEnvironment object.
public:
IEnvironment()
- The default constructor creates an empty environment object, with no initial variables.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Assignment
Assign one environment object to another.
- operator =
- Resets this object's contents to equal the passed object's.
public:
void operator =(const IEnvironment& toAssign)
- Deletes any existing contents and duplicates the variables of the source object being assigned.
- toAssign
- is the source object whose contents are to be replicated.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Data Access Methods
Access members of IEnvironment objects.
- add
- Adds a new variable to the environment object.
public:
void add(const IText& keyText, const IText& valueText)
- add() will add a new variable to the environment object. The new variable is given the passed value. Values
are not iterated in the order that they are added necessarily.
- keyText
- is the name of the variable to add
- valueText
- is the text value to give to this new variable
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- clear
- Clears all existing variables from the object.
public:
void clear()
- Clears out all of the existing variables from the environment object, leaving it as though it
was just default constructed.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- getCount
- Returns the count of variables in the object.
public:
unsigned long getCount() const
- Gets the count of variables in the environment object.
- Return
- The count of variables in the object.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- remove
- Removes a variable by name
public:
bool remove(const IText& keyText)
- Finds a variable by its key name (the name of the variable), and removes it from the environment object. The
count of variables is bumped down to account for this removal. If the name is not found, then the return is false.
If the node removed is the current internal iterator node, then the internal iterator is moved up to the next node
so that it remains valid (unless the node removed was the last node in the list or the only node.)
- keyText
- is the name of the variable to remove.
- Return
- true if the variable was found and removed, else false.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- update
- Update the value of a variable
public:
bool update(const IText& keyText, const IText& newValue)
- Finds a variable by its key name (the name of the variable) and updates its associated text value to the passed new
text value. If the variable is not found, then the return is false.
- keyText
- is the name of the variable to update
- newValue
- is the new value text to assign to this variable.
- Return
- true if the indicated variable was found and updated, else false.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Iterator Methods
Iterator through an environment object.
- first
- Sets the internal iterator to the first variable and returns its name and value.
public:
bool first(IText& keyText, IText& valueText)
- Finds the first variable in the list and sets up the internal iterator on that first element. This is required before calling next() to continue iterating through
the variables, or any time that you wish to restart the iteration back to the head of the list.
- keyText
- is filled with the name of the first variable
- keyValue
- is filled with the value of the first variable
- Return
- true if there were any variables in the object to iterate. If false, then the parameters are not changed.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
- next
- Moves the internal iterator to the next node and returns its name and value.
public:
bool next(IText& keyText, IText& valueText)
- After calling first() to find the first variable in the environment object, next() may be called to find subsequent variables. When there are no more
variables available, next() will return false.
- keyText
- is filled with the name of the next variable
- valueText
- is filled with the value of the next variable
- Return
- true if there was another variable to iterator. If false, then the passed parameters are not changed.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Search Methods
Find particular items in an environment object.
- find
- Looks up a variable in the environment object and returns its value, either by an IText return value or by copying the value into a provided IText object.
The latter is obviously more efficient if you already have a target text object, avoiding the need for the creation of a temporary for return.
Overload 1
- Finds a variable in the environment object.
public:
IText find(const IText& keyText) const
- This version take a key name (the name of the variable to find), and returns its contents in a temporary IText object. If its not found, then the returned
object just contains an empty string.
- keyText
- is the name of the variable to find
- Return
- An IText string with the variable's value. It will be an empty string if the variable does not exist.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
Overload 2
- Finds a variable in the environment object.
public:
bool find(const IText& keyText, IText& valueText) const
- This version takes a key (the variable to find) and copies the contents of that variable's value into a passed IText object.
- keyText
- is the name of the variable to find
- ValueText
- is filled with the value of the key, if it is found.
- Return
- true if the indicated key is found, else false.
- Supported Platforms
Windows |
OS/2 |
AIX |
Yes |
Yes |
Yes |
IEnvironment - Inherited Member Functions and Data
Inherited Public Functions
Inherited Public Data
Inherited Protected Functions
Inherited Protected Data