PTLib  Version 2.10.10
PPipeChannel Class Reference

#include <pipechan.h>

Inheritance diagram for PPipeChannel:
PChannel PObject

Public Member Functions

Overrides from class PObject
Comparison Compare (const PObject &obj) const
 Determine if the two objects refer to the same pipe channel. More...
 
Overrides from class PChannel
virtual PString GetName () const
 Get the name of the channel. More...
 
virtual PBoolean Read (void *buf, PINDEX len)
 Low level read from the channel. More...
 
virtual PBoolean Write (const void *buf, PINDEX len)
 Low level write to the channel. More...
 
virtual PBoolean Close ()
 Close the channel. More...
 
- Public Member Functions inherited from PChannel
PBoolean SetErrorValues (Errors errorCode, int osError, ErrorGroup group=LastGeneralError)
 Set error values to those specified. More...
 
 PChannel ()
 Create the channel. More...
 
 ~PChannel ()
 Close down the channel. More...
 
virtual PINDEX HashFunction () const
 Calculate a hash value for use in sets and dictionaries. More...
 
virtual PBoolean IsOpen () const
 Determine if the channel is currently open. More...
 
int GetHandle () const
 Get the integer operating system handle for the channel. More...
 
virtual PChannelGetBaseReadChannel () const
 Get the base channel of channel indirection using PIndirectChannel. More...
 
virtual PChannelGetBaseWriteChannel () const
 Get the base channel of channel indirection using PIndirectChannel. More...
 
void SetReadTimeout (const PTimeInterval &time)
 Set the timeout for read operations. More...
 
PTimeInterval GetReadTimeout () const
 Get the timeout for read operations. More...
 
virtual PINDEX GetLastReadCount () const
 Get the number of bytes read by the last Read() call. More...
 
virtual int ReadChar ()
 Read a single 8 bit byte from the channel. More...
 
PBoolean ReadBlock (void *buf, PINDEX len)
 Read len bytes into the buffer from the channel. More...
 
PString ReadString (PINDEX len)
 Read len character into a string from the channel. More...
 
virtual PBoolean ReadAsync (void *buf, PINDEX len)
 Begin an asynchronous read from channel. More...
 
virtual void OnReadComplete (void *buf, PINDEX len)
 User callback function for when a ReadAsync() call has completed or timed out. More...
 
void SetWriteTimeout (const PTimeInterval &time)
 Set the timeout for write operations to complete. More...
 
PTimeInterval GetWriteTimeout () const
 Get the timeout for write operations to complete. More...
 
virtual PBoolean Write (const void *buf, PINDEX len, const void *mark)
 Low level write to the channel with marker. More...
 
virtual PINDEX GetLastWriteCount () const
 Get the number of bytes written by the last Write() call. More...
 
PBoolean WriteChar (int c)
 Write a single character to the channel. More...
 
PBoolean WriteString (const PString &str)
 Write a string to the channel. More...
 
virtual PBoolean WriteAsync (const void *buf, PINDEX len)
 Begin an asynchronous write from channel. More...
 
virtual void OnWriteComplete (const void *buf, PINDEX len)
 User callback function for when a WriteAsync() call has completed or timed out. More...
 
virtual PBoolean Shutdown (ShutdownValue option)
 Close one or both of the data streams associated with a channel. More...
 
virtual bool SetLocalEcho (bool localEcho)
 Set local echo mode. More...
 
virtual bool FlowControl (const void *flowData)
 Flow Control information Pass data to the channel for flowControl determination. More...
 
PBoolean SetBufferSize (PINDEX newSize)
 Set the iostream buffer size for reads and writes. More...
 
PBoolean SendCommandString (const PString &command)
 Send a command meta-string. More...
 
void AbortCommandString ()
 Abort a command string that is in progress. More...
 
Errors GetErrorCode (ErrorGroup group=NumErrorGroups) const
 Get normalised error code. More...
 
