channel.h

开源代码的pwlib的1.10.0版本,使用openh323的1.18.0版本毕备

       The default behavour is to do nothing and return FALSE.

       @return
       TRUE if the shutdown was successfully performed.
     */
    virtual BOOL Shutdown(
      ShutdownValue option
    );

    /**Set the iostream buffer size for reads and writes.

       @return
       TRUE if the new buffer size was set.
      */
    BOOL SetBufferSize(
      PINDEX newSize    ///< New buffer size
    );

    /** Send a command meta-string. A meta-string is a string of characters
       that may contain escaped commands. The escape command is the \ as in
       the C language.

       The escape commands are:
\begin{description}
          \item[#\a#]    alert (ascii value 7)
          \item[#\b#]    backspace (ascii value 8)
          \item[#\f#]    formfeed (ascii value 12)
          \item[#\n#]    newline (ascii value 10)
          \item[#\r#]    return (ascii value 13)
          \item[#\t#]    horizontal tab (ascii value 9)
          \item[#\v#]    vertical tab (ascii value 11)
          \item[#\\#]    backslash
          \item[#\ooo#]  where ooo is octal number, ascii value ooo
          \item[#\xhh#]  where hh is hex number (ascii value 0xhh)
          \item[#\0#]    null character (ascii zero)
          \item[#\dns#]  delay for n seconds
          \item[#\dnm#]  delay for n milliseconds
          \item[#\s#]    characters following this, up to a \w
                                     command or the end of string, are to be
                                     sent to modem
          \item[#\wns#]  characters following this, up to a \s, \d
                                     or another \w or the end of the string are
                                     expected back from the modem. If the
                                     string is not received within n seconds,
                                     a failed command is registered. The
                                     exception to this is if the command is at
                                     the end of the string or the next
                                     character in the string is the \s, \d or
                                     \w in which case all characters are
                                     ignored from the modem until n seconds of
                                     no data.
          \item[#\wnm#]  as for above but timeout is in
                                     milliseconds.
\end{description}
       @return
       TRUE if the command string was completely processed.
     */
    BOOL SendCommandString(
      const PString & command  ///< Command to send to the channel
    );

    /** Abort a command string that is in progress. Note that as the
       SendCommandString() function blocks the calling thread when it runs,
       this can only be called from within another thread.
     */
    void AbortCommandString();
  //@}

  /**@name Error functions */
  //@{
    /** Normalised error codes.
        The error result of the last file I/O operation in this object.
     */
    enum Errors {
      NoError,
      /// Open fail due to device or file not found
      NotFound,       
      /// Open fail due to file already existing
      FileExists,     
      /// Write fail due to disk full
      DiskFull,       
      /// Operation fail due to insufficient privilege
      AccessDenied,   
      /// Open fail due to device already open for exclusive use
      DeviceInUse,    
      /// Operation fail due to bad parameters
      BadParameter,   
      /// Operation fail due to insufficient memory
      NoMemory,       
      /// Operation fail due to channel not being open yet
      NotOpen,        
      /// Operation failed due to a timeout
      Timeout,        
      /// Operation was interrupted
      Interrupted,    
      /// Operations buffer was too small for data.
      BufferTooSmall, 
      /// Miscellaneous error.
      Miscellaneous,
      /// High level protocol failure
      ProtocolFailure,
      NumNormalisedErrors
    };

    /**Error groups.
       To aid in multithreaded applications where reading and writing may be
       happening simultaneously, read and write errors are separated from
       other errors.
      */
    enum ErrorGroup {
      LastReadError,      ///< Error during Read() operation
      LastWriteError,     ///< Error during Write() operation
      LastGeneralError,   ///< Error during other operation, eg Open()
      NumErrorGroups
    };

    /** Get normalised error code.
      Return the error result of the last file I/O operation in this object.
      @return Normalised error code.
      */
    Errors GetErrorCode(
      ErrorGroup group = NumErrorGroups   ///< Error group to get
    ) const;

    /** Get OS errro code.
      Return the operating system error number of the last file I/O
      operation in this object.
      @return Operating System error code.
      */
    int GetErrorNumber(
      ErrorGroup group = NumErrorGroups   ///< Error group to get
    ) const;

      /** Get error message description.
        Return a string indicating the error message that may be displayed to
       the user. The error for the last I/O operation in this object is used.
      @return Operating System error description string.
       */
    virtual PString GetErrorText(
      ErrorGroup group = NumErrorGroups   ///< Error group to get
    ) const;

      /** Get error message description.
        Return a string indicating the error message that may be displayed to
       the user. The #osError# parameter is used unless zero, in which case
       the #lastError# parameter is used.
      @return Operating System error description string.
       */
    static PString GetErrorText(
      Errors lastError,   ///< Error code to translate.
      int osError = 0     ///< OS error number to translate.
    );
  //@}

    /** Convert an operating system error into platform independent error.
       This will set the lastError and osError member variables for access by
       GetErrorCode() and GetErrorNumber().
       
       @return TRUE if there was no error.
     */
    static BOOL ConvertOSError(
      int libcReturnValue,
      Errors & lastError,
      int & osError
    );

  /**@name Scattered read/write functions */
  //@{
    /** Structure that defines a "slice" of memory to be written to
     */
#if P_HAS_RECVMSG
    typedef iovec Slice;
#else
    struct Slice {
      void * iov_base;
      size_t iov_len;
    };
#endif

    typedef std::vector<Slice> VectorOfSlice;

    /** Low level scattered read from the channel. This is identical to Read except 
        that the data will be read into a series of scattered memory slices. By default,
        this call will default to calling Read multiple times, but this may be 
        implemented by operating systems to do a real scattered read

       @return
       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.
     */
    virtual BOOL Read(
      const VectorOfSlice & slices    // slices to read to
    );

    /** Low level scattered write to the channel. This is identical to Write except 
        that the data will be written from a series of scattered memory slices. By default,
        this call will default to calling Write multiple times, but this can be actually
        implemented by operating systems to do a real scattered write

       @return
       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.
     */
    virtual BOOL Write(
      const VectorOfSlice & slices    // slices to read to
    );
  //@}

  protected:
    PChannel(const PChannel &);
    PChannel & operator=(const PChannel &);
    // Prevent usage by external classes


    /** Convert an operating system error into platform independent error.
      The internal error codes are set by this function. They may be obtained
      via the #GetErrorCode()# and #GetErrorNumber()# functions.
       
       @return TRUE if there was no error.
     */
    virtual BOOL ConvertOSError(
      int libcReturnValue,
      ErrorGroup group = LastGeneralError ///< Error group to set
    );

    /**Set error values to those specified.
       Return TRUE if errorCode is NoError, FALSE otherwise
      */
    BOOL SetErrorValues(
      Errors errorCode,   ///< Error code to translate.
      int osError,        ///< OS error number to translate.
      ErrorGroup group = LastGeneralError ///< Error group to set
    );

    /** Read a character with specified timeout.
      This reads a single character from the channel waiting at most the
      amount of time specified for it to arrive. The #timeout# parameter
      is adjusted for amount of time it actually took, so it can be used
      for a multiple character timeout.

       @return TRUE if there was no error.
     */
    int ReadCharWithTimeout(
      PTimeInterval & timeout  // Timeout for read.
    );

    // Receive a (partial) command string, determine if completed yet.
    BOOL ReceiveCommandString(
      int nextChar,
      const PString & reply,
      PINDEX & pos,
      PINDEX start
    );


    // Member variables
    /// The operating system file handle return by standard open() function.
    int os_handle;
    /// The platform independant error code.
    Errors lastErrorCode[NumErrorGroups+1];
    /// The operating system error number (eg as returned by errno).
    int lastErrorNumber[NumErrorGroups+1];
    /// Number of byte last read by the Read() function.
    PINDEX lastReadCount;
    /// Number of byte last written by the Write() function.
    PINDEX lastWriteCount;
    /// Timeout for read operations.
    PTimeInterval readTimeout;
    /// Timeout for write operations.
    PTimeInterval writeTimeout;


  private:
    // New functions for class
    void Construct();
      // Complete platform dependent construction.

    // Member variables
    BOOL abortCommandString;
      // Flag to abort the transmission of a command in SendCommandString().


// Include platform dependent part of class
#ifdef _WIN32
#include "msos/ptlib/channel.h"
#else
#include "unix/ptlib/channel.h"
#endif

};

#endif

// End Of File ///////////////////////////////////////////////////////////////