JUCE  v6.1.6 (6.0.8-1114)
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::InterprocessConnection Class Referenceabstract

Manages a simple two-way messaging connection to another process, using either a socket or a named pipe as the transport medium. More...

#include <juce_InterprocessConnection.h>

Collaboration diagram for juce::InterprocessConnection:

Public Types

enum  Notify {
  Notify::no,
  Notify::yes
}
 Whether the disconnect call should trigger callbacks. More...
 

Public Member Functions

 InterprocessConnection (bool callbacksOnMessageThread=true, uint32 magicMessageHeaderNumber=0xf2b49e2c)
 Creates a connection. More...
 
virtual ~InterprocessConnection ()
 Destructor. More...
 
virtual void connectionLost ()=0
 Called when the connection is broken. More...
 
virtual void connectionMade ()=0
 Called when the connection is first connected. More...
 
bool connectToPipe (const String &pipeName, int pipeReceiveMessageTimeoutMs)
 Tries to connect the object to an existing named pipe. More...
 
bool connectToSocket (const String &hostName, int portNumber, int timeOutMillisecs)
 Tries to connect this object to a socket. More...
 
bool createPipe (const String &pipeName, int pipeReceiveMessageTimeoutMs, bool mustNotExist=false)
 Tries to create a new pipe for other processes to connect to. More...
 
void disconnect (int timeoutMs=-1, Notify notify=Notify::yes)
 Disconnects and closes any currently-open sockets or pipes. More...
 
String getConnectedHostName () const
 Returns the name of the machine at the other end of this connection. More...
 
NamedPipegetPipe () const noexcept
 Returns the pipe that this connection is using (or nullptr if it uses a socket). More...
 
StreamingSocketgetSocket () const noexcept
 Returns the socket that this connection is using (or nullptr if it uses a pipe). More...
 
bool isConnected () const
 True if a socket or pipe is currently active. More...
 
virtual void messageReceived (const MemoryBlock &message)=0
 Called when a message arrives. More...
 
bool sendMessage (const MemoryBlock &message)
 Tries to send a message to the other end of this connection. More...
 

Private Member Functions

void connectionLostInt ()
 
void connectionMadeInt ()
 
void deletePipeAndSocket ()
 
void deliverDataInt (const MemoryBlock &)
 
void initialise ()
 
void initialiseWithPipe (std::unique_ptr< NamedPipe >)
 
void initialiseWithSocket (std::unique_ptr< StreamingSocket >)
 
int readData (void *, int)
 
bool readNextMessage ()
 
void runThread ()
 
int writeData (void *, int)
 

Private Attributes

bool callbackConnectionState = false
 
const uint32 magicMessageHeader
 
std::unique_ptr< NamedPipepipe
 
ReadWriteLock pipeAndSocketLock
 
int pipeReceiveMessageTimeout = -1
 
std::shared_ptr< SafeAction > safeAction
 
std::unique_ptr< StreamingSocketsocket
 
std::unique_ptr< ConnectionThread > thread
 
std::atomic< boolthreadIsRunning { false }
 
const bool useMessageThread
 

Friends

class InterprocessConnectionServer
 

Detailed Description

Manages a simple two-way messaging connection to another process, using either a socket or a named pipe as the transport medium.

To connect to a waiting socket or an open pipe, use the connectToSocket() or connectToPipe() methods. If this succeeds, messages can be sent to the other end, and incoming messages will result in a callback via the messageReceived() method.

To open a pipe and wait for another client to connect to it, use the createPipe() method.

To act as a socket server and create connections for one or more client, see the InterprocessConnectionServer class.

IMPORTANT NOTE: Your derived Connection class must call disconnect in its destructor in order to cancel any pending messages before the class is destroyed.

See also
InterprocessConnectionServer, Socket, NamedPipe

@tags{Events}

Member Enumeration Documentation

◆ Notify

Whether the disconnect call should trigger callbacks.

Enumerator
no 
yes 

Constructor & Destructor Documentation

◆ InterprocessConnection()

juce::InterprocessConnection::InterprocessConnection ( bool  callbacksOnMessageThread = true,
uint32  magicMessageHeaderNumber = 0xf2b49e2c 
)

Creates a connection.

Connections are created manually, connecting them with the connectToSocket() or connectToPipe() methods, or they are created automatically by a InterprocessConnectionServer when a client wants to connect.

Parameters
callbacksOnMessageThreadif true, callbacks to the connectionMade(), connectionLost() and messageReceived() methods will always be made using the message thread; if false, these will be called immediately on the connection's own thread.
magicMessageHeaderNumbera magic number to use in the header to check the validity of the data blocks being sent and received. This can be any number, but the sender and receiver must obviously use matching values or they won't recognise each other.

◆ ~InterprocessConnection()

virtual juce::InterprocessConnection::~InterprocessConnection ( )
virtual

Destructor.

Member Function Documentation

◆ connectionLost()

virtual void juce::InterprocessConnection::connectionLost ( )
pure virtual

Called when the connection is broken.

If the connection was created with the callbacksOnMessageThread flag set, then this will be called on the message thread; otherwise it will be called on a server thread.

◆ connectionLostInt()

void juce::InterprocessConnection::connectionLostInt ( )
private

◆ connectionMade()

virtual void juce::InterprocessConnection::connectionMade ( )
pure virtual

Called when the connection is first connected.

If the connection was created with the callbacksOnMessageThread flag set, then this will be called on the message thread; otherwise it will be called on a server thread.

◆ connectionMadeInt()

void juce::InterprocessConnection::connectionMadeInt ( )
private

◆ connectToPipe()

