m_raw_channel.h

Go to the documentation of this file.
00001 ///
00002 /// \file       m_raw_channel.h
00003 ///             Mode class for a raw channel
00004 ///
00005 
00006 /*
00007     Copyright (C) 2005-2012, Net Direct Inc. (http://www.netdirect.ca/)
00008     Portions Copyright (C) 2010 RealVNC Ltd.
00009 
00010     This program is free software; you can redistribute it and/or modify
00011     it under the terms of the GNU General Public License as published by
00012     the Free Software Foundation; either version 2 of the License, or
00013     (at your option) any later version.
00014 
00015     This program is distributed in the hope that it will be useful,
00016     but WITHOUT ANY WARRANTY; without even the implied warranty of
00017     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
00018 
00019     See the GNU General Public License in the COPYING file at the
00020     root directory of this project for more details.
00021 */
00022 
00023 #ifndef __BARRY_M_RAW_CHANNEL_H__
00024 #define __BARRY_M_RAW_CHANNEL_H__
00025 
00026 #include "dll.h"
00027 #include "m_mode_base.h"
00028 #include "socket.h"
00029 #include "data.h"
00030 
00031 #include <string>
00032 #include <pthread.h>
00033 
00034 namespace Barry {
00035 
00036 class semaphore;
00037 
00038 namespace Mode {
00039 
00040 // Forward declaration of internal classes
00041 class RawChannelSocketHandler;
00042 class RawChannelZeroSocketHandler;
00043 
00044 // Callback from the raw channel.
00045 
00046 class BXEXPORT RawChannelDataCallback
00047 {
00048 public:
00049         virtual ~RawChannelDataCallback() {}
00050 
00051         // Called when data has been received on the channel
00052         virtual void DataReceived(Data &data) = 0;
00053         // Called when the channel has an error
00054         virtual void ChannelError(std::string msg) = 0;
00055         // Called when the channel has been asked to close by the other side
00056         virtual void ChannelClose() = 0;
00057 };
00058 
00059 //
00060 // Raw channel class
00061 //
00062 /// The main class for creating a raw channel session.
00063 ///
00064 /// To use this class, use the following steps:
00065 ///
00066 /// - Implement RawChannelDataCallback
00067 ///     - Create a Controller object (see Controller class for more details)
00068 ///     - Create this Mode::RawChannel object, passing in the Controller
00069 ///             object during construction
00070 ///     - Call Open() to open the channel and finish constructing.
00071 ///     - Call GetData() to fetch data
00072 ///     - Call SendData() to send data
00073 ///
00074 class BXEXPORT RawChannel : public Mode
00075 {
00076         friend class RawChannelSocketHandler;
00077         friend class RawChannelZeroSocketHandler;
00078 
00079         RawChannelDataCallback *m_callback;
00080         unsigned char *m_send_buffer;
00081         bool m_zero_registered;
00082         std::string *m_pending_error;
00083 
00084         Data m_receive_data;
00085 
00086 protected:
00087         void CheckQueueAvailable();
00088         void InitBuffer();
00089         void SetPendingError(const char *msg);
00090         void UnregisterZeroSocketInterest();
00091 
00092         // Used to validate a packet is a valid channel data packet
00093         void ValidateDataPacket(Data &data);
00094 
00095         // Not intended for use by users of this class.
00096         // Used for handling zero-socket packets.
00097         void HandleReceivedZeroPacket(Data &data);
00098 
00099         // Not intended for use by users of this class.
00100         // Instead data received will come in via the
00101         // RawChannelDataCallback::DataReceived callback
00102         // or using Receive().
00103         void HandleReceivedData(Data &data);
00104 
00105         // Not intended for use by users of this class.
00106         void HandleError(Barry::Error &data);
00107 
00108         // Not intended for use by users of this class.
00109         // This method is called by the internals of
00110         // Barry when setting up a connection.
00111         void OnOpen();
00112 public:
00113         // Creates a raw channel in non-callback mode.
00114         // This requires all data to be sent and received
00115         // via calls to Send and Receive.
00116         // As there are no notifications of data being
00117         // available to send or receive, this is only recommended
00118         // for use with synchronous protocols over the channel.
00119         //
00120         // Will throw a Barry::Error if the provided controller
00121         // doesn't have a routing queue set.
00122         RawChannel(Controller &con);
00123 
00124         // Creates a raw channel in callback mode.
00125         // This requires all data to be sent via calls to Send, but
00126         // the Receive method must never be called.
00127         // Instead the DataReceive
00128         //
00129         // Will throw a Barry::Error if the provided controller
00130         // doesn't have a routing queue set.
00131         RawChannel(Controller &con, RawChannelDataCallback &callback);
00132 
00133         virtual ~RawChannel();
00134 
00135         //////////////////////////////////
00136         // Raw channel mode specific methods
00137 
00138         // Send some data on the raw channel.
00139         // Will throw a Barry::Error if data is longer than
00140         // MaximumPacketContentsSize or a Usb::Error if there
00141         // is an underlying USB error.
00142         //
00143         // If using a raw channel in callback mode then care must be
00144         // taken to ensure another thread is running during any calls
00145         // to Send. See the comment in the constructor of RawChannel
00146         // for further information.
00147         void Send(Data &data, int timeout = -1);
00148 
00149         // Receive some data on the raw channel.
00150         // Will throw a Barry::Error if a disconnect occurs
00151         // or a Usb::Error if there is an underlying USB error
00152         // or a Usb::Timeout if the receive times out.
00153         //
00154         // Only valid to call this if the raw channel was created in non-callback
00155         // mode. If this is called when the raw channel was created with a
00156         // callback then a std::logic_error will be thrown.
00157         void Receive(Data &data, int timeout = -1);
00158 
00159         // Returns the maximum quantity of data which
00160         // can be sent
00161         size_t MaximumSendSize();
00162 };
00163 
00164 }} // namespace Barry::Mode
00165 
00166 #endif
00167