Bayonne2 / Common C++ 2 Framework: TTYSession Class Reference

Bayonne2 / Common C++ 2 Framework

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes

TTYSession Class Referenceabstract

The TTYSession aggragates a TTYStream and a Common C++ Thread which is assumed to be the execution context that will be used to perform actual I/O operations. More...

#include <serial.h>

Inheritance diagram for TTYSession:

Inheritance graph

[legend]

Collaboration diagram for TTYSession:

Collaboration graph

[legend]

Public Types

enum Throw { throwNothing, throwObject, throwException }

How to raise error. More...

typedef enum Thread::Throw Throw

How to raise error. More...

enum Cancel {
cancelInitial =0, cancelDeferred =1, cancelImmediate, cancelDisabled,
cancelManual, cancelDefault =cancelDeferred
}

How work cancellation. More...

typedef enum Thread::Cancel Cancel

How work cancellation. More...

enum Suspend { suspendEnable, suspendDisable }

How work suspend. More...

typedef enum Thread::Suspend Suspend

How work suspend. More...

enum Error {
  errSuccess = 0, errOpenNoTty, errOpenFailed, errSpeedInvalid,
  errFlowInvalid, errParityInvalid, errCharsizeInvalid, errStopbitsInvalid,
  errOptionInvalid, errResourceFailure, errOutput, errInput,
  errTimeout, errExtended
}

typedef enum Error Error

enum Flow { flowNone, flowSoft, flowHard, flowBoth }

typedef enum Flow Flow

enum Parity { parityNone, parityOdd, parityEven }

typedef enum Parity Parity

enum Pending { pendingInput, pendingOutput, pendingError }

typedef enum Pending Pending

Public Member Functions

TTYSession (const char *name, int pri=0, int stack=0)

Create TTY stream that will be managed by it's own thread. More...

virtual ~TTYSession ()

int start (Semaphore *start=0)

When a new thread is created, it does not begin immediate execution. More...

int detach (Semaphore *start=0)

Start a new thread as "detached". More...

Thread * getParent (void)

Gets the pointer to the Thread class which created the current thread object. More...

void suspend (void)

Suspends execution of the selected thread. More...

void resume (void)

Resumes execution of the selected thread. More...

Cancel getCancel (void)

Used to retrieve the cancellation mode in effect for the selected thread. More...

bool isRunning (void) const

Verifies if the thread is still running or has already been terminated but not yet deleted. More...

bool isDetached (void) const

Check if this thread is detached. More...

void join (void)

Blocking call which unlocks when thread terminates. More...

bool isThread (void) const

Tests to see if the current execution context is the same as the specified thread object. More...

cctid_t getId (void) const

Get system thread numeric identifier. More...

const char * getName (void) const

Get the name string for this thread, to use in debug messages. More...

void setTimeout (timeout_t to)

Set the timeout control. More...

void interactive (bool flag)

Set tty mode to buffered or "interactive". More...

int sync (void)

Flushes the stream input and out buffers, writes pending output. More...

bool isPending (Pending pend, timeout_t timeout=TIMEOUT_INF)

Get the status of pending operations. More...

Error setSpeed (unsigned long speed)

Set serial port speed for both input and output. More...

Error setCharBits (int bits)

Set character size. More...

Error setParity (Parity parity)

Set parity mode. More...

Error setStopBits (int bits)

Set number of stop bits. More...

Error setFlowControl (Flow flow)

Set flow control. More...

void toggleDTR (timeout_t millisec)

Set the DTR mode off momentarily. More...

void sendBreak (void)

Send the "break" signal. More...

Error getErrorNumber (void)

Often used by a "catch" to fetch the last error of a thrown serial. More...

char * getErrorString (void)

Often used by a "catch" to fetch the user set error string of a thrown serial. More...

int getBufferSize (void)

Get the "buffer" size for buffered operations. More...

Static Public Member Functions

static Thread * get (void)

static void setStack (size_t size=0)

Set base stack limit before manual stack sizes have effect. More...

static void sleep (timeout_t msec)

A thread-safe sleep call. More...

static void yield (void)

