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.


[view class]
~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


[view class]
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.


[view class]
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.


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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.


[view class]
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


[view class]
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.


[view class]
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