PPipeChannel Class Reference

#include <pipechan.h>

Inheritance diagram for PPipeChannel:

List of all members.

Construction
enum	OpenMode { ReadOnly, WriteOnly, ReadWrite, ReadWriteStd }
	Channel mode for the pipe to the sub-process. More...
	PPipeChannel ()
	PPipeChannel (const PString &subProgram, OpenMode mode=ReadWrite, PBoolean searchPath=PTrue, PBoolean stderrSeparate=PFalse)
	PPipeChannel (const PString &subProgram, const PStringArray &argumentList, OpenMode mode=ReadWrite, PBoolean searchPath=PTrue, PBoolean stderrSeparate=PFalse)
	PPipeChannel (const PString &subProgram, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=PTrue, PBoolean stderrSeparate=PFalse)
	PPipeChannel (const PString &subProgram, const PStringArray &argumentList, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=PTrue, PBoolean stderrSeparate=PFalse)
	~PPipeChannel ()
	Close the pipe channel, killing the sub-process.
New member functions
PBoolean	Open (const PString &subProgram, OpenMode mode=ReadWrite, PBoolean searchPath=PTrue, PBoolean stderrSeparate=PFalse)
PBoolean	Open (const PString &subProgram, const PStringArray &argumentList, OpenMode mode=ReadWrite, PBoolean searchPath=PTrue, PBoolean stderrSeparate=PFalse)
PBoolean	Open (const PString &subProgram, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=PTrue, PBoolean stderrSeparate=PFalse)
PBoolean	Open (const PString &subProgram, const PStringArray &argumentList, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=PTrue, PBoolean stderrSeparate=PFalse)
const PFilePath &	GetSubProgram () const
PBoolean	Execute ()
PBoolean	IsRunning () const
int	GetReturnCode () const
int	WaitForTermination ()
int	WaitForTermination (const PTimeInterval &timeout)
PBoolean	Kill (int signal=9)
PBoolean	ReadStandardError (PString &errors, PBoolean wait=PFalse)
static PBoolean	CanReadAndWrite ()
Public Member Functions
Overrides from class PObject
Comparison	Compare (const PObject &obj) const
Overrides from class PChannel
virtual PString	GetName () const
virtual PBoolean	Read (void *buf, PINDEX len)
virtual PBoolean	Write (const void *buf, PINDEX len)
virtual PBoolean	Close ()
Protected Attributes
PFilePath	subProgName
	The fully qualified path name for the sub-program executable.
int	toChildPipe [2]
int	fromChildPipe [2]
int	stderrChildPipe [2]
int	childPid
int	retVal

---

Member Enumeration Documentation

enum PPipeChannel::OpenMode

Channel mode for the pipe to the sub-process.

Enumerator:

ReadOnly	Pipe is only from the sub-process to the current process.
WriteOnly	Pipe is only from the current process to the sub-process.
ReadWrite	Pipe is bidirectional between current and sub-processes.
ReadWriteStd	Pipe is bidirectional between current and sub-processes but sub-processes stdout and stderr goes to current processes stdout and stderr

---

Constructor & Destructor Documentation

PPipeChannel::PPipeChannel

(

)

Create a new pipe channel.

PPipeChannel::PPipeChannel	(	const PString &	subProgram,
		OpenMode	mode = ReadWrite,
		PBoolean	searchPath = PTrue,
		PBoolean	stderrSeparate = PFalse
	)

Create a new pipe channel. This executes the subProgram and transfers data from its stdin/stdout/stderr.

See the Open()# function for details of various parameters.

Parameters:

subProgram	Sub program name or command line.
mode	Mode for the pipe channel.
searchPath	Flag for system PATH to be searched.
stderrSeparate	Standard error is on separate pipe

PPipeChannel::PPipeChannel	(	const PString &	subProgram,
		const PStringArray &	argumentList,
		OpenMode	mode = ReadWrite,
		PBoolean	searchPath = PTrue,
		PBoolean	stderrSeparate = PFalse
	)

Create a new pipe channel. This executes the subProgram and transfers data from its stdin/stdout/stderr.

See the Open()# function for details of various parameters.

Parameters:

subProgram	Sub program name or command line.
argumentList	Array of arguments to sub-program.
mode	Mode for the pipe channel.
searchPath	Flag for system PATH to be searched.
stderrSeparate	Standard error is on separate pipe

PPipeChannel::PPipeChannel	(	const PString &	subProgram,
		const PStringToString &	environment,
		OpenMode	mode = ReadWrite,
		PBoolean	searchPath = PTrue,
		PBoolean	stderrSeparate = PFalse
	)

Create a new pipe channel. This executes the subProgram and transfers data from its stdin/stdout/stderr.

See the Open()# function for details of various parameters.