Yields the current thread's CPU time slice to allow another thread to begin immediate execution. More...

static Throw getException (void)

Get exception mode of the current thread. More...

static void setException (Throw mode)

Set exception mode of the current thread. More...

static Cancel enterCancel (void)

This is used to help build wrapper functions in libraries around system calls that should behave as cancellation points but don't. More...

static void exitCancel (Cancel cancel)

This is used to restore a cancel block. More...

Protected Member Functions

void setName (const char *text)

Set the name of the current thread. More...

virtual void run (void)=0

All threads execute by deriving the Run method of Thread. More...

virtual void final (void)

A thread that is self terminating, either by invoking exit() or leaving it's run(), will have this method called. More...

virtual void initial (void)

The initial method is called by a newly created thread when it starts execution. More...

virtual void * getExtended (void)

Since getParent() and getThread() only refer to an object of the Thread "base" type, this virtual method can be replaced in a derived class with something that returns data specific to the derived class that can still be accessed through the pointer returned by getParent() and getThread(). More...

virtual void notify (Thread *)

When a thread terminates, it now sends a notification message to the parent thread which created it. More...

void exit (void)

Used to properly exit from a Thread derived run() or initial() method. More...

void sync (void)

Used to wait for a join or cancel, in place of explicit exit. More...

bool testCancel (void)

test a cancellation point for deferred thread cancellation. More...

void setCancel (Cancel mode)

Sets thread cancellation mode. More...

void setSuspend (Suspend mode)

Sets the thread's ability to be suspended from execution. More...

void terminate (void)

Used by another thread to terminate the current thread. More...

void clrParent (void)

clear parent thread relationship. More...

void allocate (void)

Used to allocate the buffer space needed for iostream operations. More...

void endStream (void)

Used to terminate the buffer space and clean up the tty connection. More...

int underflow (void)

This streambuf method is used to load the input buffer through the established tty serial port. More...

int uflow (void)

This streambuf method is used for doing unbuffered reads through the establish tty serial port when in interactive mode. More...

int overflow (int ch)

This streambuf method is used to write the output buffer through the established tty port. More...

void open (const char *fname)

Opens the serial device. More...

void close (void)

Closes the serial device. More...

virtual int aRead (char *Data, const int Length)

Reads from serial device. More...

virtual int aWrite (const char *Data, const int Length)

Writes to serial device. More...

Error error (Error error, char *errstr=NULL)

This service is used to throw all serial errors which usually occur during the serial constructor. More...

void error (char *err)

This service is used to thow application defined serial errors where the application specific error code is a string. More...

void setError (bool enable)

This method is used to turn the error handler on or off for "throwing" execptions by manipulating the thrown flag. More...

int setPacketInput (int size, unsigned char btimer=0)

Set packet read mode and "size" of packet read buffer. More...

int setLineInput (char newline=13, char nl1=0)

Set "line buffering" read mode and specifies the newline character to be used in seperating line records. More...

void restore (void)

Restore serial device to the original settings at time of open. More...

void flushInput (void)

Used to flush the input waiting queue. More...

void flushOutput (void)

Used to flush any pending output data. More...

void waitOutput (void)

Used to wait until all output has been sent. More...

void endSerial (void)

Used as the default destructor for ending serial I/O services. More...

void initConfig (void)

Used to initialize a newly opened serial file handle. More...

Protected Attributes

char * gbuf

char * pbuf

timeout_t timeout

HANDLE dev

int bufsize

Detailed Description

The TTYSession aggragates a TTYStream and a Common C++ Thread which is assumed to be the execution context that will be used to perform actual I/O operations.

This class is very anagolous to TCPSession.

Author: David Sugar dyfet.nosp@m.@ost.nosp@m.el.co.nosp@m.m This class is very anagolous to TCPSession.

Definition at line 588 of file serial.h.

Member Typedef Documentation

typedef enum Thread::Cancel Thread::Cancel

inherited

How work cancellation.

typedef enum Error Serial::Error

inherited

Definition at line 117 of file serial.h.

typedef enum Flow Serial::Flow

inherited

Definition at line 125 of file serial.h.

typedef enum Parity Serial::Parity

