OpenShot Library | libopenshot-audio 0.2.0
juce_InterprocessConnection.h
1
2/** @weakgroup juce_events-interprocess
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 The code included in this file is provided under the terms of the ISC license
15 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16 To use, copy, modify, and/or distribute this software for any purpose with or
17 without fee is hereby granted provided that the above copyright notice and
18 this permission notice appear in all copies.
19
20 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22 DISCLAIMED.
23
24 ==============================================================================
25*/
26
27namespace juce
28{
29
30class InterprocessConnectionServer;
31class MemoryBlock;
32
33
34//==============================================================================
35/**
36 Manages a simple two-way messaging connection to another process, using either
37 a socket or a named pipe as the transport medium.
38
39 To connect to a waiting socket or an open pipe, use the connectToSocket() or
40 connectToPipe() methods. If this succeeds, messages can be sent to the other end,
41 and incoming messages will result in a callback via the messageReceived()
42 method.
43
44 To open a pipe and wait for another client to connect to it, use the createPipe()
45 method.
46
47 To act as a socket server and create connections for one or more client, see the
48 InterprocessConnectionServer class.
49
50 @see InterprocessConnectionServer, Socket, NamedPipe
51
52 @tags{Events}
53*/
55{
56public:
57 //==============================================================================
58 /** Creates a connection.
59
60 Connections are created manually, connecting them with the connectToSocket()
61 or connectToPipe() methods, or they are created automatically by a InterprocessConnectionServer
62 when a client wants to connect.
63
64 @param callbacksOnMessageThread if true, callbacks to the connectionMade(),
65 connectionLost() and messageReceived() methods will
66 always be made using the message thread; if false,
67 these will be called immediately on the connection's
68 own thread.
69 @param magicMessageHeaderNumber a magic number to use in the header to check the
70 validity of the data blocks being sent and received. This
71 can be any number, but the sender and receiver must obviously
72 use matching values or they won't recognise each other.
73 */
74 InterprocessConnection (bool callbacksOnMessageThread = true,
75 uint32 magicMessageHeaderNumber = 0xf2b49e2c);
76
77 /** Destructor. */
79
80 //==============================================================================
81 /** Tries to connect this object to a socket.
82
83 For this to work, the machine on the other end needs to have a InterprocessConnectionServer
84 object waiting to receive client connections on this port number.
85
86 @param hostName the host computer, either a network address or name
87 @param portNumber the socket port number to try to connect to
88 @param timeOutMillisecs how long to keep trying before giving up
89 @returns true if the connection is established successfully
90 @see Socket
91 */
92 bool connectToSocket (const String& hostName,
93 int portNumber,
94 int timeOutMillisecs);
95
96 /** Tries to connect the object to an existing named pipe.
97
98 For this to work, another process on the same computer must already have opened
99 an InterprocessConnection object and used createPipe() to create a pipe for this
100 to connect to.
101
102 @param pipeName the name to use for the pipe - this should be unique to your app
103 @param pipeReceiveMessageTimeoutMs a timeout length to be used when reading or writing
104 to the pipe, or -1 for an infinite timeout.
105 @returns true if it connects successfully.
106 @see createPipe, NamedPipe
107 */
108 bool connectToPipe (const String& pipeName, int pipeReceiveMessageTimeoutMs);
109
110 /** Tries to create a new pipe for other processes to connect to.
111
112 This creates a pipe with the given name, so that other processes can use
113 connectToPipe() to connect to the other end.
114
115 @param pipeName the name to use for the pipe - this should be unique to your app
116 @param pipeReceiveMessageTimeoutMs a timeout length to be used when reading or writing
117 to the pipe, or -1 for an infinite timeout
118 @param mustNotExist if set to true, the method will fail if the pipe already exists
119 @returns true if the pipe was created, or false if it fails (e.g. if another process is
120 already using using the pipe)
121 */
122 bool createPipe (const String& pipeName, int pipeReceiveMessageTimeoutMs, bool mustNotExist = false);
123
124 /** Disconnects and closes any currently-open sockets or pipes. */
125 void disconnect();
126
127 /** True if a socket or pipe is currently active. */
128 bool isConnected() const;
129
130 /** Returns the socket that this connection is using (or nullptr if it uses a pipe). */
131 StreamingSocket* getSocket() const noexcept { return socket.get(); }
132
133 /** Returns the pipe that this connection is using (or nullptr if it uses a socket). */
134 NamedPipe* getPipe() const noexcept { return pipe.get(); }
135
136 /** Returns the name of the machine at the other end of this connection.
137 This may return an empty string if the name is unknown.
138 */
139 String getConnectedHostName() const;
140
141 //==============================================================================
142 /** Tries to send a message to the other end of this connection.
143
144 This will fail if it's not connected, or if there's some kind of write error. If
145 it succeeds, the connection object at the other end will receive the message by
146 a callback to its messageReceived() method.
147
148 @see messageReceived
149 */
150 bool sendMessage (const MemoryBlock& message);
151
152 //==============================================================================
153 /** Called when the connection is first connected.
154
155 If the connection was created with the callbacksOnMessageThread flag set, then
156 this will be called on the message thread; otherwise it will be called on a server
157 thread.
158 */
159 virtual void connectionMade() = 0;
160
161 /** Called when the connection is broken.
162
163 If the connection was created with the callbacksOnMessageThread flag set, then
164 this will be called on the message thread; otherwise it will be called on a server
165 thread.
166 */
167 virtual void connectionLost() = 0;
168
169 /** Called when a message arrives.
170
171 When the object at the other end of this connection sends us a message with sendMessage(),
172 this callback is used to deliver it to us.
173
174 If the connection was created with the callbacksOnMessageThread flag set, then
175 this will be called on the message thread; otherwise it will be called on a server
176 thread.
177
178 @see sendMessage
179 */
180 virtual void messageReceived (const MemoryBlock& message) = 0;
181
182
183private:
184 //==============================================================================
185 CriticalSection pipeAndSocketLock;
186 std::unique_ptr<StreamingSocket> socket;
187 std::unique_ptr<NamedPipe> pipe;
188 bool callbackConnectionState = false;
189 const bool useMessageThread;
190 const uint32 magicMessageHeader;
191 int pipeReceiveMessageTimeout = -1;
192
193 friend class InterprocessConnectionServer;
194 void initialiseWithSocket (StreamingSocket*);
195 void initialiseWithPipe (NamedPipe*);
196 void deletePipeAndSocket();
197 void connectionMadeInt();
198 void connectionLostInt();
199 void deliverDataInt (const MemoryBlock&);
200 bool readNextMessage();
201 int readData (void*, int);
202
203 struct ConnectionThread;
204 std::unique_ptr<ConnectionThread> thread;
205 std::atomic<bool> threadIsRunning { false };
206
207 void runThread();
208 int writeData (void*, int);
209
210 JUCE_DECLARE_WEAK_REFERENCEABLE (InterprocessConnection)
211 JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (InterprocessConnection)
212};
213
214} // namespace juce
215
216/** @}*/
An object that waits for client sockets to connect to a port on this host, and creates InterprocessCo...
Manages a simple two-way messaging connection to another process, using either a socket or a named pi...
virtual void connectionMade()=0
Called when the connection is first connected.
virtual void messageReceived(const MemoryBlock &message)=0
Called when a message arrives.
StreamingSocket * getSocket() const noexcept
Returns the socket that this connection is using (or nullptr if it uses a pipe).
virtual void connectionLost()=0
Called when the connection is broken.
NamedPipe * getPipe() const noexcept
Returns the pipe that this connection is using (or nullptr if it uses a socket).
A class to hold a resizable block of raw data.
A cross-process pipe that can have data written to and read from it.
A wrapper for a streaming (TCP) socket.
Definition juce_Socket.h:42
The JUCE String class!
Definition juce_String.h:43
#define JUCE_API
This macro is added to all JUCE public class declarations.