2 /// \file m_raw_channel.h
3 /// Mode class for a raw channel
7 Copyright (C) 2005-2011, Net Direct Inc. (http://www.netdirect.ca/)
8 Portions Copyright (C) 2010 RealVNC Ltd.
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.
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.
19 See the GNU General Public License in the COPYING file at the
20 root directory of this project for more details.
23 #ifndef __BARRY_M_RAW_CHANNEL_H__
24 #define __BARRY_M_RAW_CHANNEL_H__
27 #include "m_mode_base.h"
40 // Forward declaration of internal classes
41 class RawChannelSocketHandler
;
42 class RawChannelZeroSocketHandler
;
44 // Callback from the raw channel.
46 class BXEXPORT RawChannelDataCallback
49 virtual ~RawChannelDataCallback() {}
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;
62 /// The main class for creating a raw channel session.
64 /// To use this class, use the following steps:
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
74 class BXEXPORT RawChannel
: public Mode
76 friend class RawChannelSocketHandler
;
77 friend class RawChannelZeroSocketHandler
;
79 RawChannelDataCallback
*m_callback
;
80 unsigned char *m_send_buffer
;
81 bool m_zero_registered
;
82 std::string
*m_pending_error
;
87 void CheckQueueAvailable();
89 void SetPendingError(const char *msg
);
90 void UnregisterZeroSocketInterest();
92 // Used to validate a packet is a valid channel data packet
93 void ValidateDataPacket(Data
&data
);
95 // Not intended for use by users of this class.
96 // Used for handling zero-socket packets.
97 void HandleReceivedZeroPacket(Data
&data
);
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
);
105 // Not intended for use by users of this class.
106 void HandleError(Barry::Error
&data
);
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.
113 // Creates a raw channel in non-callback mode.
114 // This requires all data to be sent and received
115 // via calls to Send and Receive.
116 // As there are no notifications of data being
117 // available to send or receive, this is only recommended
118 // for use with synchronous protocols over the channel.
120 // Will throw a Barry::Error if the provided controller
121 // doesn't have a routing queue set.
122 RawChannel(Controller
&con
);
124 // Creates a raw channel in callback mode.
125 // This requires all data to be sent via calls to Send, but
126 // the Receive method must never be called.
127 // Instead the DataReceive
129 // Will throw a Barry::Error if the provided controller
130 // doesn't have a routing queue set.
131 RawChannel(Controller
&con
, RawChannelDataCallback
&callback
);
133 virtual ~RawChannel();
135 //////////////////////////////////
136 // Raw channel mode specific methods
138 // Send some data on the raw channel.
139 // Will throw a Barry::Error if data is longer than
140 // MaximumPacketContentsSize or a Usb::Error if there
141 // is an underlying USB error.
143 // If using a raw channel in callback mode then care must be
144 // taken to ensure another thread is running during any calls
145 // to Send. See the comment in the constructor of RawChannel
146 // for further information.
147 void Send(Data
&data
, int timeout
= -1);
149 // Receive some data on the raw channel.
150 // Will throw a Barry::Error if a disconnect occurs
151 // or a Usb::Error if there is an underlying USB error
152 // or a Usb::Timeout if the receive times out.
154 // Only valid to call this if the raw channel was created in non-callback
155 // mode. If this is called when the raw channel was created with a
156 // callback then a std::logic_error will be thrown.
157 void Receive(Data
&data
, int timeout
= -1);
159 // Returns the maximum quantity of data which
161 size_t MaximumSendSize();
164 }} // namespace Barry::Mode