inherited

Definition at line 132 of file serial.h.

typedef enum Pending Serial::Pending

inherited

Definition at line 139 of file serial.h.

typedef enum Thread::Suspend Thread::Suspend

inherited

How work suspend.

typedef enum Thread::Throw Thread::Throw

inherited

How to raise error.

Member Enumeration Documentation

enum Thread::Cancel

inherited

How work cancellation.

Enumerator
cancelInitial	used internally, do not use
cancelDeferred	exit thread on cancellation pointsuch as yield
cancelImmediate	exit befor cancellation
cancelDisabled	ignore cancellation
cancelManual	unimplemented (working in progress) Todo: implement
cancelDefault	default you should use this for compatibility instead of deferred

Definition at line 1108 of file thread.h.

enum Serial::Error

inherited

Enumerator
errSuccess
errOpenNoTty
errOpenFailed
errSpeedInvalid
errFlowInvalid
errParityInvalid
errCharsizeInvalid
errStopbitsInvalid
errOptionInvalid
errResourceFailure
errOutput
errInput
errTimeout
errExtended

Definition at line 101 of file serial.h.

enum Serial::Flow

inherited

Enumerator
flowNone
flowSoft
flowHard
flowBoth

Definition at line 119 of file serial.h.

enum Serial::Parity

inherited

Enumerator
parityNone
parityOdd
parityEven

Definition at line 127 of file serial.h.

enum Serial::Pending

inherited

Enumerator
pendingInput
pendingOutput
pendingError

Definition at line 134 of file serial.h.

enum Thread::Suspend

inherited

How work suspend.

Enumerator
suspendEnable	suspend enabled
suspendDisable	suspend disabled, Suspend do nothing

Definition at line 1122 of file thread.h.

enum Thread::Throw

inherited

How to raise error.

Enumerator
throwNothing	continue without throwing error
throwObject	throw object that cause error (throw this)
throwException	throw an object relative to error

Definition at line 1099 of file thread.h.

Constructor & Destructor Documentation

TTYSession::TTYSession ( const char * name,

int pri = 0,

int stack = 0

)

Create TTY stream that will be managed by it's own thread.

Parameters: name of tty device to open.

pri execution priority.

stack allocation needed on some platforms.

virtual TTYSession::~TTYSession ( )

virtual

Member Function Documentation

void TTYStream::allocate ( void )

protectedinherited

Used to allocate the buffer space needed for iostream operations.

This is based on MAX_INPUT.

virtual int Serial::aRead ( char * Data,

const int Length

)

protectedvirtualinherited

Reads from serial device.

Parameters: Data Point to character buffer to receive data. Buffers MUST be at least Length + 1 bytes in size.

Length Number of bytes to read.

virtual int Serial::aWrite ( const char * Data,

const int Length

)

protectedvirtualinherited

Writes to serial device.

Parameters: Data Point to character buffer containing data to write. Buffers MUST

Length Number of bytes to write.

void Serial::close ( void )

protectedinherited

Closes the serial device.

void Thread::clrParent ( void )

inlineprotectedinherited

clear parent thread relationship.

Definition at line 1295 of file thread.h.

int Thread::detach ( Semaphore * start = 0 )

inherited

Start a new thread as "detached".

This is an alternative start() method that resolves some issues with later glibc implimentations which incorrectly impliment self-detach.

Returns: error code if execution fails.

Parameters: start optional starting semaphore to alternately use.

void Serial::endSerial ( void )

protectedinherited

Used as the default destructor for ending serial I/O services.

It will restore the port to it's original state.

void TTYStream::endStream ( void )

protectedinherited

Used to terminate the buffer space and clean up the tty connection.

This function is called by the destructor.

static Cancel Thread::enterCancel ( void )

staticinherited

This is used to help build wrapper functions in libraries around system calls that should behave as cancellation points but don't.

Returns: saved cancel type.

Error Serial::error ( Error error,

char * errstr = NULL

)

protectedinherited

This service is used to throw all serial errors which usually occur during the serial constructor.

Parameters: error defined serial error id.

errstr string or message to optionally pass.

