1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
|
/*
==============================================================================
This file is part of the juce_core module of the JUCE library.
Copyright (c) 2015 - ROLI Ltd.
Permission to use, copy, modify, and/or distribute this software for any purpose with
or without fee is hereby granted, provided that the above copyright notice and this
permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
------------------------------------------------------------------------------
NOTE! This permissive ISC license applies ONLY to files within the juce_core module!
All other JUCE modules are covered by a dual GPL/commercial license, so if you are
using any other modules, be sure to check that you also comply with their license.
For more details, visit www.juce.com
==============================================================================
*/
#ifndef JUCE_SOCKET_H_INCLUDED
#define JUCE_SOCKET_H_INCLUDED
//==============================================================================
/**
A wrapper for a streaming (TCP) socket.
This allows low-level use of sockets; for an easier-to-use messaging layer on top of
sockets, you could also try the InterprocessConnection class.
@see DatagramSocket, InterprocessConnection, InterprocessConnectionServer
*/
class JUCE_API StreamingSocket
{
public:
//==============================================================================
/** Creates an uninitialised socket.
To connect it, use the connect() method, after which you can read() or write()
to it.
To wait for other sockets to connect to this one, the createListener() method
enters "listener" mode, and can be used to spawn new sockets for each connection
that comes along.
*/
StreamingSocket();
/** Destructor. */
~StreamingSocket();
//==============================================================================
/** Binds the socket to the specified local port.
@returns true on success; false may indicate that another socket is already bound
on the same port
*/
bool bindToPort (int localPortNumber);
/** Binds the socket to the specified local port and local address.
If localAddress is not an empty string then the socket will be bound to localAddress
as well. This is useful if you would like to bind your socket to a specific network
adapter. Note that localAddress must be an IP address assigned to one of your
network address otherwise this function will fail.
@returns true on success; false may indicate that another socket is already bound
on the same port
@see bindToPort(int localPortNumber), IPAddress::findAllAddresses
*/
bool bindToPort (int localPortNumber, const String& localAddress);
/** Returns the local port number to which this socket is currently bound.
This is useful if you need to know to which port the OS has actually bound your
socket when calling the constructor or bindToPort with zero as the
localPortNumber argument. Returns -1 if the function fails. */
int getBoundPort() const noexcept;
/** Tries to connect the socket to hostname:port.
If timeOutMillisecs is 0, then this method will block until the operating system
rejects the connection (which could take a long time).
@returns true if it succeeds.
@see isConnected
*/
bool connect (const String& remoteHostname,
int remotePortNumber,
int timeOutMillisecs = 3000);
/** True if the socket is currently connected. */
bool isConnected() const noexcept { return connected; }
/** Closes the connection. */
void close();
/** Returns the name of the currently connected host. */
const String& getHostName() const noexcept { return hostName; }
/** Returns the port number that's currently open. */
int getPort() const noexcept { return portNumber; }
/** True if the socket is connected to this machine rather than over the network. */
bool isLocal() const noexcept;
/** Returns the OS's socket handle that's currently open. */
int getRawSocketHandle() const noexcept { return handle; }
//==============================================================================
/** Waits until the socket is ready for reading or writing.
If readyForReading is true, it will wait until the socket is ready for
reading; if false, it will wait until it's ready for writing.
If the timeout is < 0, it will wait forever, or else will give up after
the specified time.
If the socket is ready on return, this returns 1. If it times-out before
the socket becomes ready, it returns 0. If an error occurs, it returns -1.
*/
int waitUntilReady (bool readyForReading,
int timeoutMsecs) const;
/** Reads bytes from the socket.
If blockUntilSpecifiedAmountHasArrived is true, the method will block until
maxBytesToRead bytes have been read, (or until an error occurs). If this
flag is false, the method will return as much data as is currently available
without blocking.
@returns the number of bytes read, or -1 if there was an error.
@see waitUntilReady
*/
int read (void* destBuffer, int maxBytesToRead,
bool blockUntilSpecifiedAmountHasArrived);
/** Writes bytes to the socket from a buffer.
Note that this method will block unless you have checked the socket is ready
for writing before calling it (see the waitUntilReady() method).
@returns the number of bytes written, or -1 if there was an error.
*/
int write (const void* sourceBuffer, int numBytesToWrite);
//==============================================================================
/** Puts this socket into "listener" mode.
When in this mode, your thread can call waitForNextConnection() repeatedly,
which will spawn new sockets for each new connection, so that these can
be handled in parallel by other threads.
@param portNumber the port number to listen on
@param localHostName the interface address to listen on - pass an empty
string to listen on all addresses
@returns true if it manages to open the socket successfully.
@see waitForNextConnection
*/
bool createListener (int portNumber, const String& localHostName = String());
/** When in "listener" mode, this waits for a connection and spawns it as a new
socket.
The object that gets returned will be owned by the caller.
This method can only be called after using createListener().
@see createListener
*/
StreamingSocket* waitForNextConnection() const;
private:
//==============================================================================
String hostName;
int volatile portNumber, handle;
bool connected, isListener;
mutable CriticalSection readLock;
StreamingSocket (const String& hostname, int portNumber, int handle);
JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (StreamingSocket)
};
//==============================================================================
/**
A wrapper for a datagram (UDP) socket.
This allows low-level use of sockets; for an easier-to-use messaging layer on top of
sockets, you could also try the InterprocessConnection class.
@see StreamingSocket, InterprocessConnection, InterprocessConnectionServer
*/
class JUCE_API DatagramSocket
{
public:
//==============================================================================
/**
Creates a datagram socket.
You first need to bind this socket to a port with bindToPort if you intend to read
from this socket.
If enableBroadcasting is true, the socket will be allowed to send broadcast messages
(may require extra privileges on linux)
*/
DatagramSocket (bool enableBroadcasting = false);
/** Destructor. */
~DatagramSocket();
//==============================================================================
/** Binds the socket to the specified local port.
The localPortNumber is the port on which to bind this socket. If this value is 0,
the port number is assigned by the operating system.
@returns true on success; false may indicate that another socket is already bound
on the same port
*/
bool bindToPort (int localPortNumber);
/** Binds the socket to the specified local port and local address.
If localAddress is not an empty string then the socket will be bound to localAddress
as well. This is useful if you would like to bind your socket to a specific network
adapter. Note that localAddress must be an IP address assigned to one of your
network address otherwise this function will fail.
@returns true on success; false may indicate that another socket is already bound
on the same port
@see bindToPort(int localPortNumber), IPAddress::findAllAddresses
*/
bool bindToPort (int localPortNumber, const String& localAddress);
/** Returns the local port number to which this socket is currently bound.
This is useful if you need to know to which port the OS has actually bound your
socket when bindToPort was called with zero.
Returns -1 if the socket didn't bind to any port yet or an error occured. */
int getBoundPort() const noexcept;
/** Returns the OS's socket handle that's currently open. */
int getRawSocketHandle() const noexcept { return handle; }
//==============================================================================
/** Waits until the socket is ready for reading or writing.
If readyForReading is true, it will wait until the socket is ready for
reading; if false, it will wait until it's ready for writing.
If the timeout is < 0, it will wait forever, or else will give up after
the specified time.
If the socket is ready on return, this returns 1. If it times-out before
the socket becomes ready, it returns 0. If an error occurs, it returns -1.
*/
int waitUntilReady (bool readyForReading,
int timeoutMsecs) const;
/** Reads bytes from the socket.
If blockUntilSpecifiedAmountHasArrived is true, the method will block until
maxBytesToRead bytes have been read, (or until an error occurs). If this
flag is false, the method will return as much data as is currently available
without blocking.
@returns the number of bytes read, or -1 if there was an error.
@see waitUntilReady
*/
int read (void* destBuffer, int maxBytesToRead,
bool blockUntilSpecifiedAmountHasArrived);
/** Reads bytes from the socket and return the IP address of the sender.
If blockUntilSpecifiedAmountHasArrived is true, the method will block until
maxBytesToRead bytes have been read, (or until an error occurs). If this
flag is false, the method will return as much data as is currently available
without blocking.
@returns the number of bytes read, or -1 if there was an error. On a successful
result, the senderIPAddress value will be set to the IP of the sender.
@see waitUntilReady
*/
int read (void* destBuffer, int maxBytesToRead,
bool blockUntilSpecifiedAmountHasArrived,
String& senderIPAddress, int& senderPortNumber);
/** Writes bytes to the socket from a buffer.
Note that this method will block unless you have checked the socket is ready
for writing before calling it (see the waitUntilReady() method).
@returns the number of bytes written, or -1 if there was an error.
*/
int write (const String& remoteHostname, int remotePortNumber,
const void* sourceBuffer, int numBytesToWrite);
//==============================================================================
/** Join a multicast group
@returns true if it succeeds.
*/
bool joinMulticast (const String& multicastIPAddress);
/** Leave a multicast group
@returns true if it succeeds.
*/
bool leaveMulticast (const String& multicastIPAddress);
private:
//==============================================================================
int handle;
bool isBound;
String lastBindAddress, lastServerHost;
int lastServerPort;
void* lastServerAddress;
mutable CriticalSection readLock;
JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (DatagramSocket)
};
#endif // JUCE_SOCKET_H_INCLUDED
|