bool juce::InterprocessConnection::connectToPipe ( const String pipeName,
int  pipeReceiveMessageTimeoutMs 
)

Tries to connect the object to an existing named pipe.

For this to work, another process on the same computer must already have opened an InterprocessConnection object and used createPipe() to create a pipe for this to connect to.

Parameters
pipeNamethe name to use for the pipe - this should be unique to your app
pipeReceiveMessageTimeoutMsa timeout length to be used when reading or writing to the pipe, or -1 for an infinite timeout.
Returns
true if it connects successfully.
See also
createPipe, NamedPipe

◆ connectToSocket()

bool juce::InterprocessConnection::connectToSocket ( const String hostName,
int  portNumber,
int  timeOutMillisecs 
)

Tries to connect this object to a socket.

For this to work, the machine on the other end needs to have a InterprocessConnectionServer object waiting to receive client connections on this port number.

Parameters
hostNamethe host computer, either a network address or name
portNumberthe socket port number to try to connect to
timeOutMillisecshow long to keep trying before giving up
Returns
true if the connection is established successfully
See also
Socket

◆ createPipe()

bool juce::InterprocessConnection::createPipe ( const String pipeName,
int  pipeReceiveMessageTimeoutMs,
bool  mustNotExist = false 
)

Tries to create a new pipe for other processes to connect to.

This creates a pipe with the given name, so that other processes can use connectToPipe() to connect to the other end.

Parameters
pipeNamethe name to use for the pipe - this should be unique to your app
pipeReceiveMessageTimeoutMsa timeout length to be used when reading or writing to the pipe, or -1 for an infinite timeout
mustNotExistif set to true, the method will fail if the pipe already exists
Returns
true if the pipe was created, or false if it fails (e.g. if another process is already using the pipe)

◆ deletePipeAndSocket()

void juce::InterprocessConnection::deletePipeAndSocket ( )
private

◆ deliverDataInt()

void juce::InterprocessConnection::deliverDataInt ( const MemoryBlock )
private

◆ disconnect()

void juce::InterprocessConnection::disconnect ( int  timeoutMs = -1,
Notify  notify = Notify::yes 
)

Disconnects and closes any currently-open sockets or pipes.

Derived classes must call this in their destructors in order to avoid undefined behaviour.

Parameters
timeoutMsthe time in ms to wait before killing the thread by force
notifywhether or not to call connectionLost

◆ getConnectedHostName()

String juce::InterprocessConnection::getConnectedHostName ( ) const

Returns the name of the machine at the other end of this connection.

This may return an empty string if the name is unknown.

◆ getPipe()

NamedPipe* juce::InterprocessConnection::getPipe ( ) const
inlinenoexcept

Returns the pipe that this connection is using (or nullptr if it uses a socket).

◆ getSocket()

StreamingSocket* juce::InterprocessConnection::getSocket ( ) const
inlinenoexcept

Returns the socket that this connection is using (or nullptr if it uses a pipe).

◆ initialise()

void juce::InterprocessConnection::initialise ( )
private

◆ initialiseWithPipe()

void juce::InterprocessConnection::initialiseWithPipe ( std::unique_ptr< NamedPipe )
private

◆ initialiseWithSocket()

void juce::InterprocessConnection::initialiseWithSocket ( std::unique_ptr< StreamingSocket )
private

◆ isConnected()

bool juce::InterprocessConnection::isConnected ( ) const

True if a socket or pipe is currently active.

◆ messageReceived()

virtual void juce::InterprocessConnection::messageReceived ( const MemoryBlock message)
pure virtual

Called when a message arrives.

When the object at the other end of this connection sends us a message with sendMessage(), this callback is used to deliver it to us.

If the connection was created with the callbacksOnMessageThread flag set, then this will be called on the message thread; otherwise it will be called on a server thread.

See also
sendMessage

◆ readData()

int juce::InterprocessConnection::readData ( void *  ,
int   
)
private

◆ readNextMessage()

bool juce::InterprocessConnection::readNextMessage ( )
private

◆ runThread()

void juce::InterprocessConnection::runThread ( )
private

◆ sendMessage()

bool juce::InterprocessConnection::sendMessage ( const MemoryBlock message)

Tries to send a message to the other end of this connection.

This will fail if it's not connected, or if there's some kind of write error. If it succeeds, the connection object at the other end will receive the message by a callback to its messageReceived() method.

See also
messageReceived

◆ writeData()

int juce::InterprocessConnection::writeData ( void *  ,
int   
)
private

Friends And Related Function Documentation

◆ InterprocessConnectionServer

friend class InterprocessConnectionServer
friend

Member Data Documentation

◆ callbackConnectionState

bool juce::InterprocessConnection::callbackConnectionState = false
private

◆ magicMessageHeader

const uint32 juce::InterprocessConnection::magicMessageHeader
private

◆ pipe

std::unique_ptr<NamedPipe> juce::InterprocessConnection::pipe
private

◆ pipeAndSocketLock

ReadWriteLock juce::InterprocessConnection::pipeAndSocketLock
private

◆ pipeReceiveMessageTimeout

int juce::InterprocessConnection::pipeReceiveMessageTimeout = -1
private

◆ safeAction

std::shared_ptr<SafeAction> juce::InterprocessConnection::safeAction
private

◆ socket

std::unique_ptr<StreamingSocket> juce::InterprocessConnection::socket
private

◆ thread

std::unique_ptr<ConnectionThread> juce::InterprocessConnection::thread
private

◆ threadIsRunning

std::atomic<bool> juce::InterprocessConnection::threadIsRunning { false }
private

◆ useMessageThread

const bool juce::InterprocessConnection::useMessageThread
private

The documentation for this class was generated from the following file: