Process

Description

The Process object allows running and managing an external process.

› Inherits:Object

Properties

arguments

This property holds the arguments which to pass to the program.

› Type:StringList
› Signal:argumentsChanged()
› Attributes:Writable

error

This property holds the most recently occurred error or Process.NoError if no error occurred. If the same error occurs multiple times this property does not change. Use the errorOccurred() signal to detect multiple occurrences of the same error.

› Type:Error
› Signal:errorChanged()
› Attributes:Readonly

errorString

This property holds the current human readable error string corresponding to the current value in the error property. It may include additional information such as failure reasons or locations.

› Type:String
› Signal:errorStringChanged()
› Attributes:Readonly

exitCode

This property holds the exit code of the last process that finished. It’s only valid if no Process.Crashed error occurred.

This property was introduced in InCore 1.1.

› Type:SignedInteger
› Signal:exitCodeChanged()
› Attributes:Readonly

program

This property holds the name of the program to run. If not in PATH a relative or absolute path has to be specified as well.

› Type:String
› Signal:programChanged()
› Attributes:Writable

running

This property holds whether the program is running. It can be used for both querying and changing the status and is updated automatically when calling start() and stop().

› Type:Boolean
› Default:false
› Signal:runningChanged()
› Attributes:Writable

Methods

kill()

This method kills the program to using the SIGKILL signal.

start()

This method starts the program asynchronously. Any errors will be signaled via the error property and the errorOccurred() signal.

› Returns:Boolean

stop()

This method requests the program to stop using the SIGTERM signal.

Signals

errorOccurred()

This signal is emitted whenever an error has occurred, regardless of whether the error property has changed or not. In contrast to the change notification signal of the error property this signal is also emitted several times if a certain error occurs several times in succession.

finished()

This signal is emitted when the process finishes and running equals false. The exit code of the program is available in the exitCode property.

This signal was introduced in InCore 1.1.

started()

This signal is emitted when the process has started and running equals true.

This signal was introduced in InCore 1.1.

Enumerations

Error

This enumeration describes all errors which can occur in Process objects. The most recently occurred error is stored in the error property.

Name Value Description
Process.NoError 0 No error occurred or was detected.
Process.AlreadyRunning 1 Process is already running and has to be stopped first.
Process.InvalidProgram 2 Program is empty or invalid.
Process.FailedToStart 3 The process failed to start. Either the specified program does not exist or permissions are lacking to invoke the program.
Process.Crashed 4 The process crashed some time after starting successfully.
Process.Timedout 5 Waiting for the process to start or stop timed out.
Process.UnknownError 6 Unknown/other error occurred.

Example

import InCore.Foundation 2.5

Application {
    Process {
        program: "tar"
        arguments: [ "czf", "/tmp/logs.tar.gz", "/storage/incore/myapp/logs/" ]
        onCompleted: start();
        onStarted: console.log("Started log file export")
        onFinished: {
            if (error === Process.NoError && exitCode === 0)
            {
                console.log("All log files have been exported successfully")
            }
            else if (error !== Process.NoError)
            {
                console.log("Export failed due to process error", errorString)
            }
            else
            {
                console.log("Export failed with exit code", exitCode)
            }
        }
    }
}