stdio_redirecter Class Reference

Redirects I/O for a newly launched application. More...

#include <redirecter.h>

Inheritance diagram for stdio_redirecter:

[legend]Collaboration diagram for stdio_redirecter:


Public Types
enum	outcomes { OKAY = common::OKAY, NOT_FOUND = common::NOT_FOUND, NONE_READY = common::NONE_READY, PARTIAL = common::PARTIAL, ACCESS_DENIED = common::ACCESS_DENIED }
Public Member Functions
	stdio_redirecter (const istring &command, const istring &parameters)
	controls the I/O for a program started with "command" and "parameters".
	stdio_redirecter ()
	creates a blank redirecter which should be started up with reset().
	~stdio_redirecter ()
	shuts down the program that was launched, if it's still running.
outcome	reset (const istring &command, const istring &parameters)
	shuts down the active program and starts with new parameters.
	IMPLEMENT_CLASS_NAME ("stdio_redirecter")
outcome	health () const
	if the object constructed successfully, this returns OKAY.
bool	running ()
	returns true if the application is still running.
int	exit_value () const
	returns the exit value from the app after it was launched.
int	process_id () const
	the process id of the launched application.
void	zap_program ()
	attempts to force a shutdown of the launched application.
outcome	read (byte_array &received)
	attempts to read bytes from the program's standard output.
outcome	write (const byte_array &to_write, int &written)
	writes the bytes in "to_write" into the program's standard input.
outcome	write (const istring &to_write, int &written)
	sends a string "to_write" to the launched program's standard input.
outcome	read_stderr (byte_array &received)
	reads from the program's standard error stream similarly to read().
void	close_input ()
	shuts down the standard input to the program.
void	std_thread_action (bool is_stdout)
	invoked by our threads when data becomes available.

Detailed Description

Redirects I/O for a newly launched application.

Definition at line 27 of file redirecter.h.

Member Enumeration Documentation

enum stdio_redirecter::outcomes

Enumerator:

OKAY
NOT_FOUND	the file to launch was not found.
NONE_READY	there was no data available.
PARTIAL	only some of the bytes could be stored.
ACCESS_DENIED	the OS told us we could not.

Definition at line 49 of file redirecter.h.

Constructor & Destructor Documentation

stdio_redirecter::stdio_redirecter	(	const istring &	command,
		const istring &	parameters
	)

controls the I/O for a program started with "command" and "parameters".

this creates an io redirecter that will trap the inputs and outputs of a program called "command" that is launched with the "parameters". the program can be communicated with via the read and write methods below.

Definition at line 96 of file redirecter.cpp.

References OKAY.

stdio_redirecter::stdio_redirecter ( )

creates a blank redirecter which should be started up with reset().

Definition at line 76 of file redirecter.cpp.

stdio_redirecter::~stdio_redirecter ( )

shuts down the program that was launched, if it's still running.

Definition at line 121 of file redirecter.cpp.

References WHACK(), and zap_program().

Member Function Documentation

outcome stdio_redirecter::reset	(	const istring &	command,
		const istring &	parameters
	)

shuts down the active program and starts with new parameters.

Definition at line 135 of file redirecter.cpp.

References OKAY, and zap_program().

stdio_redirecter::IMPLEMENT_CLASS_NAME ( "stdio_redirecter" )

outcome stdio_redirecter::health ( ) const [inline]

if the object constructed successfully, this returns OKAY.

otherwise an error occurred during the pipe creation or process fork.

Definition at line 57 of file redirecter.h.

Referenced by main(), and smtp_client::send_email().

bool stdio_redirecter::running ( )

returns true if the application is still running.

if it exited on its own, then this will return false.

Definition at line 302 of file redirecter.cpp.

References exit_value().

Referenced by smtp_client::send_email().

int stdio_redirecter::exit_value ( ) const [inline]

returns the exit value from the app after it was launched.

this is only valid if the launch succeeded, the app ran, and now the running() method is returning false because the application exited.

Definition at line 65 of file redirecter.h.

Referenced by running(), and smtp_client::send_email().

int stdio_redirecter::process_id ( ) const [inline]

the process id of the launched application.

this is only valid if the app is still running.

Definition at line 69 of file redirecter.h.

void stdio_redirecter::zap_program ( )

attempts to force a shutdown of the launched application.

this also closes out all of our pipes and handles.

Definition at line 353 of file redirecter.cpp.

References ini_configurator::APPLICATION_DIRECTORY, ithread::cancel(), close, close_input(), ini_configurator::delete_entry(), FUNCDEF, LOG, NIL, portable::process_id(), PROCESS_SECTION, REDIRECTER_INI, configurator::RETURN_ONLY, and ithread::stop().

Referenced by reset(), and ~stdio_redirecter().

outcome stdio_redirecter::read ( byte_array & received )

attempts to read bytes from the program's standard output.

if any bytes were found, OKAY is returned and the bytes are stored in "received".

Definition at line 413 of file redirecter.cpp.

References array< contents >::length(), NONE_READY, common::OKAY, OKAY, and array< contents >::reset().

Referenced by std_thread_action().

outcome stdio_redirecter::write	(	const byte_array &	to_write,
		int &	written
	)

writes the bytes in "to_write" into the program's standard input.

OKAY is returned if all were successfully written. the number of bytes that were actually sent to the program is put in "written". if only a portion of the bytes could be written, then PARTIAL is returned.

Definition at line 431 of file redirecter.cpp.

References ACCESS_DENIED, FUNCDEF, array< contents >::length(), NIL, array< contents >::observe(), and OKAY.

Referenced by main(), smtp_client::send_email(), and write().