ExternalProcess Class Reference

A wrapper around QProcess to conveniently start an external program and forward its outputs. More...

#include <OpenMS/SYSTEM/ExternalProcess.h>

Inheritance diagram for ExternalProcess:

Collaboration diagram for ExternalProcess:

Public Types
enum	RETURNSTATE { SUCCESS, NONZERO_EXIT, CRASH, FAILED_TO_START }
	result of calling an external executable More...

Public Member Functions
	ExternalProcess ()
	default Ctor; callbacks for stdout/stderr are empty More...
	ExternalProcess (std::function< void(const String &)> callbackStdOut, std::function< void(const String &)> callbackStdErr)
	set the callback functions to process stdout and stderr output when the external process generates it More...
	~ExternalProcess ()
	D'tor. More...
void	setCallbacks (std::function< void(const String &)> callbackStdOut, std::function< void(const String &)> callbackStdErr)
	re-wire the callbacks used using run() More...
RETURNSTATE	run (const QString &exe, const QStringList &args, const QString &working_dir, const bool verbose, String &error_msg)
	Runs a program and calls the callback functions from time to time if output from the external program is available. More...
ExternalProcess::RETURNSTATE	run (const QString &exe, const QStringList &args, const QString &working_dir, const bool verbose)
	Same as other overload, just without a returned error message. More...

Private Slots
void	processStdOut_ ()
void	processStdErr_ ()

Private Attributes
QProcess *	qp_
	pointer to avoid including the QProcess header here (it's huge) More...
std::function< void(const String &)>	callbackStdOut_
std::function< void(const String &)>	callbackStdErr_

Detailed Description

A wrapper around QProcess to conveniently start an external program and forward its outputs.

Use the custom Ctor to provide callback functions for stdout/stderr output or set them via setCallbacks().

Running an external program blocks the caller, so do not use this in a main GUI thread (unless you have some other means to tell the user that no interaction is possible at the moment).

@Note If you want QMessageboxes to be shown if something went wrong, use ExternalProcessMBox as a convenient wrapper instead.

Member Enumeration Documentation

RETURNSTATE

enum RETURNSTATE

strong

result of calling an external executable

Enumerator
SUCCESS	everything went smoothly (exit-code = 0)
NONZERO_EXIT
CRASH	finished, but returned with an exit-code other than 0 ran, but crashed (segfault etc)
FAILED_TO_START	executable not found or not enough access rights for user

Constructor & Destructor Documentation

ExternalProcess() [1/2]

ExternalProcess

(

)

default Ctor; callbacks for stdout/stderr are empty

ExternalProcess() [2/2]

ExternalProcess	(	std::function< void(const String &)>	callbackStdOut,
		std::function< void(const String &)>	callbackStdErr
	)

set the callback functions to process stdout and stderr output when the external process generates it

~ExternalProcess()

~ExternalProcess

(

)

D'tor.

Member Function Documentation

processStdErr_

void processStdErr_ ( )

privateslot

processStdOut_

void processStdOut_ ( )

privateslot

run() [1/2]

ExternalProcess::RETURNSTATE run	(	const QString &	exe,
		const QStringList &	args,
		const QString &	working_dir,
		const bool	verbose
	)

Same as other overload, just without a returned error message.

run() [2/2]

RETURNSTATE run	(	const QString &	exe,
		const QStringList &	args,
		const QString &	working_dir,
		const bool	verbose,
		String &	error_msg
	)

Runs a program and calls the callback functions from time to time if output from the external program is available.

Parameters

	exe	The program to call (can contain spaces in path, no problem)
	args	A list of extra arguments (can be empty)
	verbose	Report the call command and errors via the callbacks (default: false)
	working_dir	Execute the external process in the given directory (relevant when relative input/output paths are given). Leave empty to use the current working directory.
[out]	error_string	Message to display to the user if something went wrong (if return != SUCCESS)

Returns

Did the external program succeed (SUCCESS) or did something go wrong?

setCallbacks()

void setCallbacks	(	std::function< void(const String &)>	callbackStdOut,
		std::function< void(const String &)>	callbackStdErr
	)

re-wire the callbacks used using run()

Member Data Documentation

callbackStdErr_

std::function<void(const String&)> callbackStdErr_

private

callbackStdOut_

std::function<void(const String&)> callbackStdOut_

private

qp_

QProcess* qp_

private

pointer to avoid including the QProcess header here (it's huge)