void Serial::error ( char * err )

inlineprotectedinherited

This service is used to thow application defined serial errors where the application specific error code is a string.

Parameters: err string or message to pass.

Definition at line 209 of file serial.h.

void Thread::exit ( void )

protectedinherited

Used to properly exit from a Thread derived run() or initial() method.

Terminates execution of the current thread and calls the derived classes final() method.

static void Thread::exitCancel ( Cancel cancel )

staticinherited

This is used to restore a cancel block.

Parameters: cancel type that was saved.

virtual void Thread::final ( void )

protectedvirtualinherited

A thread that is self terminating, either by invoking exit() or leaving it's run(), will have this method called.

It can be used to self delete the current object assuming the object was created with new on the heap rather than stack local, hence one may often see final defined as "delete this" in a derived thread class. A final method, while running, cannot be terminated or cancelled by another thread. Final is called for all cancellation type (even immediate).

You can safe delete thread ("delete this") class on final, but you should exit ASAP (or do not try to call CommonC++ methods...)

Note: A thread cannot delete its own context or join itself. To make a thread that is a self running object that self-deletes, one has to detach the thread by using detach() instead of start().

See Also: exit; run

Reimplemented in ThreadQueue.

void Serial::flushInput ( void )

protectedinherited

Used to flush the input waiting queue.

void Serial::flushOutput ( void )

protectedinherited

Used to flush any pending output data.

static Thread* Thread::get ( void )

staticinherited

int Serial::getBufferSize ( void )

inlineinherited

Get the "buffer" size for buffered operations.

This can be used when setting packet or line read modes to determine how many bytes to wait for in a given read call.

Returns: number of bytes used for buffering.

Definition at line 387 of file serial.h.

Cancel Thread::getCancel ( void )

inlineinherited

Used to retrieve the cancellation mode in effect for the selected thread.

Returns: cancellation mode constant.

Definition at line 1419 of file thread.h.

Error Serial::getErrorNumber ( void )

inlineinherited

Often used by a "catch" to fetch the last error of a thrown serial.

Returns: error numbr of last Error.

Definition at line 368 of file serial.h.

char* Serial::getErrorString ( void )

inlineinherited

Often used by a "catch" to fetch the user set error string of a thrown serial.

Returns: string for error message.

Definition at line 377 of file serial.h.

static Throw Thread::getException ( void )

staticinherited

Get exception mode of the current thread.

Returns: exception mode.

virtual void* Thread::getExtended ( void )

protectedvirtualinherited

Returns: pointer to derived class specific data.

cctid_t Thread::getId ( void ) const

inherited

Get system thread numeric identifier.

Returns: numeric identifier of this thread.

const char* Thread::getName ( void ) const

inlineinherited

Get the name string for this thread, to use in debug messages.

Returns: debug name.

Definition at line 1463 of file thread.h.

Thread* Thread::getParent ( void )

inlineinherited

Gets the pointer to the Thread class which created the current thread object.

Returns: a Thread *, or "(Thread *)this" if no parent.

Definition at line 1397 of file thread.h.

void Serial::initConfig ( void )

protectedinherited

Used to initialize a newly opened serial file handle.

You should set serial properties and DTR manually before first use.

virtual void Thread::initial ( void )

protectedvirtualinherited

The initial method is called by a newly created thread when it starts execution.

This method is ran with deferred cancellation disabled by default. The Initial method is given a separate handler so that it can create temporary objects on it's own stack frame, rather than having objects created on run() that are only needed by startup and yet continue to consume stack space.

See Also: run; final

Reimplemented in TCPSession, and UnixSession.

void TTYStream::interactive ( bool flag )

inherited

Set tty mode to buffered or "interactive".

When interactive, all streamed I/O is directly sent to the serial port immediately.

Parameters: flag bool set to true to make interactive.

bool Thread::isDetached ( void ) const

inherited

Check if this thread is detached.

Returns: true if the thread is detached.

bool TTYStream::isPending ( Pending pend,

timeout_t timeout = TIMEOUT_INF

)

virtualinherited

Get the status of pending operations.