int GetErrorNumber (ErrorGroup group=NumErrorGroups) const
 Get OS errro code. More...
 
virtual PString GetErrorText (ErrorGroup group=NumErrorGroups) const
 Get error message description. More...
 
virtual PBoolean Read (const VectorOfSlice &slices)
 Low level scattered read from the channel. More...
 
virtual PBoolean Write (const VectorOfSlice &slices)
 Low level scattered write to the channel. More...
 
- Public Member Functions inherited from PObject
virtual ~PObject ()
 
virtual PObjectClone () const
 Create a copy of the class on the heap. More...
 
virtual const char * GetClass (unsigned ancestor=0) const
 Get the current dynamic type of the object instance. More...
 
PBoolean IsClass (const char *cls) const
 
virtual PBoolean InternalIsDescendant (const char *clsName) const
 Determine if the dynamic type of the current instance is a descendent of the specified class. More...
 
virtual Comparison CompareObjectMemoryDirect (const PObject &obj) const
 Determine the byte wise comparison of two objects. More...
 
bool operator== (const PObject &obj) const
 Compare the two objects. More...
 
bool operator!= (const PObject &obj) const
 Compare the two objects. More...
 
bool operator< (const PObject &obj) const
 Compare the two objects. More...
 
bool operator> (const PObject &obj) const
 Compare the two objects. More...
 
bool operator<= (const PObject &obj) const
 Compare the two objects. More...
 
bool operator>= (const PObject &obj) const
 Compare the two objects. More...
 
virtual void PrintOn (ostream &strm) const
 Output the contents of the object to the stream. More...
 
virtual void ReadFrom (istream &strm)
 Input the contents of the object from the stream. More...
 

Protected Attributes

PFilePath subProgName
 The fully qualified path name for the sub-program executable. More...
 
int toChildPipe [2]
 
int fromChildPipe [2]
 
int stderrChildPipe [2]
 
int childPid
 
int retVal
 
- Protected Attributes inherited from PChannel
int os_handle
 The operating system file handle return by standard open() function. More...
 
Errors lastErrorCode [NumErrorGroups+1]
 The platform independant error code. More...
 
int lastErrorNumber [NumErrorGroups+1]
 The operating system error number (eg as returned by errno). More...
 
PINDEX lastReadCount
 Number of byte last read by the Read() function. More...
 
PINDEX lastWriteCount
 Number of byte last written by the Write() function. More...
 
PTimeInterval readTimeout
 Timeout for read operations. More...
 
PTimeInterval writeTimeout
 Timeout for write operations. More...
 
PString channelName
 
PMutex px_threadMutex
 
PXBlockType px_lastBlockType
 
PThreadpx_readThread
 
PThreadpx_writeThread
 
PMutex px_writeMutex
 
PThreadpx_selectThread [3]
 
PMutex px_selectMutex [3]
 

Construction

enum  OpenMode { ReadOnly, WriteOnly, ReadWrite, ReadWriteStd }
 Channel mode for the pipe to the sub-process. More...
 
 PPipeChannel ()
 Create a new pipe channel. More...
 
 PPipeChannel (const PString &subProgram, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false)
 Create a new pipe channel. More...
 
 PPipeChannel (const PString &subProgram, const PStringArray &argumentList, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false)
 Create a new pipe channel. More...
 
 PPipeChannel (const PString &subProgram, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false)
 Create a new pipe channel. More...
 
 PPipeChannel (const PString &subProgram, const PStringArray &argumentList, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false)
 Create a new pipe channel. More...
 
 ~PPipeChannel ()
 Close the pipe channel, killing the sub-process. More...
 

New member functions

PBoolean Open (const PString &subProgram, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false)
 Open a channel. More...
 
PBoolean Open (const PString &subProgram, const PStringArray &argumentList, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false)
 Open a channel. More...
 
PBoolean Open (const PString &subProgram, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false)
 Open a channel. More...
 
