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-2010, 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         // Mutex for signalling between read and write threads
  80         pthread_mutex_t m_mutex;
  81         bool m_mutex_valid;
  82         // Condvar for signalling between read and write threads
  83         pthread_cond_t m_cv;
  84         bool m_cv_valid;
  85
  86         semaphore *m_semaphore;
  87         RawChannelDataCallback *m_callback;
  88         unsigned char *m_send_buffer;
  89         bool m_zero_registered;
  90         std::string *m_pending_error;
  91
  92         Data m_receive_data;
  93
  94 protected:
  95         void CheckQueueAvailable();
  96         void InitBuffer();
  97         void InitSemaphore();
  98         void SetPendingError(const char *msg);
  99         void UnregisterZeroSocketInterest();
 100
 101         // Used to validate a packet is a valid channel data packet
 102         void ValidateDataPacket(Data &data);
 103
 104         // Not intended for use by users of this class.
 105         // Used for handling zero-socket packets.
 106         void HandleReceivedZeroPacket(Data &data);
 107
 108         // Not intended for use by users of this class.
 109         // Instead data received will come in via the
 110         // RawChannelDataCallback::DataReceived callback
 111         // or using Receive().
 112         void HandleReceivedData(Data &data);
 113
 114         // Not intended for use by users of this class.
 115         void HandleError(Barry::Error &data);
 116
 117         // Not intended for use by users of this class.
 118         // This method is called by the internals of
 119         // Barry when setting up a connection.
 120         void OnOpen();
 121 public:
 122         // Creates a raw channel in non-callback mode.
 123         // This requires all data to be sent and received
 124         // via calls to Send and Receive.
 125         // As there are no notifications of data being
 126         // available to send or receive, this is only recommended
 127         // for use with synchronous protocols over the channel.
 128         //
 129         // Will throw a Barry::Error if the provided controller
 130         // doesn't have a routing queue set.
 131         RawChannel(Controller &con);
 132
 133         // Creates a raw channel in callback mode.
 134         // This requires all data to be sent via calls to Send, but
 135         // the Receive method must never be called.
 136         // Instead the DataReceive
 137         //
 138         // Will throw a Barry::Error if the provided controller
 139         // doesn't have a routing queue set.
 140         RawChannel(Controller &con, RawChannelDataCallback &callback);
 141
 142         virtual ~RawChannel();
 143
 144         //////////////////////////////////
 145         // Raw channel mode specific methods
 146
 147         // Send some data on the raw channel.
 148         // Will throw a Barry::Error if data is longer than
 149         // MaximumPacketContentsSize or a Usb::Error if there
 150         // is an underlying USB error.
 151         //
 152         // If using a raw channel in callback mode then care must be
 153         // taken to ensure another thread is running during any calls
 154         // to Send. See the comment in the constructor of RawChannel
 155         // for further information.
 156         void Send(Data &data, int timeout = -1);
 157
 158         // Receive some data on the raw channel.
 159         // Will throw a Barry::Error if a disconnect occurs
 160         // or a Usb::Error if there is an underlying USB error
 161         // or a Usb::Timeout if the receive times out.
 162         //
 163         // Only valid to call this if the raw channel was created in non-callback
 164         // mode. If this is called when the raw channel was created with a
 165         // callback then a std::logic_error will be thrown.
 166         void Receive(Data &data, int timeout = -1);
 167
 168         // Returns the maximum quantity of data which
 169         // can be sent
 170         size_t MaximumSendSize();
 171 };
 172
 173 }} // namespace Barry::Mode
 174
 175 #endif
 176