This can be used to examine if input or output is waiting, or if an error has occured on the serial device. If read buffer contains data then input is ready and if write buffer contains data it is first flushed then checked.

Returns: true if ready, false if timeout.

Parameters: pend ready check to perform.

timeout in milliseconds.

Reimplemented from Serial.

bool Thread::isRunning ( void ) const

inherited

Verifies if the thread is still running or has already been terminated but not yet deleted.

Returns: true if the thread is still executing.

bool Thread::isThread ( void ) const

inherited

Tests to see if the current execution context is the same as the specified thread object.

Returns: true if the current context is this object.

void Thread::join ( void )

inherited

Blocking call which unlocks when thread terminates.

virtual void Thread::notify ( Thread * )

protectedvirtualinherited

When a thread terminates, it now sends a notification message to the parent thread which created it.

The actual use of this notification is left to be defined in a derived class.

Parameters: - the thread that has terminated.

void Serial::open ( const char * fname )

protectedinherited

Opens the serial device.

Parameters: fname Pathname of device to open

int TTYStream::overflow ( int ch )

protectedinherited

This streambuf method is used to write the output buffer through the established tty port.

Parameters: ch char to push through.

Returns: char pushed through.

void Serial::restore ( void )

protectedinherited

Restore serial device to the original settings at time of open.

void Thread::resume ( void )

inherited

Resumes execution of the selected thread.

virtual void Thread::run ( void )

protectedpure virtualinherited

All threads execute by deriving the Run method of Thread.

This method is called after Initial to begin normal operation of the thread. If the method terminates, then the thread will also terminate after notifying it's parent and calling it's Final() method.

See Also: Initial

Implemented in SerialService, SingleThreadRTPSession< RTPDataChannel, RTCPChannel, ServiceQueue >, SocketService, ThreadQueue, and SingleRTPSessionPool.

void Serial::sendBreak ( void )

inherited

Send the "break" signal.

void Thread::setCancel ( Cancel mode )

protectedinherited

Sets thread cancellation mode.

Threads can either be set immune to termination (cancelDisabled), can be set to terminate when reaching specific "thread cancellation points" (cancelDeferred) or immediately when Terminate is requested (cancelImmediate).

Parameters: mode for cancellation of the current thread.

Error Serial::setCharBits ( int bits )

inherited

Set character size.

Returns: 0 on success.

Parameters: bits character size to use (usually 7 or 8).

void Serial::setError ( bool enable )

inlineprotectedinherited

This method is used to turn the error handler on or off for "throwing" execptions by manipulating the thrown flag.

Parameters: enable true to enable handler.

Definition at line 219 of file serial.h.

static void Thread::setException ( Throw mode )

staticinherited

Set exception mode of the current thread.

Returns: exception mode.

Error Serial::setFlowControl ( Flow flow )

inherited

Set flow control.

Returns: 0 on success.

Parameters: flow control mode.

int Serial::setLineInput ( char newline = 13,

char nl1 = 0

)

protectedinherited

Set "line buffering" read mode and specifies the newline character to be used in seperating line records.

isPending can then be used to wait for an entire line of input.

Parameters: newline newline character.

nl1 EOL2 control character.

Returns: size of conical input buffer.

void Thread::setName ( const char * text )

protectedinherited

Set the name of the current thread.

If the name is passed as NULL, then the default name is set (usually object pointer).

Parameters: text name to use.

int Serial::setPacketInput ( int size,

unsigned char btimer = 0

)

protectedinherited

Set packet read mode and "size" of packet read buffer.

This sets VMIN to x. VTIM is normally set to "0" so that "isPending()" can wait for an entire packet rather than just the first byte.

Returns: actual buffer size set.

Parameters: size of packet read request.

btimer optional inter-byte data packet timeout.

Error Serial::setParity ( Parity parity )

inherited

Set parity mode.

Returns: 0 on success.

Parameters: parity mode.

Error Serial::setSpeed ( unsigned long speed )

inherited

Set serial port speed for both input and output.

Returns: 0 on success.

Parameters: speed to select. 0 signifies modem "hang up".

static void Thread::setStack ( size_t size = 0 )

inlinestaticinherited

