ProcessProbe Item¶

class ProcessProbe¶: Starts and watches processes.

Inherits:	`Component`
Enumerations:	`ProcessError`. `State`
Properties:	`arguments`, `exitCode`, `program` `state`, `workingDirectory`
Methods:	`readAllStandardError()`, `readAllStandardOutput()` `start()`, `terminate()`, `waitForFinished()` `waitForStarted()`
Signals:	`errorOccurred()`, `started()`, `finished()`

Detailed Description¶

ProcessProbe can invoke external applications and communicate with them. It mirrors the API of QProcess.

The process to run is defined by the program property. Arguments are provided as a string list in the arguments property.

Example:

import qst 1.0

Testcase {

    ProcessProbe {
        id: make
        program : (Qst.hostOs === "windows") ? "gmake.exe" : "make"
        arguments: [
            "-j",
            "8"
        ]
    }

    function run() {
        make.start();
        make.waitForFinished(1701);
        Qst.compare(make.exitCode, 0, "Make did not succeed");
    }
}

Enumerations¶

enum ProcessError¶

Error events during process execution. Further information may be obtained with errorString().

enumerator Crashed¶: The process crashed some time after starting successfully.

enumerator FailedToStart¶: The process failed to start. Either the invoked program is missing, or you may have insufficient permissions to invoke the program.

enumerator ReadError¶: An error occurred when attempting to read from the process. For example, the process may not be running.

enumerator Timedout¶: The last waitFor…() function timed out. The state of ProcessProbe is unchanged, and you can try calling waitFor…() again.

enumerator WriteError¶: An error occurred when attempting to write to the process. For example, the process may not be running, or it may have closed its input channel.

enumerator UnknownError¶: An unknown error occurred.

enum State¶

Execution state of the process.

enumerator NotRunning¶: The process has not been started or it has already finished.

enumerator Starting¶: The process is starting, but it is not running yet.

enumerator Running¶: The process is running.

Properties¶

stringlist arguments¶

Process arguments in list format. Unlike on a shell, spaces do not separate arguments and thus, each argument must be a separate list entry. Escaping is required for arguments containing spaces.:

// Wrong
arguments: [ "--file My\ File.txt " ]

// Correct
arguments: [
    "--file",
    "My File.txt"
]

integer exitCode¶: The exit code of the last process that finished. This property is read-only.

string program¶: Path to an executable to run.

State state¶: The current execution state of the process.

string workingDirectory¶

Methods¶

string errorString()¶: Returns a human-readable description of the last error that occurred.

string readAllStandardError()¶: This function returns all data available from the standard error of the process.

string readAllStandardOutput()¶: This function returns all data available from the standard output of the process.

void start()¶: Starts the process set by program with the arguments given by arguments. This function returns immediately.

void terminate()¶: Attempts to terminate the process.

bool waitForFinished(int milliseconds)¶

Blocks until the process has finished and the finished() signal has been emitted, or until milliseconds have passed.

Returns true if the process finished; otherwise returns false (if the operation timed out, if an error occurred, or if this process is already finished).

If milliseconds is -1, this function will not time out.

bool waitForStarted(int milliseconds)¶

Blocks until the process has started and the started() signal has been emitted, or until milliseconds have passed.

Returns true if the process was started successfully; otherwise returns false (if the operation timed out or if an error occurred).

Signals¶

void errorOccurred(ProcessError error)¶: An error has occurred during execution. A human-readable version of the error may be obtained with errorString().

void finished()¶: This signal is emitted when the process finishes. exitCode is the exit code of the process (only valid for normal exits). After the process has finished, the buffers in QProcess are still intact. You can still read any data that the process may have written before it finished.

void started()¶: This signal is emitted by ProcessProbe when the process has started, and state is State::Running.