juce::DatagramSocket Class Reference

A wrapper for a datagram (UDP) socket. More...

#include <juce_Socket.h>

Collaboration diagram for juce::DatagramSocket:

Public Member Functions
	DatagramSocket (bool enableBroadcasting=false)
	Creates a datagram socket. More...
	~DatagramSocket ()
	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...
int	getBoundPort () const noexcept
	Returns the local port number to which this socket is currently bound. More...
int	getRawSocketHandle () const noexcept
	Returns the OS's socket handle that's currently open. More...
bool	joinMulticast (const String &multicastIPAddress)
	Join a multicast group. More...
bool	leaveMulticast (const String &multicastIPAddress)
	Leave a multicast group. More...
int	read (void *destBuffer, int maxBytesToRead, bool blockUntilSpecifiedAmountHasArrived)
	Reads bytes from the socket. More...
int	read (void *destBuffer, int maxBytesToRead, bool blockUntilSpecifiedAmountHasArrived, String &senderIPAddress, int &senderPortNumber)
	Reads bytes from the socket and return the IP address of the sender. More...
bool	setEnablePortReuse (bool enabled)
	Allow other applications to re-use the port. More...
bool	setMulticastLoopbackEnabled (bool enableLoopback)
	Enables or disables multicast loopback. More...
void	shutdown ()
	Closes the underlying socket object. More...
int	waitUntilReady (bool readyForReading, int timeoutMsecs)
	Waits until the socket is ready for reading or writing. More...
int	write (const String &remoteHostname, int remotePortNumber, const void *sourceBuffer, int numBytesToWrite)
	Writes bytes to the socket from a buffer. More...

Private Attributes
std::atomic< int >	handle { -1 }
bool	isBound = false
String	lastBindAddress
void *	lastServerAddress = nullptr
String	lastServerHost
int	lastServerPort = -1
CriticalSection	readLock

Detailed Description

A wrapper for a datagram (UDP) 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

StreamingSocket, InterprocessConnection, InterprocessConnectionServer

@tags{Core}

Constructor & Destructor Documentation

DatagramSocket()

juce::DatagramSocket::DatagramSocket

(

bool

enableBroadcasting = false

)

Creates a datagram socket.

You first need to bind this socket to a port with bindToPort if you intend to read from this socket.

If enableBroadcasting is true, the socket will be allowed to send broadcast messages (may require extra privileges on linux)

~DatagramSocket()

juce::DatagramSocket::~DatagramSocket

(

)

Destructor.

Member Function Documentation

bindToPort() [1/2]

bool juce::DatagramSocket::bindToPort

(

int

localPortNumber

)

Binds the socket to the specified local port.

The localPortNumber is the port on which to bind this socket. If this value is 0, the port number is assigned by the operating system.

Returns

true on success; false may indicate that another socket is already bound on the same port

bindToPort() [2/2]

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

getBoundPort()

int juce::DatagramSocket::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 bindToPort was called with zero.

Returns

-1 if the socket didn't bind to any port yet or an error occurred

getRawSocketHandle()

int juce::DatagramSocket::getRawSocketHandle ( ) const

inlinenoexcept

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

References juce::gl::handle.

joinMulticast()

bool juce::DatagramSocket::joinMulticast

(

const String &

multicastIPAddress

)

Join a multicast group.

Returns

true if it succeeds

leaveMulticast()

bool juce::DatagramSocket::leaveMulticast

(

const String &

multicastIPAddress

)

Leave a multicast group.

Returns

true if it succeeds

read() [1/2]

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

read() [2/2]

int juce::DatagramSocket::read	(	void *	destBuffer,
		int	maxBytesToRead,
		bool	blockUntilSpecifiedAmountHasArrived,
		String &	senderIPAddress,
		int &	senderPortNumber
	)

Reads bytes from the socket and return the IP address of the sender.

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. On a successful result, the senderIPAddress value will be set to the IP of the sender

See also

waitUntilReady

setEnablePortReuse()

bool juce::DatagramSocket::setEnablePortReuse

(

bool

enabled

)

Allow other applications to re-use the port.

Allow any other application currently running to bind to the same port. Do not use this if your socket handles sensitive data as it could be read by any, possibly malicious, third-party apps.

Returns

true on success

setMulticastLoopbackEnabled()

bool juce::DatagramSocket::setMulticastLoopbackEnabled

(

bool

enableLoopback

)

Enables or disables multicast loopback.

Returns

true if it succeeds

shutdown()

void juce::DatagramSocket::shutdown

(

)

Closes the underlying socket object.

Closes the underlying socket object and aborts any read or write operations. Note that all other methods will return an error after this call and the object cannot be re-used.

This method is useful if another thread is blocking in a read/write call and you would like to abort the read/write thread. Simply deleting the socket object without calling shutdown may cause a race-condition where the read/write returns just before the socket is deleted and the subsequent read/write would try to read from an invalid pointer. By calling shutdown first, the socket object remains valid but all current and subsequent calls to read/write will return immediately.

waitUntilReady()

int juce::DatagramSocket::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::DatagramSocket::write	(	const String &	remoteHostname,
		int	remotePortNumber,
		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

handle

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

private

isBound

bool juce::DatagramSocket::isBound = false

private

lastBindAddress

String juce::DatagramSocket::lastBindAddress

private

lastServerAddress

void* juce::DatagramSocket::lastServerAddress = nullptr

private

lastServerHost

String juce::DatagramSocket::lastServerHost

private

lastServerPort

int juce::DatagramSocket::lastServerPort = -1

private

readLock

CriticalSection juce::DatagramSocket::readLock

mutableprivate

---

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

• juce_Socket.h