Set base stack limit before manual stack sizes have effect.

Parameters: size stack size to set, or use 0 to clear autostack.

Definition at line 1347 of file thread.h.

Error Serial::setStopBits ( int bits )

inherited

Set number of stop bits.

Returns: 0 on success.

Parameters: bits stop bits.

void Thread::setSuspend ( Suspend mode )

protectedinherited

Sets the thread's ability to be suspended from execution.

The thread may either have suspend enabled (suspendEnable) or disabled (suspendDisable).

Parameters: mode for suspend.

void TTYStream::setTimeout ( timeout_t to )

inlineinherited

Set the timeout control.

Parameters: to timeout to use.

Definition at line 499 of file serial.h.

static void Thread::sleep ( timeout_t msec )

staticinherited

A thread-safe sleep call.

On most Posix systems, "sleep()" is implimented with SIGALRM making it unusable from multipe threads. Pthread libraries often define an alternate "sleep" handler such as usleep(), nanosleep(), or nap(), that is thread safe, and also offers a higher timer resolution.

Parameters: msec timeout in milliseconds.

int Thread::start ( Semaphore * start = 0 )

inherited

When a new thread is created, it does not begin immediate execution.

This is because the derived class virtual tables are not properly loaded at the time the C++ object is created within the constructor itself, at least in some compiler/system combinations. The thread can either be told to wait for an external semaphore, or it can be started directly after the constructor completes by calling the start() method.

Returns: error code if execution fails.

Parameters: start optional starting semaphore to alternately use.

void Thread::suspend ( void )

inherited

Suspends execution of the selected thread.

Pthreads do not normally support suspendable threads, so the behavior is simulated with signals. On systems such as Linux that define threads as processes, SIGSTOP and SIGCONT may be used.

int TTYStream::sync ( void )

inherited

Flushes the stream input and out buffers, writes pending output.

Returns: 0 on success.

void Thread::sync ( void )

protectedinherited

Used to wait for a join or cancel, in place of explicit exit.

void Thread::terminate ( void )

protectedinherited

Used by another thread to terminate the current thread.

Termination actually occurs based on the current setCancel() mode. When the current thread does terminate, control is returned to the requesting thread. terminate() should always be called at the start of any destructor of a class derived from Thread to assure the remaining part of the destructor is called without the thread still executing.

bool Thread::testCancel ( void )

protectedinherited

test a cancellation point for deferred thread cancellation.

void Serial::toggleDTR ( timeout_t millisec )

inherited

Set the DTR mode off momentarily.

Parameters: millisec number of milliseconds.

int TTYStream::uflow ( void )

protectedinherited

This streambuf method is used for doing unbuffered reads through the establish tty serial port when in interactive mode.

Also this method will handle proper use of buffers if not in interative mode.

Returns: char from tty serial port, EOF also possible.

int TTYStream::underflow ( void )

protectedinherited

This streambuf method is used to load the input buffer through the established tty serial port.

Returns: char from get buffer, EOF also possible.

void Serial::waitOutput ( void )

protectedinherited

Used to wait until all output has been sent.

static void Thread::yield ( void )

staticinherited

Yields the current thread's CPU time slice to allow another thread to begin immediate execution.

Field Documentation

int Serial::bufsize

protectedinherited

Definition at line 162 of file serial.h.

HANDLE Serial::dev

protectedinherited

Definition at line 160 of file serial.h.

char* TTYStream::gbuf

protectedinherited

Definition at line 432 of file serial.h.

bool Serial::linebuf

inherited

Definition at line 147 of file serial.h.

char * TTYStream::pbuf

protectedinherited

Definition at line 432 of file serial.h.

bool Serial::thrown

inherited

Definition at line 146 of file serial.h.

timeout_t TTYStream::timeout

protectedinherited

Definition at line 433 of file serial.h.

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

serial.h

Generated on Dec 21, 2017 for commoncpp2-1.8.1, ccrtp-1.7.2, libzrtpcpp-2.3.4, ccscript3-1.1.7, ccaudio2-1.0.0 and bayonne2-2.3.2 (after installation in /usr/local/) by doxygen 1.8.6