PBoolean Open (const PString &subProgram, const PStringArray &argumentList, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false)
 Open a new pipe channel allowing the subProgram to be executed and data transferred from its stdin/stdout/stderr. More...
 
const PFilePathGetSubProgram () const
 Get the full file path for the sub-programs executable file. More...
 
PBoolean 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. More...
 
PBoolean IsRunning () const
 Determine if the program associated with the PPipeChannel is still executing. More...
 
int GetReturnCode () const
 Get the return code from the most recent Close;. More...
 
int WaitForTermination ()
 This function will block and wait for the sub-program to terminate. More...
 
int WaitForTermination (const PTimeInterval &timeout)
 This function will block and wait for the sub-program to terminate. More...
 
PBoolean Kill (int signal=9)
 This function will terminate the sub-program using the signal code specified. More...
 
PBoolean ReadStandardError (PString &errors, PBoolean wait=false)
 Read all available data on the standard error stream of the sub-process. More...
 
static PBoolean CanReadAndWrite ()
 Determine if the platform can support simultaneous read and writes from the PPipeChannel (eg MSDOS returns false, Unix returns true). More...
 

Additional Inherited Members

- Public Types inherited from PChannel
enum  PXBlockType { PXReadBlock, PXWriteBlock, PXAcceptBlock, PXConnectBlock }
 
enum  ShutdownValue { ShutdownRead = 0, ShutdownWrite = 1, ShutdownReadAndWrite = 2 }
 
enum  Errors {
  NoError, NotFound, FileExists, DiskFull,
  AccessDenied, DeviceInUse, BadParameter, NoMemory,
  NotOpen, Timeout, Interrupted, BufferTooSmall,
  Miscellaneous, ProtocolFailure, NumNormalisedErrors
}
 Normalised error codes. More...
 
enum  ErrorGroup { LastReadError, LastWriteError, LastGeneralError, NumErrorGroups }
 Error groups. More...
 
typedef std::vector< SliceVectorOfSlice
 
- Public Types inherited from PObject
enum  Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
 Result of the comparison operation performed by the Compare() function. More...
 
- Static Public Member Functions inherited from PChannel
static PBoolean ConvertOSError (int libcReturnValue, Errors &lastError, int &osError)
 Convert an operating system error into platform independent error. More...
 
static PString GetErrorText (Errors lastError, int osError=0)
 Get error message description. More...
 
- Static Public Member Functions inherited from PObject
static const char * Class ()
 Get the name of the class as a C string. More...
 
static Comparison InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
 Internal function caled from CompareObjectMemoryDirect() More...
 
- Protected Member Functions inherited from PChannel
 PChannel (const PChannel &)
 
PChanneloperator= (const PChannel &)
 
virtual PBoolean ConvertOSError (int libcReturnValue, ErrorGroup group=LastGeneralError)
 Convert an operating system error into platform independent error. More...
 
int ReadCharWithTimeout (PTimeInterval &timeout)
 Read a character with specified timeout. More...
 
PBoolean ReceiveCommandString (int nextChar, const PString &reply, PINDEX &pos, PINDEX start)
 
PBoolean PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout)
 
int PXClose ()
 
- Protected Member Functions inherited from PObject
 PObject ()
 Constructor for PObject, made protected so cannot ever create one on its own. More...
 

