summaryrefslogtreecommitdiffstats
path: root/src/corelib/io/qprocess.cpp
diff options
context:
space:
mode:
authorThiago Macieira <thiago.macieira@nokia.com>2009-05-13 14:54:03 (GMT)
committerThiago Macieira <thiago.macieira@nokia.com>2009-08-21 13:03:06 (GMT)
commit0375a941dcd45b71a9397dbd405c9c055ab9a81a (patch)
tree0ad6be315129ce14bbdc3c73a2793a58b5d464c3 /src/corelib/io/qprocess.cpp
parente2b1ab498d0e3b194d5aaa9dd8d6a7112d1a0201 (diff)
downloadQt-0375a941dcd45b71a9397dbd405c9c055ab9a81a.zip
Qt-0375a941dcd45b71a9397dbd405c9c055ab9a81a.tar.gz
Qt-0375a941dcd45b71a9397dbd405c9c055ab9a81a.tar.bz2
Document the new QProcessEnvironment class
Diffstat (limited to 'src/corelib/io/qprocess.cpp')
-rw-r--r--src/corelib/io/qprocess.cpp168
1 files changed, 165 insertions, 3 deletions
diff --git a/src/corelib/io/qprocess.cpp b/src/corelib/io/qprocess.cpp
index b9dd9d7..7c13bf0 100644
--- a/src/corelib/io/qprocess.cpp
+++ b/src/corelib/io/qprocess.cpp
@@ -101,6 +101,44 @@ QT_END_NAMESPACE
QT_BEGIN_NAMESPACE
+/*!
+ \class QProcessEnvironment
+
+ \brief The QProcessEnvironment class holds the environment variables that
+ can be passed to a program.
+
+ \ingroup io
+ \ingroup misc
+ \mainclass
+ \reentrant
+ \since 4.6
+
+ A process's environment is composed of a set of key=value pairs known as
+ environment variables. The QProcessEnvironment class wraps that concept
+ and allows easy manipulation of those variables. It's meant to be used
+ along with QProcess, to set the environment for child processes. It
+ cannot be used to change the current process's environment.
+
+ The environment of the calling process can be obtained using
+ QProcessEnvironment::systemEnvironment().
+
+ On Unix systems, the variable names are case-sensitive. For that reason,
+ this class will not touch the names of the variables. Note as well that
+ Unix environment allows both variable names and contents to contain arbitrary
+ binary data (except for the NUL character), but this is not supported by
+ QProcessEnvironment. This class only supports names and values that are
+ encodable by the current locale settings (see QTextCodec::codecForLocale).
+
+ On Windows, the variable names are case-insensitive. Therefore,
+ QProcessEnvironment will always uppercase the names and do case-insensitive
+ comparisons.
+
+ On Windows CE, the concept of environment does not exist. This class will
+ keep the values set for compatibility with other platforms, but the values
+ set will have no effect on the processes being created.
+
+ \sa QProcess, QProcess::systemEnvironment(), QProcess::setProcessEnvironment()
+*/
#ifdef Q_OS_WIN
static inline QProcessEnvironmentPrivate::Unit prepareName(const QString &name)
{ return name.toUpper(); }
@@ -179,56 +217,148 @@ QProcessEnvironment QProcessEnvironmentPrivate::fromList(const QStringList &list
return env;
}
+/*!
+ Creates a new QProcessEnvironment object. This constructor creates an
+ empty environment. If set on a QProcess, this will cause the current
+ environment variables to be removed.
+*/
QProcessEnvironment::QProcessEnvironment()
: d(0)
{
}
+/*!
+ Frees the resources associated with this QProcessEnvironment object.
+*/
QProcessEnvironment::~QProcessEnvironment()
{
}
+/*!
+ Creates a QProcessEnvironment object that is a copy of \a other.
+*/
QProcessEnvironment::QProcessEnvironment(const QProcessEnvironment &other)
: d(other.d)
{
}
+/*!
+ Copies the contents of the \a other QProcessEnvironment object into this
+ one.
+*/
QProcessEnvironment &QProcessEnvironment::operator=(const QProcessEnvironment &other)
{
d = other.d;
return *this;
}
+/*!
+ \fn bool QProcessEnvironment::operator !=(const QProcessEnvironment &other) const
+
+ Returns true if this and the \a other QProcessEnvironment objects are different.
+
+ \sa operator==()
+*/
+
+/*!
+ Returns true if this and the \a other QProcessEnvironment objects are equal.
+
+ Two QProcessEnvironment objects are considered equal if they have the same
+ set of key=value pairs. The comparison of keys is done case-sensitive on
+ platforms where the environment is case-sensitive.
+
+ \sa operator!=(), contains()
+*/
bool QProcessEnvironment::operator==(const QProcessEnvironment &other) const
{
return d->hash == other.d->hash;
}
+/*!
+ Returns true if this QProcessEnvironment object is empty: that is
+ there are no key=value pairs set.
+
+ \sa clear(), systemEnvironment(), insert()
+*/
bool QProcessEnvironment::isEmpty() const
{
return d ? d->hash.isEmpty() : true;
}
+/*!
+ Removes all key=value pairs from this QProcessEnvironment object, making
+ it empty.
+
+ \sa isEmpty(), systemEnvironment()
+*/
void QProcessEnvironment::clear()
{
d->hash.clear();
}
+/*!
+ Returns true if the environment variable of name \a name is found in
+ this QProcessEnvironment object.
+
+ On Windows, variable names are case-insensitive, so the key is converted
+ to uppercase before searching. On other systems, names are case-sensitive
+ so no trasformation is applied.
+
+ \sa insert(), value()
+*/
bool QProcessEnvironment::contains(const QString &name) const
{
return d ? d->hash.contains(prepareName(name)) : false;
}
+/*!
+ Inserts the environment variable of name \a name and contents \a value
+ into this QProcessEnvironment object. If that variable already existed,
+ it is replaced by the new value.
+
+ On Windows, variable names are case-insensitive, so this function always
+ uppercases the variable name before inserting. On other systems, names
+ are case-sensitive, so no transformation is applied.
+
+ On most systems, inserting a variable with no contents will have the
+ same effect for applications as if the variable had not been set at all.
+ However, to guarantee that there are no incompatibilities, to remove a
+ variable, please use the remove() function.
+
+ \sa contains(), remove(), value()
+*/
void QProcessEnvironment::insert(const QString &name, const QString &value)
{
d->hash.insert(prepareName(name), prepareValue(value));
}
+/*!
+ Removes the environment variable identified by \a name from this
+ QProcessEnvironment object. If that variable did not exist before,
+ nothing happens.
+
+ On Windows, variable names are case-insensitive, so the key is converted
+ to uppercase before searching. On other systems, names are case-sensitive
+ so no trasformation is applied.
+
+ \sa contains(), insert(), value()
+*/
void QProcessEnvironment::remove(const QString &name)
{
d->hash.remove(prepareName(name));
}
+/*!
+ Searches this QProcessEnvironment object for a variable identified by
+ \a name and returns its value. If the variable is not found in this object,
+ then \a defaultValue is returned instead.
+
+ On Windows, variable names are case-insensitive, so the key is converted
+ to uppercase before searching. On other systems, names are case-sensitive
+ so no trasformation is applied.
+
+ \sa contains(), insert(), remove()
+*/
QString QProcessEnvironment::value(const QString &name, const QString &defaultValue) const
{
if (!d)
@@ -238,6 +368,19 @@ QString QProcessEnvironment::value(const QString &name, const QString &defaultVa
return valueToString(result);
}
+/*!
+ Converts this QProcessEnvironment object into a list of strings, one for
+ each environment variable that is set. The environment variable's name
+ and its value are separated by an equal character ('=').
+
+ The QStringList contents returned by this function are suitable for use
+ with the QProcess::setEnvironment function. However, it is recommended
+ to use QProcess::setProcessEnvironment instead since that will avoid
+ unnecessary copying of the data.
+
+ \sa systemEnvironment(), QProcess::systemEnvironment(), QProcess::environment(),
+ QProcess::setEnvironment()
+*/
QStringList QProcessEnvironment::toStringList() const
{
return d ? d->toList() : QStringList();
@@ -1341,6 +1484,9 @@ QProcess::ProcessState QProcess::state() const
\snippet doc/src/snippets/qprocess-environment/main.cpp 0
+ \note This function is less efficient than the setProcessEnvironment()
+ function.
+
\sa environment(), setProcessEnvironment(), systemEnvironment()
*/
void QProcess::setEnvironment(const QStringList &environment)
@@ -1367,7 +1513,7 @@ QStringList QProcess::environment() const
}
/*!
- \since 4.5
+ \since 4.6
Sets the environment that QProcess will use when starting a process to the
\a environment object.
@@ -1387,7 +1533,7 @@ void QProcess::setProcessEnvironment(const QProcessEnvironment &environment)
}
/*!
- \since 4.5
+ \since 4.6
Returns the environment that QProcess will use when starting a
process, or an empty object if no environment has been set using
setEnvironment() or setProcessEnvironment(). If no environment has
@@ -2000,6 +2146,15 @@ QT_END_INCLUDE_NAMESPACE
\snippet doc/src/snippets/code/src_corelib_io_qprocess.cpp 8
+ This function does not cache the system environment. Therefore, it's
+ possible to obtain an updated version of the environment if low-level C
+ library functions like \tt setenv ot \tt putenv have been called.
+
+ However, note that repeated calls to this function will recreate the
+ list of environment variables, which is a non-trivial operation.
+
+ \note For new code, it is recommended to use QProcessEvironment::systemEnvironment()
+
\sa QProcessEnvironment::systemEnvironment(), environment(), setEnvironment()
*/
QStringList QProcess::systemEnvironment()
@@ -2013,10 +2168,17 @@ QStringList QProcess::systemEnvironment()
}
/*!
- \since 4.5
+ \since 4.6
Returns the environment of the calling process as a QProcessEnvironment.
+ This function does not cache the system environment. Therefore, it's
+ possible to obtain an updated version of the environment if low-level C
+ library functions like \tt setenv ot \tt putenv have been called.
+
+ However, note that repeated calls to this function will recreate the
+ QProcessEnvironment object, which is a non-trivial operation.
+
\sa QProcess::systemEnvironment()
*/
QProcessEnvironment QProcessEnvironment::systemEnvironment()