A wrapper for a streaming (TCP) socket. More...

#include <juce_Socket.h>

Collaboration diagram for StreamingSocket:

[legend]

Public Member Functions
	StreamingSocket ()
	Creates an uninitialised socket. More...

	~StreamingSocket ()
	Destructor. More...

bool	bindToPort (int localPortNumber)
	Binds the socket to the specified local port. More...

bool	bindToPort (int localPortNumber, const String &localAddress)
	Binds the socket to the specified local port and local address. More...

void	close ()
	Closes the connection. More...

bool	connect (const String &remoteHostname, int remotePortNumber, int timeOutMillisecs=3000)
	Tries to connect the socket to hostname:port. More...

bool	createListener (int portNumber, const String &localHostName=String())
	Puts this socket into "listener" mode. More...

int	getBoundPort () const noexcept
	Returns the local port number to which this socket is currently bound. More...

const String &	getHostName () const noexcept
	Returns the name of the currently connected host. More...

int	getPort () const noexcept
	Returns the port number that's currently open. More...

int	getRawSocketHandle () const noexcept
	Returns the OS's socket handle that's currently open. More...

bool	isConnected () const noexcept
	True if the socket is currently connected. More...

bool	isLocal () const noexcept
	True if the socket is connected to this machine rather than over the network. More...

int	read (void *destBuffer, int maxBytesToRead, bool blockUntilSpecifiedAmountHasArrived)
	Reads bytes from the socket. More...

StreamingSocket *	waitForNextConnection () const
	When in "listener" mode, this waits for a connection and spawns it as a new socket. More...

int	waitUntilReady (bool readyForReading, int timeoutMsecs) const
	Waits until the socket is ready for reading or writing. More...

int	write (const void *sourceBuffer, int numBytesToWrite)
	Writes bytes to the socket from a buffer. More...

Private Member Functions
	StreamingSocket (const String &hostname, int portNumber, int handle)

Private Attributes
bool	connected

int volatile	handle

String	hostName

bool	isListener

int volatile	portNumber

CriticalSection	readLock

Detailed Description

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 also: DatagramSocket, InterprocessConnection, InterprocessConnectionServer

Constructor & Destructor Documentation

◆ StreamingSocket() [1/2]

StreamingSocket::StreamingSocket ( )

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()

StreamingSocket::~StreamingSocket ( )

Destructor.

◆ StreamingSocket() [2/2]

StreamingSocket::StreamingSocket	(	const String &	hostname,
		int	portNumber,
		int	handle
	)

private

Member Function Documentation

◆ bindToPort() [1/2]

bool StreamingSocket::bindToPort ( int localPortNumber )

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

◆ bindToPort() [2/2]

bool StreamingSocket::bindToPort	(	int	localPortNumber,
		const String &	localAddress
	)

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 also: bindToPort(int localPortNumber), IPAddress::findAllAddresses

◆ close()

void StreamingSocket::close ( )

Closes the connection.

◆ connect()

bool StreamingSocket::connect	(	const String &	remoteHostname,
		int	remotePortNumber,
		int	timeOutMillisecs = `3000`
	)

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 also: isConnected

◆ createListener()

bool StreamingSocket::createListener	(	int	portNumber,
		const String &	localHostName = `String()`
	)

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.

Parameters

portNumber	the port number to listen on
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 also: waitForNextConnection

◆ getBoundPort()

int StreamingSocket::getBoundPort ( ) const

noexcept

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.

◆ getHostName()

const String& StreamingSocket::getHostName ( ) const

inlinenoexcept

Returns the name of the currently connected host.

◆ getPort()

int StreamingSocket::getPort ( ) const

inlinenoexcept

Returns the port number that's currently open.

◆ getRawSocketHandle()

int StreamingSocket::getRawSocketHandle ( ) const

inlinenoexcept

Returns the OS's socket handle that's currently open.

◆ isConnected()

bool StreamingSocket::isConnected ( ) const

inlinenoexcept

True if the socket is currently connected.

◆ isLocal()

bool StreamingSocket::isLocal ( ) const

noexcept

True if the socket is connected to this machine rather than over the network.

◆ read()

int StreamingSocket::read	(	void *	destBuffer,
		int	maxBytesToRead,
		bool	blockUntilSpecifiedAmountHasArrived
	)

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 also: waitUntilReady

◆ waitForNextConnection()

StreamingSocket* StreamingSocket::waitForNextConnection ( ) const

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 also: createListener

◆ waitUntilReady()

int StreamingSocket::waitUntilReady	(	bool	readyForReading,
		int	timeoutMsecs
	)		const

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.

◆ write()

int StreamingSocket::write	(	const void *	sourceBuffer,
		int	numBytesToWrite
	)

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.

Member Data Documentation

◆ connected

bool StreamingSocket::connected

private

◆ handle

int volatile StreamingSocket::handle

private

◆ hostName

String StreamingSocket::hostName

private

◆ isListener

bool StreamingSocket::isListener

private

◆ portNumber

int volatile StreamingSocket::portNumber

private

◆ readLock

CriticalSection StreamingSocket::readLock

mutableprivate

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

juce_Socket.h

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ StreamingSocket() [1/2]

◆ ~StreamingSocket()

◆ StreamingSocket() [2/2]

Member Function Documentation

◆ bindToPort() [1/2]

◆ bindToPort() [2/2]

◆ close()

◆ connect()

◆ createListener()

◆ getBoundPort()

◆ getHostName()

◆ getPort()

◆ getRawSocketHandle()

◆ isConnected()

◆ isLocal()

◆ read()

◆ waitForNextConnection()

◆ waitUntilReady()

◆ write()

Member Data Documentation

◆ connected

◆ handle

◆ hostName

◆ isListener

◆ portNumber

◆ readLock