Member Enumeration Documentation

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 = true,
PBoolean  stderrSeparate = false 
)

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
subProgramSub program name or command line.
modeMode for the pipe channel.
searchPathFlag for system PATH to be searched.
stderrSeparateStandard error is on separate pipe
PPipeChannel::PPipeChannel ( const PString subProgram,
const PStringArray argumentList,
OpenMode  mode = ReadWrite,
PBoolean  searchPath = true,
PBoolean  stderrSeparate = false 
)

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
subProgramSub program name or command line.
argumentListArray of arguments to sub-program.
modeMode for the pipe channel.
searchPathFlag for system PATH to be searched.
stderrSeparateStandard error is on separate pipe
PPipeChannel::PPipeChannel ( const PString subProgram,
const PStringToString environment,
OpenMode  mode = ReadWrite,
PBoolean  searchPath = true,
PBoolean  stderrSeparate = false 
)

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
subProgramSub program name or command line.
environmentArray of arguments to sub-program.
modeMode for the pipe channel.
searchPathFlag for system PATH to be searched.
stderrSeparateStandard error is on separate pipe
PPipeChannel::PPipeChannel ( const PString subProgram,
const PStringArray argumentList,
const PStringToString environment,
OpenMode  mode = ReadWrite,
PBoolean  searchPath = true,
PBoolean  stderrSeparate = false 
)

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
subProgramSub program name or command line.
argumentListArray of arguments to sub-program.
environmentArray of arguments to sub-program.
modeMode for the pipe channel.
searchPathFlag for system PATH to be searched.
stderrSeparateStandard 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 false, Unix returns true).

Returns
true 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
objAnother 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
true 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
true 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
true if the process received the signal. Note that this does not mean that the process has actually terminated.
Parameters
signalSignal code to be sent to process.
PBoolean PPipeChannel::Open ( const PString subProgram,
OpenMode  mode = ReadWrite,
PBoolean  searchPath = true,
PBoolean  stderrSeparate = false 
)

Open a channel.

Parameters
subProgramSub program name or command line.
modeMode for the pipe channel.
searchPathFlag for system PATH to be searched.
stderrSeparateStandard error is on separate pipe
PBoolean PPipeChannel::Open ( const PString subProgram,
const PStringArray argumentList,
OpenMode  mode = ReadWrite,
PBoolean  searchPath = true,
PBoolean  stderrSeparate = false 
)

Open a channel.

Parameters
subProgramSub program name or command line.
argumentListArray of arguments to sub-program.
modeMode for the pipe channel.
searchPathFlag for system PATH to be searched.
stderrSeparateStandard error is on separate pipe
PBoolean PPipeChannel::Open ( const PString subProgram,
const PStringToString environment,
OpenMode  mode = ReadWrite,
PBoolean  searchPath = true,
PBoolean  stderrSeparate = false 
)

Open a channel.

Parameters
subProgramSub program name or command line.
environmentArray of arguments to sub-program.
modeMode for the pipe channel.
searchPathFlag for system PATH to be searched.
stderrSeparateStandard error is on separate pipe
PBoolean PPipeChannel::Open ( const PString subProgram,
const PStringArray argumentList,
const PStringToString environment,
OpenMode  mode = ReadWrite,
PBoolean  searchPath = true,
PBoolean  stderrSeparate = false 
)

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 false 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
subProgramSub program name or command line.
argumentListArray of arguments to sub-program.
environmentArray of arguments to sub-program.
modeMode for the pipe channel.
searchPathFlag for system PATH to be searched.
stderrSeparateStandard 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 false to determine what caused the failure.

Returns
true indicates that at least one character was read from the channel. false means no bytes were read due to timeout or some other I/O error.
Parameters
bufPointer to a block of memory to receive the read bytes.
lenMaximum number of bytes to read into the buffer.

Reimplemented from PChannel.

PBoolean PPipeChannel::ReadStandardError ( PString errors,
PBoolean  wait = false 
)

Read all available data on the standard error stream of the sub-process.

If the wait parameter is false then only the text currently available is returned. If true then the function blocks as long as necessary to get some number of bytes.

Returns
true indicates that at least one character was read from stderr. false means no bytes were read due to timeout or some other I/O error.
Parameters
errorsString to receive standard error text.
waitFlag to indicate if function should block
int PPipeChannel::WaitForTermination ( )

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

Returns
Return code from the closing process
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
timeoutAmount of time to wait for 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 false.

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

Returns
true if at least len bytes were written to the channel.
Parameters
bufPointer to a block of memory to write.
lenNumber 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: