PTLib
Version 2.10.4
|
#include <pipechan.h>
Public Member Functions | |
Overrides from class PObject | |
Comparison | Compare (const PObject &obj) const |
Determine if the two objects refer to the same pipe channel. | |
Overrides from class PChannel | |
virtual PString | GetName () const |
Get the name of the channel. | |
virtual PBoolean | Read (void *buf, PINDEX len) |
Low level read from the channel. | |
virtual PBoolean | Write (const void *buf, PINDEX len) |
Low level write to the channel. | |
virtual PBoolean | Close () |
Close the channel. | |
![]() | |
PBoolean | SetErrorValues (Errors errorCode, int osError, ErrorGroup group=LastGeneralError) |
Set error values to those specified. | |
PChannel () | |
Create the channel. | |
~PChannel () | |
Close down the channel. | |
virtual PINDEX | HashFunction () const |
Calculate a hash value for use in sets and dictionaries. | |
virtual PBoolean | IsOpen () const |
Determine if the channel is currently open. | |
int | GetHandle () const |
Get the integer operating system handle for the channel. | |
virtual PChannel * | GetBaseReadChannel () const |
Get the base channel of channel indirection using PIndirectChannel. | |
virtual PChannel * | GetBaseWriteChannel () const |
Get the base channel of channel indirection using PIndirectChannel. | |
void | SetReadTimeout (const PTimeInterval &time) |
Set the timeout for read operations. | |
PTimeInterval | GetReadTimeout () const |
Get the timeout for read operations. | |
virtual PINDEX | GetLastReadCount () const |
Get the number of bytes read by the last Read() call. | |
virtual int | ReadChar () |
Read a single 8 bit byte from the channel. | |
PBoolean | ReadBlock (void *buf, PINDEX len) |
Read len bytes into the buffer from the channel. | |
PString | ReadString (PINDEX len) |
Read len character into a string from the channel. | |
virtual PBoolean | ReadAsync (void *buf, PINDEX len) |
Begin an asynchronous read from channel. | |
virtual void | OnReadComplete (void *buf, PINDEX len) |
User callback function for when a ReadAsync() call has completed or timed out. | |
void | SetWriteTimeout (const PTimeInterval &time) |
Set the timeout for write operations to complete. | |
PTimeInterval | GetWriteTimeout () const |
Get the timeout for write operations to complete. | |
virtual PBoolean | Write (const void *buf, PINDEX len, const void *mark) |
Low level write to the channel with marker. | |
virtual PINDEX | GetLastWriteCount () const |
Get the number of bytes written by the last Write() call. | |
PBoolean | WriteChar (int c) |
Write a single character to the channel. | |
PBoolean | WriteString (const PString &str) |
Write a string to the channel. | |
virtual PBoolean | WriteAsync (const void *buf, PINDEX len) |
Begin an asynchronous write from channel. | |
virtual void | OnWriteComplete (const void *buf, PINDEX len) |
User callback function for when a WriteAsync() call has completed or timed out. | |
virtual PBoolean | Shutdown (ShutdownValue option) |
Close one or both of the data streams associated with a channel. | |
virtual bool | SetLocalEcho (bool localEcho) |
Set local echo mode. | |
virtual bool | FlowControl (const void *flowData) |
Flow Control information Pass data to the channel for flowControl determination. | |
PBoolean | SetBufferSize (PINDEX newSize) |
Set the iostream buffer size for reads and writes. | |
PBoolean | SendCommandString (const PString &command) |
Send a command meta-string. | |
void | AbortCommandString () |
Abort a command string that is in progress. | |
Errors | GetErrorCode (ErrorGroup group=NumErrorGroups) const |
Get normalised error code. | |
int | GetErrorNumber (ErrorGroup group=NumErrorGroups) const |
Get OS errro code. | |
virtual PString | GetErrorText (ErrorGroup group=NumErrorGroups) const |
Get error message description. | |
virtual PBoolean | Read (const VectorOfSlice &slices) |
Low level scattered read from the channel. | |
virtual PBoolean | Write (const VectorOfSlice &slices) |
Low level scattered write to the channel. | |
![]() | |
virtual | ~PObject () |
virtual PObject * | Clone () const |
Create a copy of the class on the heap. | |
virtual const char * | GetClass (unsigned ancestor=0) const |
Get the current dynamic type of the object instance. | |
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. | |
virtual Comparison | CompareObjectMemoryDirect (const PObject &obj) const |
Determine the byte wise comparison of two objects. | |
bool | operator== (const PObject &obj) const |
Compare the two objects. | |
bool | operator!= (const PObject &obj) const |
Compare the two objects. | |
bool | operator< (const PObject &obj) const |
Compare the two objects. | |
bool | operator> (const PObject &obj) const |
Compare the two objects. | |
bool | operator<= (const PObject &obj) const |
Compare the two objects. | |
bool | operator>= (const PObject &obj) const |
Compare the two objects. | |
virtual void | PrintOn (ostream &strm) const |
Output the contents of the object to the stream. | |
virtual void | ReadFrom (istream &strm) |
Input the contents of the object from the stream. |
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 |
![]() | |
int | os_handle |
The operating system file handle return by standard open() function. | |
Errors | lastErrorCode [NumErrorGroups+1] |
The platform independant error code. | |
int | lastErrorNumber [NumErrorGroups+1] |
The operating system error number (eg as returned by errno). | |
PINDEX | lastReadCount |
Number of byte last read by the Read() function. | |
PINDEX | lastWriteCount |
Number of byte last written by the Write() function. | |
PTimeInterval | readTimeout |
Timeout for read operations. | |
PTimeInterval | writeTimeout |
Timeout for write operations. | |
PString | channelName |
PMutex | px_threadMutex |
PXBlockType | px_lastBlockType |
PThread * | px_readThread |
PThread * | px_writeThread |
PMutex | px_writeMutex |
PThread * | px_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. | |
PPipeChannel (const PString &subProgram, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false) | |
Create a new pipe channel. | |
PPipeChannel (const PString &subProgram, const PStringArray &argumentList, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false) | |
Create a new pipe channel. | |
PPipeChannel (const PString &subProgram, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false) | |
Create a new pipe channel. | |
PPipeChannel (const PString &subProgram, const PStringArray &argumentList, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false) | |
Create a new pipe channel. | |
~PPipeChannel () | |
Close the pipe channel, killing the sub-process. |
New member functions | |
PBoolean | Open (const PString &subProgram, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false) |
Open a channel. | |
PBoolean | Open (const PString &subProgram, const PStringArray &argumentList, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false) |
Open a channel. | |
PBoolean | Open (const PString &subProgram, const PStringToString &environment, OpenMode mode=ReadWrite, PBoolean searchPath=true, PBoolean stderrSeparate=false) |
Open a channel. | |
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. | |
const PFilePath & | GetSubProgram () const |
Get the full file path for the sub-programs executable file. | |
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. | |
PBoolean | IsRunning () const |
Determine if the program associated with the PPipeChannel is still executing. | |
int | GetReturnCode () const |
Get the return code from the most recent Close;. | |
int | WaitForTermination () |
This function will block and wait for the sub-program to terminate. | |
int | WaitForTermination (const PTimeInterval &timeout) |
This function will block and wait for the sub-program to terminate. | |
PBoolean | Kill (int signal=9) |
This function will terminate the sub-program using the signal code specified. | |
PBoolean | ReadStandardError (PString &errors, PBoolean wait=false) |
Read all available data on the standard error stream of the sub-process. | |
static PBoolean | CanReadAndWrite () |
Determine if the platform can support simultaneous read and writes from the PPipeChannel (eg MSDOS returns false, Unix returns true). |
Additional Inherited Members | |
![]() | |
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< Slice > | VectorOfSlice |
![]() | |
static PBoolean | ConvertOSError (int libcReturnValue, Errors &lastError, int &osError) |
Convert an operating system error into platform independent error. | |
static PString | GetErrorText (Errors lastError, int osError=0) |
Get error message description. | |
![]() | |
PChannel (const PChannel &) | |
PChannel & | operator= (const PChannel &) |
virtual PBoolean | ConvertOSError (int libcReturnValue, ErrorGroup group=LastGeneralError) |
Convert an operating system error into platform independent error. | |
int | ReadCharWithTimeout (PTimeInterval &timeout) |
Read a character with specified timeout. | |
PBoolean | ReceiveCommandString (int nextChar, const PString &reply, PINDEX &pos, PINDEX start) |
PBoolean | PXSetIOBlock (PXBlockType type, const PTimeInterval &timeout) |
int | PXClose () |
![]() |
Channel mode for the pipe to the sub-process.
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.
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 = 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.
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 = 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.
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 = 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.
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.
|
static |
Determine if the platform can support simultaneous read and writes from the PPipeChannel (eg MSDOS returns false, Unix returns true).
|
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.
|
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.
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.
|
virtual |
Get the name of the channel.
Reimplemented from PChannel.
int PPipeChannel::GetReturnCode | ( | ) | const |
Get the return code from the most recent Close;.
const PFilePath& PPipeChannel::GetSubProgram | ( | ) | const |
Get the full file path for the sub-programs executable file.
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.
PBoolean PPipeChannel::Kill | ( | int | signal = 9 | ) |
This function will terminate the sub-program using the signal code specified.
signal | Signal code to be sent to process. |
PBoolean PPipeChannel::Open | ( | const PString & | subProgram, |
OpenMode | mode = ReadWrite , |
||
PBoolean | searchPath = true , |
||
PBoolean | stderrSeparate = false |
||
) |
Open a channel.
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 |
PBoolean PPipeChannel::Open | ( | const PString & | subProgram, |
const PStringArray & | argumentList, | ||
OpenMode | mode = ReadWrite , |
||
PBoolean | searchPath = true , |
||
PBoolean | stderrSeparate = false |
||
) |
Open a channel.
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, |
const PStringToString & | environment, | ||
OpenMode | mode = ReadWrite , |
||
PBoolean | searchPath = true , |
||
PBoolean | stderrSeparate = false |
||
) |
Open a channel.
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, | ||
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.
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 |
|
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.
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.
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.
errors | String to receive standard error text. |
wait | Flag to indicate if function should block |
int PPipeChannel::WaitForTermination | ( | ) |
This function will block and wait for the sub-program to terminate.
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.
timeout | Amount of time to wait for process. |
|
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.
buf | Pointer to a block of memory to write. |
len | Number of bytes to write. |
Reimplemented from PChannel.
|
protected |
|
protected |
|
protected |
|
protected |
|
protected |
The fully qualified path name for the sub-program executable.
|
protected |