Parameters:

subProgram	Sub program name or command line.
environment	Array of arguments to sub-program.
mode	Mode for the pipe channel.
searchPath	Flag for system PATH to be searched.
stderrSeparate	Standard error is on separate pipe

PPipeChannel::PPipeChannel	(	const PString &	subProgram,
		const PStringArray &	argumentList,
		const PStringToString &	environment,
		OpenMode	mode = ReadWrite,
		PBoolean	searchPath = PTrue,
		PBoolean	stderrSeparate = PFalse
	)

Create a new pipe channel. This executes the subProgram and transfers data from its stdin/stdout/stderr.

See the Open()# function for details of various parameters.

Parameters:

subProgram	Sub program name or command line.
argumentList	Array of arguments to sub-program.
environment	Array of arguments to sub-program.
mode	Mode for the pipe channel.
searchPath	Flag for system PATH to be searched.
stderrSeparate	Standard error is on separate pipe

PPipeChannel::~PPipeChannel

(

)

Close the pipe channel, killing the sub-process.

---

Member Function Documentation

static PBoolean PPipeChannel::CanReadAndWrite

(

)

[static]

Determine if the platform can support simultaneous read and writes from the PPipeChannel (eg MSDOS returns PFalse, Unix returns PTrue).

Returns:

PTrue if platform supports concurrent multi-processing.

virtual PBoolean PPipeChannel::Close

(

)

[virtual]

Close the channel. This will kill the sub-program's process (on platforms where that is relevent).

For WriteOnly# or ReadWrite# mode pipe channels on platforms that do no support concurrent multi-processing and have not yet called the Execute()# function this will run the sub-program.

Reimplemented from PChannel.

Comparison PPipeChannel::Compare

(

const PObject &

obj

)

const [virtual]

Determine if the two objects refer to the same pipe channel. This actually compares the sub-program names that are passed into the constructor.

Returns:

Comparison value of the sub-program strings.

Parameters:

obj	Another pipe channel to compare against.

Reimplemented from PChannel.

PBoolean PPipeChannel::Execute

(

)

Start execution of sub-program for platforms that do not support multi-processing, this will actually run the sub-program passing all data written to the PPipeChannel.

For platforms that do support concurrent multi-processing this will close the pipe from the current process to the sub-process.

As the sub-program is run immediately and concurrently, this will just give an end of file to the stdin of the remote process. This is often necessary.

Returns:

PTrue if execute was successful.

virtual PString PPipeChannel::GetName

(

)

const [virtual]

Get the name of the channel.

Returns:

string for the sub-program that is run.

Reimplemented from PChannel.

int PPipeChannel::GetReturnCode

(

)

const

Get the return code from the most recent Close;

Returns:

Return code from the closing process, if the process is still running then -2 is returned. If the process never started due to some error then -1 is returned.

const PFilePath& PPipeChannel::GetSubProgram

(

)

const

Get the full file path for the sub-programs executable file.

Returns:

file path name for sub-program.

PBoolean PPipeChannel::IsRunning

(

)

const

Determine if the program associated with the PPipeChannel is still executing. This is useful for determining the status of PPipeChannels which take a long time to execute on operating systems which support concurrent multi-processing.

Returns:

PTrue if the program associated with the PPipeChannel is still running

PBoolean PPipeChannel::Kill

(

int

signal = 9

)

This function will terminate the sub-program using the signal code specified.

Returns:

PTrue if the process received the signal. Note that this does not mean that the process has actually terminated.

Parameters:

signal

Signal code to be sent to process.

PBoolean PPipeChannel::Open	(	const PString &	subProgram,
		const PStringArray &	argumentList,
		const PStringToString &	environment,
		OpenMode	mode = ReadWrite,
		PBoolean	searchPath = PTrue,
		PBoolean	stderrSeparate = PFalse
	)

Open a new pipe channel allowing the subProgram to be executed and data transferred from its stdin/stdout/stderr.

If the mode is ReadOnly# then the stdout# of the sub-program is supplied via the Read()# calls of the PPipeChannel. The sub-programs input is set to the platforms null device (eg /dev/nul).

If mode is WriteOnly# then Write()# calls of the PPipeChannel are suppied to the sub-programs stdin# and its stdout# is sent to the null device.

If mode is ReadWrite# then both read and write actions can occur.

The subProgram# parameter may contain just the path of the program to be run or a program name and space separated arguments, similar to that provided to the platforms command processing shell. Which use of this parameter is determiend by whether arguments are passed via the argumentPointers# or argumentList# parameters.

The searchPath# parameter indicates that the system PATH for executables should be searched for the sub-program. If PFalse then only the explicit or implicit path contained in the subProgram# parameter is searched for the executable.

