DzProcess Class Reference
[File Input and Output Objects]

A class for starting/communicating with external programs. More...

Inheritance diagram for DzProcess:

QObject Object List of all members.

Enumerations

enum  Communication { Stdin = 0x01, Stdout = 0x02, Stderr = 0x04, DupStderr = 0x08 }

Properties

Array arguments
Communication communication
Number exitStatus
Boolean normalExit
Boolean running
String workingDirectory

Methods

Boolean canReadLineStderr ()
Boolean canReadLineStdout ()
void closeStdin ()
void kill ()
Boolean launch (String buffer, Array env=0)
String readLineStderr ()
String readLineStdout ()
String readStderr ()
String readStdout ()
Boolean start (Array env=0)
void tryTerminate ()
void writeToStdin (String buffer)

Constructors

 DzProcess (Array args)
 DzProcess (String arg0)
 DzProcess ()

Signals

void launchFinished ()
 Signature: "launchFinished()"
void processExited ()
 Signature: "processExited()"
void readyReadStderr ()
 Signature: "readyReadStderr()"
void readyReadStdout ()
 Signature: "readyReadStdout()"
void wroteToStdin ()
 Signature: "wroteToStdin()"

Detailed Description

A class for starting/communicating with external programs.

See the Render To RIB sample (line #440+), to see this class in action.


Member Enumeration Documentation

enum DzProcess::Communication

Defines the communication channels connected to the process.

Enumerator:
Stdin  Data can be written to the process' standard input.
Stdout  Data can be read from the process' standard output.
Stderr  Data can be read from the process' standard error.
DupStderr  Both, the process' standard error and its standard output are written to its standard output (which means nothing is sent to its standard error).


Constructor & Destructor Documentation

DzProcess::DzProcess (  ) 

Default Constructor.

Creates a DzProcess object without specifying the program or arguments. This does NOT start start the process.

DzProcess::DzProcess ( String  arg0  ) 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Creates a DzProcess object specifying only the program, without any arguments. This does NOT start start the process.

DzProcess::DzProcess ( Array  args  ) 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Creates a DzProcess object specifying the program and any arguments. The first element of args is the program to execute, the rest are the command line arguments. This does NOT start start the process.


Member Function Documentation

Boolean DzProcess::canReadLineStderr (  ) 

Returns:
true if it is possible to read an entire line of text from standard error, otherwise false.

Boolean DzProcess::canReadLineStdout (  ) 

Returns:
true if it is possible to read an entire line of text from standard output, otherwise false.

void DzProcess::closeStdin (  ) 

Closes the process' standard input and deletes any pending data that hasn't been written to standard input.

void DzProcess::kill (  ) 

Terminates the process.

Attention:
This is not a safe way to end a process, as the process will not be able to perform any cleanup. tryTerminate() is safer, but process' can ignore it.

Boolean DzProcess::launch ( String  buffer,
Array  env = 0 
)

Attempts to run the process, writing buffer to the process' standard input. Standard input is closed if all of the data in buffer is written to it. If env is specified, the values in the Array [of strings] are interpreted as environment settings in the form VARIABLE=VALUE, and the process is started with these environment settings. If env is not specifiied, the process is started with the same environment settings as the starting process.

Returns:
true if the process was able to start, otherwise false.

void DzProcess::launchFinished (  )  [signal]

Signature: "launchFinished()"

Emitted when the process is started with launch(). If starting the process is successful, this signal is emitted after the data passed in has been written to standard input. If starting the process fails, this signal is emitted immediately.

void DzProcess::processExited (  )  [signal]

Signature: "processExited()"

Emitted when the process has exited.

QString DzProcess::readLineStderr (  ) 

Returns:
A line of text from standard error, minus any trailing newline or carriage return characters if canReadLineStderr() is true, otherwise an empty string.

QString DzProcess::readLineStdout (  ) 

Returns:
A line of text from standard output, minus any trailing newline or carriage return characters if canReadLineStdout() is true, otherwise an empty string.

QString DzProcess::readStderr (  ) 

Reads the data that the process has written to standard error. When new data is written, the readyReadStderr() signal is emitted.

Returns:
The data written to standard error, or an empty string if there is no such data.
Attention:
This method does not wait for there to be something to read.

QString DzProcess::readStdout (  ) 

Reads the data that the process has written to standard output. When new data is written, the readyReadStdout() signal is emitted.

Returns:
The data written to standard output, or an empty string if there is no such data.
Attention:
This method does not wait for there to be something to read.

void DzProcess::readyReadStderr (  )  [signal]

Signature: "readyReadStderr()"

Emitted when the process has written data to standard error.

void DzProcess::readyReadStdout (  )  [signal]

Signature: "readyReadStdout()"

Emitted when the process has written data to standard output.

Boolean DzProcess::start ( Array  env = 0  ) 

Attempts to run the process for the program and arguments specified with the arguments property or as specified in the constructor. If env is specified, the values in the Array [of strings] are interpreted as environment settings in the form VARIABLE=VALUE, and the process is started with these environment settings. If env is not specifiied, the process is started with the same environment settings as the starting process.

Returns:
true if the process was able to start, otherwise false.

void DzProcess::tryTerminate (  ) 

Attempts to terminate the process.

Attention:
Process' can ignore this, if they choose to. If you want to be certain that the process is terminated, use kill() instead.

void DzProcess::writeToStdin ( String  buffer  ) 

Writes buffer to standard input. The process may, or may not, read the data. The wroteToStdin() signal is emitted once all data in buffer has been written to the process.

void DzProcess::wroteToStdin (  )  [signal]

Signature: "wroteToStdin()"

Emitted if the data sent to standard input (via writeToStdin()) was actually written to the process.


Member Data Documentation

QStringList DzProcess::arguments

Holds an Array of strings. The first being the program to execute, the rest being the command line arguments.

int DzProcess::communication

Holds the communication for the process.

int DzProcess::exitStatus

Holds the exit status of the program when it has finished. 0 if the process is still running. (Read Only)

bool DzProcess::normalExit

Holds whether or not the process has exited normally. (Read Only)

Boolean DzProcess::running

Holds whether or not the process is currently running. (Read Only)

QString DzProcess::workingDirectory

Holds the working directory for the process.


Generated on Thu Sep 24 12:21:14 2009

Copyright © 2002 - 2009 DAZ 3D, Inc.