ofDocsdocumentation addons ofxNetwork ofxUDPManager

ofxUDPManager

editEdit

UDP is a network protocol that is faster and less rigid in its packet transmission requirements. Unlike TCP, UDP has no notion of connections nor does it check to see if a packet has been successfuly recieved by the client. A UDP socket can receive datagrams from any server on the network and send datagrams to any host on the network. In addition, datagrams may arrive in any order, never arrive at all, or be duplicated in transit. There are three modes of UDP servers: socket (aka unicast), broadcast, and multicast.

Unicast refers to a unique host-client. This is a one-to one connection between the client and the server

Multicast is the delivery of a message or information to a group of destination computers simultaneously in a single transmission. A packet sent to a unicast or broadcast address is only delivered to the host identified by that address. To the contrary, when packet is send to a multicast address, all interfaces identified by that address receive the data. However, multicast has the drawback that it is not well supported by routers and NAT.

Broadcast allows you to call every host within a subnet. It's like Multicast but doesn't require that your network infrastructure support it.

A very simple unicast server looks like this:


void ofApp::setup()
{

	//create the socket and set to send to 127.0.0.1:11999
	udpConnection.Create();
	udpConnection.Connect("127.0.0.1",11999);
	udpConnection.SetNonBlocking(true);
}

void ofApp::keyPressed(int key)
{
	string message = "You pressed a key";
	udpConnection.Send(message.c_str(), message.length());
}

A very simple unicast client looks like this:


void ofApp::setup()
{

	//create the socket and bind to port 11999
	udpConnection.Create();
	udpConnection.Bind(11999);
	udpConnection.SetNonBlocking(true);
}

void ofApp::update()
{
	char udpMessage[1000];
	udpConnection.Receive(udpMessage,1000);
	string message=udpMessage;
}

Notice that these are quite different than the creation of TCP servers and clients which you might be more familiar with.

The basic usage of UDP for socket servers and clients looks like so:

UDP Socket Server (sending):

  1. Create() - initialize the server
  2. Connect() - connect to an IP and a Port that you'll be sending messages on
  3. Send() - send the message

UDP Socket Client (receiving):

  1. Create() - intialize the client
  2. Bind() - bind the client to a port and listen for any UDP messages on that port
  3. Receive() - receive any data broadcast over UDP on the port set up to receive on

The basic usage of UDP for multicast looks like so:

UDP Multicast (sending):

  1. Create() - initialize the server
  2. ConnectMcast() - connect to an IP and a Port that you'll broadcast on
  3. Send() - send a message to any listening clients

UDP Multicast (receiving):

  1. Create() - initialize the client
  2. BindMcast() - bind to a port
  3. Receive() - check to see if any data has been received

Bind( ... )

bool Bind(unsigned short usPort)

Bind a port to receive socket/unicast UDP:

udpConnection.Create();
udpConnection.Bind(11999);
udpConnection.SetNonBlocking(true);

BindMcast( ... )

bool BindMcast(char *pMcast, unsigned short usPort)

Bind to multicast address to receive data:

udpConnection.Create();
udpConnection.BindMcast("224.0.0.1", 11999);

Close( )

bool Close()

Stop listening on a given port. Works with both socket and multicast.

Connect( ... )

bool Connect(const char *pHost, unsigned short usPort)

Connect to a socket client to send information.


udpConnection.Create();
udpConnection.Connect("127.0.0.1",11999);
udpConnection.SetNonBlocking(true);

ConnectMcast( ... )

bool ConnectMcast(char *pMcast, unsigned short usPort)

Connect to a multicast address.


udpConnection.Create();
udpConnection.Connect("224.0.0.1",11999);

Create( )

bool Create()

Create the UDP manager. Must be called before binding to any IP or sockets.

GetListenAddr( ... )

bool GetListenAddr(string &address, int &port)

GetMaxMsgSize( )

int GetMaxMsgSize()

GetReceiveBufferSize( )

int GetReceiveBufferSize()

Get the size of the receive buffer. The minimum (doubled) value for this option is 256. The max is determined by your OS.

GetRemoteAddr( ... )

bool GetRemoteAddr(string &address, int &port)

Returns the dots and numbers remote address in a string,

GetSendBufferSize( )

int GetSendBufferSize()

Get the size of the send buffer. The minimum (doubled) value for this option is 256. The max is determined by your OS.

GetTTL( )

int GetTTL()

returns -1 on failure

GetTimeoutReceive( )

int GetTimeoutReceive()

Return the current receive timeout.

GetTimeoutSend( )

int GetTimeoutSend()

Return the current send timeout.

HasSocket( )

bool HasSocket()

PeekReceive( )

int PeekReceive()

Receive( ... )

int Receive(char *pBuff, const int iSize)

Receives a message to a buffer of size iSize. Receive() returns the number of bytes actually received.

char udpMessage[100000];
udpConnection.Receive(udpMessage,100000);
string message=udpMessage;

Send( ... )

int Send(const char *pBuff, const int iSize)

Send a char* of data with length of iSize to all listeners.

string message = "A message";
udpConnection.Send(message.c_str(),message.length());

SendAll( ... )

int SendAll(const char *pBuff, const int iSize)

The SendAll() method is useful for extremely large data objects that may need multiple sendto() calls to actually be completely.

SetEnableBroadcast( ... )

bool SetEnableBroadcast(bool enableBroadcast)

Broadcast allows sending of packets to a particular network layer. If you're only using a single local network without a large number of attached machines, using broadcast may make more sense than trying to use multicast.

SetNonBlocking( ... )

bool SetNonBlocking(bool useNonBlocking)

Determines whether calls to send or receive are allowed to block their thread until they've completed. If your network infrastructure is time critical, then this may be a good choice. Usually though, you should leave it off.

SetReceiveBufferSize( ... )

bool SetReceiveBufferSize(int sizeInByte)

Set the size of the receive buffer. The minimum (doubled) value for this option is 256. The max is determined by your OS.

SetReuseAddress( ... )

bool SetReuseAddress(bool allowReuse)

SetSendBufferSize( ... )

bool SetSendBufferSize(int sizeInByte)

Set the size of the send buffer. The minimum (doubled) value for this option is 256. The max is determined by your OS.

SetTTL( ... )

bool SetTTL(int nTTL)

The TTL (Time To Live) field in the IP header has a double significance in multicast. As always, it controls the live time of the datagram to avoid it being looped forever due to routing errors. Routers decrement the TTL of every datagram as it traverses from one network to another and when its value reaches 0 the packet is dropped.

A list of TTL thresholds and their associated scope follows:

TTL Scope

0 Restricted to the same host. Won't be output by any interface. 1 Restricted to the same subnet. Won't be forwarded by a router. <32 Restricted to the same site, organization or department. <64 Restricted to the same region. <128 Restricted to the same continent. <255 Unrestricted in scope. Global.

SetTimeoutReceive( ... )

void SetTimeoutReceive(int timeoutInSeconds)

Set a timeout for any receive operations in seconds.

SetTimeoutSend( ... )

void SetTimeoutSend(int timeoutInSeconds)

Set a timeout for any send operations in seconds.

Setup( ... )

bool Setup(const ofxUDPSettings &settings)

WaitReceive( ... )

int WaitReceive(time_t timeoutSeconds, time_t timeoutMillis)

WaitSend( ... )

int WaitSend(time_t timeoutSeconds, time_t timeoutMillis)

ofxUDPManager( )

ofxUDPManager()

~ofxUDPManager( )

~ofxUDPManager()