The stderrSeparate# parameter indicates that the standard error stream is not included in line with the standard output stream. In this case, data in this stream must be read using the ReadStandardError()# function.

The environment# parameter is a null terminated sequence of null terminated strings of the form name=value. If NULL is passed then the same invironment as calling process uses is passed to the child process.

Parameters:

subProgram	Sub program name or command line.
argumentList	Array of arguments to sub-program.
environment	Array of arguments to sub-program.
mode	Mode for the pipe channel.
searchPath	Flag for system PATH to be searched.
stderrSeparate	Standard error is on separate pipe

PBoolean PPipeChannel::Open	(	const PString &	subProgram,
		const PStringToString &	environment,
		OpenMode	mode = ReadWrite,
		PBoolean	searchPath = PTrue,
		PBoolean	stderrSeparate = PFalse
	)

Open a channel.

Parameters:

subProgram	Sub program name or command line.
environment	Array of arguments to sub-program.
mode	Mode for the pipe channel.
searchPath	Flag for system PATH to be searched.
stderrSeparate	Standard error is on separate pipe

PBoolean PPipeChannel::Open	(	const PString &	subProgram,
		const PStringArray &	argumentList,
		OpenMode	mode = ReadWrite,
		PBoolean	searchPath = PTrue,
		PBoolean	stderrSeparate = PFalse
	)

Open a channel.

Parameters:

subProgram	Sub program name or command line.
argumentList	Array of arguments to sub-program.
mode	Mode for the pipe channel.
searchPath	Flag for system PATH to be searched.
stderrSeparate	Standard error is on separate pipe

PBoolean PPipeChannel::Open	(	const PString &	subProgram,
		OpenMode	mode = ReadWrite,
		PBoolean	searchPath = PTrue,
		PBoolean	stderrSeparate = PFalse
	)

Open a channel.

Parameters:

subProgram	Sub program name or command line.
mode	Mode for the pipe channel.
searchPath	Flag for system PATH to be searched.
stderrSeparate	Standard error is on separate pipe

virtual PBoolean PPipeChannel::Read	(	void *	buf,
		PINDEX	len
	)			[virtual]

Low level read from the channel. This function may block until the requested number of characters were read or the read timeout was reached. The GetLastReadCount() function returns the actual number of bytes read.

If there are no more characters available as the sub-program has stopped then the number of characters available is returned. This is similar to end of file for the PFile channel.

The GetErrorCode() function should be consulted after Read() returns PFalse to determine what caused the failure.

Returns:

PTrue indicates that at least one character was read from the channel. PFalse means no bytes were read due to timeout or some other I/O error.

Parameters:

buf	Pointer to a block of memory to receive the read bytes.
len	Maximum number of bytes to read into the buffer.

Reimplemented from PChannel.

PBoolean PPipeChannel::ReadStandardError	(	PString &	errors,
		PBoolean	wait = PFalse
	)

Read all available data on the standard error stream of the sub-process. If the wait# parameter is PFalse then only the text currently available is returned. If PTrue then the function blocks as long as necessary to get some number of bytes.

Returns:

PTrue indicates that at least one character was read from stderr. PFalse means no bytes were read due to timeout or some other I/O error.

Parameters:

errors	String to receive standard error text.
wait	Flag to indicate if function should block

int PPipeChannel::WaitForTermination

(

const PTimeInterval &

timeout

)

This function will block and wait for the sub-program to terminate. It will wait only for the specified amount of time.

Returns:

Return code from the closing process, -1 if timed out.

Parameters:

timeout

Amount of time to wait for process.

int PPipeChannel::WaitForTermination

(

)

This function will block and wait for the sub-program to terminate.

Returns:

Return code from the closing process

virtual PBoolean PPipeChannel::Write	(	const void *	buf,
		PINDEX	len
	)			[virtual]

Low level write to the channel. This function will block until the requested number of characters are written or the write timeout is reached. The GetLastWriteCount() function returns the actual number of bytes written.

If the sub-program has completed its run then this function will fail returning PFalse.

The GetErrorCode() function should be consulted after Write() returns PFalse to determine what caused the failure.

Returns:

PTrue if at least len bytes were written to the channel.

Parameters:

buf	Pointer to a block of memory to write.
len	Number of bytes to write.

Reimplemented from PChannel.

---

Member Data Documentation

int PPipeChannel::childPid [protected]

int PPipeChannel::fromChildPipe[2] [protected]

int PPipeChannel::retVal [protected]

int PPipeChannel::stderrChildPipe[2] [protected]

PFilePath PPipeChannel::subProgName [protected]

The fully qualified path name for the sub-program executable.

int PPipeChannel::toChildPipe[2] [protected]

---

The documentation for this class was generated from the following file:

• pipechan.h

---