menu: added new Keywords tag to .desktop files
[barry.git] / src / m_raw_channel.h
blobe79284d718c01af0ef883c2ac719dfa79680897d
1 ///
2 /// \file m_raw_channel.h
3 /// Mode class for a raw channel
4 ///
6 /*
7 Copyright (C) 2005-2013, 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__
26 #include "dll.h"
27 #include "m_mode_base.h"
28 #include "socket.h"
29 #include "data.h"
31 #include <string>
32 #include <pthread.h>
34 namespace Barry {
36 class semaphore;
38 namespace Mode {
40 // Forward declaration of internal classes
41 class RawChannelSocketHandler;
42 class RawChannelZeroSocketHandler;
44 // Callback from the raw channel.
46 class BXEXPORT RawChannelDataCallback
48 public:
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;
60 // Raw channel class
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
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;
84 Data m_receive_data;
86 protected:
87 void CheckQueueAvailable();
88 void InitBuffer();
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.
111 void OnOpen();
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.
125 // Will throw a Barry::Error if the provided controller
126 // doesn't have a routing queue set.
127 RawChannel(Controller &con);
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
134 // Will throw a Barry::Error if the provided controller
135 // doesn't have a routing queue set.
136 RawChannel(Controller &con, RawChannelDataCallback &callback);
138 virtual ~RawChannel();
140 //////////////////////////////////
141 // Raw channel mode specific methods
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.
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);
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.
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);
164 // Returns the maximum quantity of data which
165 // can be sent
166 size_t MaximumSendSize();
169 }} // namespace Barry::Mode
171 #endif