juce::InterprocessConnection Class Reference

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...
NamedPipe *	getPipe () const noexcept
	Returns the pipe that this connection is using (or nullptr if it uses a socket). More...
StreamingSocket *	getSocket () 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< NamedPipe >	pipe
ReadWriteLock	pipeAndSocketLock
int	pipeReceiveMessageTimeout = -1
std::shared_ptr< SafeAction >	safeAction
std::unique_ptr< StreamingSocket >	socket
std::unique_ptr< ConnectionThread >	thread
std::atomic< bool >	threadIsRunning { 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

enum juce::InterprocessConnection::Notify

strong

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

callbacksOnMessageThread	if 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.
magicMessageHeaderNumber	a 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

pipeName	the name to use for the pipe - this should be unique to your app
pipeReceiveMessageTimeoutMs	a 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

hostName	the host computer, either a network address or name
portNumber	the socket port number to try to connect to
timeOutMillisecs	how 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

pipeName	the name to use for the pipe - this should be unique to your app
pipeReceiveMessageTimeoutMs	a timeout length to be used when reading or writing to the pipe, or -1 for an infinite timeout
mustNotExist	if 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

timeoutMs	the time in ms to wait before killing the thread by force
notify	whether 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:

• juce_InterprocessConnection.h