channel.h

mgcp协议源代码。支持多种编码：g711

       String that was read.
     */
    PString ReadString(PINDEX len);

    /** Begin an asynchronous read from channel. The read timeout is used as in
       other read operations, in this case calling the OnReadComplete()
       function.

       Note that if the channel is not capable of asynchronous read then this
       will do a sychronous read is in the Read() function with the addition
       of calling the OnReadComplete() before returning.

       @return
       TRUE if the read was sucessfully queued.
     */
    virtual BOOL ReadAsync(
      void * buf,   /// Pointer to a block of memory to receive the read bytes.
      PINDEX len    /// Maximum number of bytes to read into the buffer.
    );

    /** User callback function for when a #ReadAsync()# call has completed or
       timed out. The original pointer to the buffer passed in ReadAsync() is
       passed to the function.
     */
    virtual void OnReadComplete(
      void * buf, /// Pointer to a block of memory that received the read bytes.
      PINDEX len  /// Actual number of bytes to read into the buffer.
    );
  //@}

  /**@name Writing functions */
  //@{
    /** Set the timeout for write operations to complete. This may be zero for
       immediate return through to PMaxMilliseconds which will wait forever for
       the write request to be completed.
       
       Note that this function may not be available, or meaningfull,  for all
       channels. In this case the parameter is et but ignored.
     */
    void SetWriteTimeout(
      const PTimeInterval & time /// The new time interval for write operations.
    );

    /** Get the timeout for write operations to complete. Note that this
       function may not be available, or meaningfull, for all channels. In
       that case it returns the previously set value.

       @return
       time interval for writing.
     */
    PTimeInterval GetWriteTimeout() const;

    /** 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.

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

       @return
       TRUE if at least len bytes were written to the channel.
     */
    virtual BOOL Write(
      const void * buf, /// Pointer to a block of memory to write.
      PINDEX len        /// Number of bytes to write.
    );

    /** Get the number of bytes written by the last Write() call.
       
       Note that the number of bytes written may often be less, or even more,
       than that asked for. A common case of it being less is where the disk
       is full. An example of where the bytes written is more is as follows.
       On a #PTextFile# channel on the MSDOS platform, there is
       translation of \n to CR/LF pairs. This will result in the number of
       bytes returned being more than that requested.

       @return
       the number of bytes written.
     */
    PINDEX GetLastWriteCount() const;

    /** Write a single character to the channel. This function simply uses the
       Write() function so all comments on that function also apply.
       
       Note that this asserts if the value is not in the range 0..255.

       @return
       TRUE if the byte was successfully written.
     */
    BOOL WriteChar(int c);

    /** Write a string to the channel. This function simply uses the Write()
       function so all comments on that function also apply.

       @return
       TRUE if the character written.
     */
    BOOL WriteString(const PString & str);

    /** Begin an asynchronous write from channel. The write timeout is used as
       in other write operations, in this case calling the OnWriteComplete()
       function. Note that if the channel is not capable of asynchronous write
       then this will do a sychronous write as in the Write() function with
       the addition of calling the OnWriteComplete() before returning.

       @return
       TRUE of the write operation was succesfully queued.
     */
    virtual BOOL WriteAsync(
      const void * buf, /// Pointer to a block of memory to write.
      PINDEX len        /// Number of bytes to write.
    );

    /** User callback function for when a WriteAsync() call has completed or
       timed out. The original pointer to the buffer passed in WriteAsync() is
       passed in here and the len parameter is the actual number of characters
       written.
     */
    virtual void OnWriteComplete(
      const void * buf, /// Pointer to a block of memory to write.
      PINDEX len        /// Number of bytes to write.
    );
  //@}

  /**@name Miscellaneous functions */
  //@{
    /** Close the channel, shutting down the link to the data source.

       @return TRUE if the channel successfully closed.
     */
    virtual BOOL Close();

    enum ShutdownValue {
      ShutdownRead         = 0,
      ShutdownWrite        = 1,
      ShutdownReadAndWrite = 2
    };

    /** Close one or both of the data streams associated with a channel.

       The default behavour is to do nothing and return FALSE.

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

    /** 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
    };
    /** Get normalised error code.
      Return the error result of the last file I/O operation in this object.
      @return Normalised error code.
      */
    Errors GetErrorCode() 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() 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() 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 error, Errors & lastError, int & osError);

  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 error);


    /** 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 lastError;
    /// The operating system error number (eg as returned by errno).
    int osError;
    /// 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().

#ifdef DOC_PLUS_PLUS
};
#endif

// Class declaration continued in platform specific header file ///////////////