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 
27 namespace juce
28 {
29 
30 class InterprocessConnectionServer;
31 class 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 {
56 public:
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. */
78  virtual ~InterprocessConnection();
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 
183 private:
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 /** @}*/
JUCE_API
#define JUCE_API
This macro is added to all JUCE public class declarations.
Definition: juce_StandardHeader.h:143
juce::InterprocessConnection
Manages a simple two-way messaging connection to another process, using either a socket or a named pi...
Definition: juce_InterprocessConnection.h:54
juce::StreamingSocket
A wrapper for a streaming (TCP) socket.
Definition: juce_Socket.h:41
juce::InterprocessConnectionServer
An object that waits for client sockets to connect to a port on this host, and creates InterprocessCo...
Definition: juce_InterprocessConnectionServer.h:43
juce::NamedPipe
A cross-process pipe that can have data written to and read from it.
Definition: juce_NamedPipe.h:40
juce::String
The JUCE String class!
Definition: juce_String.h:42
juce::InterprocessConnection::getSocket
StreamingSocket * getSocket() const noexcept
Returns the socket that this connection is using (or nullptr if it uses a pipe).
Definition: juce_InterprocessConnection.h:131
juce::CriticalSection
A re-entrant mutex.
Definition: juce_CriticalSection.h:46
juce::InterprocessConnection::getPipe
NamedPipe * getPipe() const noexcept
Returns the pipe that this connection is using (or nullptr if it uses a socket).
Definition: juce_InterprocessConnection.h:134
juce::MemoryBlock
A class to hold a resizable block of raw data.
Definition: juce_MemoryBlock.h:36