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

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

#include <juce_Socket.h>

Collaboration diagram for juce::StreamingSocket:

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 StringgetHostName () 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...
 
StreamingSocketwaitForNextConnection () const
 When in "listener" mode, this waits for a connection and spawns it as a new socket. More...
 
int waitUntilReady (bool readyForReading, int timeoutMsecs)
 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

std::atomic< boolconnected { false }
 
std::atomic< inthandle { -1 }
 
String hostName
 
std::atomic< boolisListener { false }
 
std::atomic< intportNumber { 0 }
 
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

@tags{Core}

Constructor & Destructor Documentation

◆ StreamingSocket() [1/2]

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

juce::StreamingSocket::~StreamingSocket ( )

Destructor.

◆ StreamingSocket() [2/2]

juce::StreamingSocket::StreamingSocket ( const String hostname,
int  portNumber,
int  handle 
)
private

Member Function Documentation

◆ bindToPort() [1/2]

bool juce::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 juce::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::getAllAddresses

◆ close()

void juce::StreamingSocket::close ( )

Closes the connection.

◆ connect()

bool juce::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, false if otherwise
See also
isConnected

◆ createListener()

bool juce::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
portNumberthe port number to listen on
localHostNamethe 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 juce::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& juce::StreamingSocket::getHostName ( ) const
inlinenoexcept

Returns the name of the currently connected host.

◆ getPort()

int juce::StreamingSocket::getPort ( ) const
inlinenoexcept

Returns the port number that's currently open.

◆ getRawSocketHandle()

int juce::StreamingSocket::getRawSocketHandle ( ) const
inlinenoexcept

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

References juce::gl::handle.

◆ isConnected()

bool juce::StreamingSocket::isConnected ( ) const
inlinenoexcept

True if the socket is currently connected.

◆ isLocal()

bool juce::StreamingSocket::isLocal ( ) const
noexcept

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

◆ read()

int juce::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* juce::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 juce::StreamingSocket::waitUntilReady ( bool  readyForReading,
int  timeoutMsecs 
)

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.

Returns
1 if the socket is ready on return, 0 if it times-out before the socket becomes ready, or -1 if an error occurs

◆ write()

int juce::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

std::atomic<bool> juce::StreamingSocket::connected { false }
private

◆ handle

std::atomic<int> juce::StreamingSocket::handle { -1 }
private

◆ hostName

String juce::StreamingSocket::hostName
private

◆ isListener

std::atomic<bool> juce::StreamingSocket::isListener { false }
private

◆ portNumber

std::atomic<int> juce::StreamingSocket::portNumber { 0 }
private

◆ readLock

CriticalSection juce::StreamingSocket::readLock
mutableprivate

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