src/m_raw_channel.h

   1 ///
   2 /// \file       m_raw_channel.h
   3 ///             Mode class for a raw channel
   4 ///
   5
   6 /*
   7     Copyright (C) 2005-2013, Net Direct Inc. (http://www.netdirect.ca/)
   8     Portions Copyright (C) 2010 RealVNC Ltd.
   9
  10     This program is free software; you can redistribute it and/or modify
  11     it under the terms of the GNU General Public License as published by
  12     the Free Software Foundation; either version 2 of the License, or
  13     (at your option) any later version.
  14
  15     This program is distributed in the hope that it will be useful,
  16     but WITHOUT ANY WARRANTY; without even the implied warranty of
  17     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  18
  19     See the GNU General Public License in the COPYING file at the
  20     root directory of this project for more details.
  21 */
  22
  23 #ifndef __BARRY_M_RAW_CHANNEL_H__
  24 #define __BARRY_M_RAW_CHANNEL_H__
  25
  26 #include "dll.h"
  27 #include "m_mode_base.h"
  28 #include "socket.h"
  29 #include "data.h"
  30
  31 #include <string>
  32 #include <pthread.h>
  33
  34 namespace Barry {
  35
  36 class semaphore;
  37
  38 namespace Mode {
  39
  40 // Forward declaration of internal classes
  41 class RawChannelSocketHandler;
  42 class RawChannelZeroSocketHandler;
  43
  44 // Callback from the raw channel.
  45
  46 class BXEXPORT RawChannelDataCallback
  47 {
  48 public:
  49         virtual ~RawChannelDataCallback() {}
  50
  51         // Called when data has been received on the channel
  52         virtual void DataReceived(Data &data) = 0;
  53         // Called when the channel has an error
  54         virtual void ChannelError(std::string msg) = 0;
  55         // Called when the channel has been asked to close by the other side
  56         virtual void ChannelClose() = 0;
  57 };
  58
  59 //
  60 // Raw channel class
  61 //
  62 /// The main class for creating a raw channel session.
  63 ///
  64 /// To use this class, use the following steps:
  65 ///
  66 /// - Implement RawChannelDataCallback
  67 ///     - Create a Controller object (see Controller class for more details)
  68 ///     - Create this Mode::RawChannel object, passing in the Controller
  69 ///             object during construction
  70 ///     - Call Open() to open the channel and finish constructing.
  71 ///     - Call GetData() to fetch data
  72 ///     - Call SendData() to send data
  73 ///
  74 class BXEXPORT RawChannel : public Mode
  75 {
  76         friend class RawChannelSocketHandler;
  77         friend class RawChannelZeroSocketHandler;
  78
  79         RawChannelDataCallback *m_callback;
  80         unsigned char *m_send_buffer;
  81         bool m_zero_registered;
  82         std::string *m_pending_error;
  83
  84         Data m_receive_data;
  85
  86 protected:
  87         void CheckQueueAvailable();
  88         void InitBuffer();
  89         void SetPendingError(const char *msg);
  90         void UnregisterZeroSocketInterest();
  91
  92         // Used to validate a packet is a valid channel data packet
  93         void ValidateDataPacket(Data &data);
  94
  95         // Not intended for use by users of this class.
  96         // Used for handling zero-socket packets.
  97         void HandleReceivedZeroPacket(Data &data);
  98
  99         // Not intended for use by users of this class.
 100         // Instead data received will come in via the
 101         // RawChannelDataCallback::DataReceived callback
 102         // or using Receive().
 103         void HandleReceivedData(Data &data);
 104
 105         // Not intended for use by users of this class.
 106         void HandleError(Barry::Error &data);
 107
 108         // Not intended for use by users of this class.
 109         // This method is called by the internals of
 110         // Barry when setting up a connection.
 111         void OnOpen();
 112
 113         // Not intended for use by users of this class.
 114         // This method is called by the internals of
 115         // Barry when setting up a connection.
 116         SocketRoutingQueue::SocketDataHandlerPtr GetHandler();
 117 public:
 118         // Creates a raw channel in non-callback mode.
 119         // This requires all data to be sent and received
 120         // via calls to Send and Receive.
 121         // As there are no notifications of data being
 122         // available to send or receive, this is only recommended
 123         // for use with synchronous protocols over the channel.
 124         //
 125         // Will throw a Barry::Error if the provided controller
 126         // doesn't have a routing queue set.
 127         RawChannel(Controller &con);
 128
 129         // Creates a raw channel in callback mode.
 130         // This requires all data to be sent via calls to Send, but
 131         // the Receive method must never be called.
 132         // Instead the DataReceive
 133         //
 134         // Will throw a Barry::Error if the provided controller
 135         // doesn't have a routing queue set.
 136         RawChannel(Controller &con, RawChannelDataCallback &callback);
 137
 138         virtual ~RawChannel();
 139
 140         //////////////////////////////////
 141         // Raw channel mode specific methods
 142
 143         // Send some data on the raw channel.
 144         // Will throw a Barry::Error if data is longer than
 145         // MaximumPacketContentsSize or a Usb::Error if there
 146         // is an underlying USB error.
 147         //
 148         // If using a raw channel in callback mode then care must be
 149         // taken to ensure another thread is running during any calls
 150         // to Send. See the comment in the constructor of RawChannel
 151         // for further information.
 152         void Send(Data &data, int timeout = -1);
 153
 154         // Receive some data on the raw channel.
 155         // Will throw a Barry::Error if a disconnect occurs
 156         // or a Usb::Error if there is an underlying USB error
 157         // or a Usb::Timeout if the receive times out.
 158         //
 159         // Only valid to call this if the raw channel was created in non-callback
 160         // mode. If this is called when the raw channel was created with a
 161         // callback then a std::logic_error will be thrown.
 162         void Receive(Data &data, int timeout = -1);
 163
 164         // Returns the maximum quantity of data which
 165         // can be sent
 166         size_t MaximumSendSize();
 167 };
 168
 169 }} // namespace Barry::Mode
 170
 171 #endif
 172