cctools
Macros | Functions
datagram.h File Reference

UDP datagram communications. More...

Go to the source code of this file.

Macros

#define DATAGRAM_ADDRESS_MAX   48
 Maximum number of characters in a text formatted datagram address. More...
 
#define DATAGRAM_PAYLOAD_MAX   65536
 Maximum number of bytes in a datagram payload. More...
 
#define DATAGRAM_PORT_ANY   0
 Used to indicate any available port. More...
 
#define DATAGRAM_ADDRESS_BROADCAST   "255.255.255.255"
 The address to send to for broadcasting. More...
 

Functions

struct datagram * datagram_create (int port)
 Create a new port for sending or receiving datagrams. More...
 
struct datagram * datagram_create_address (const char *address, int port)
 Create a new address/port for sending or receiving datagrams. More...
 
void datagram_delete (struct datagram *d)
 Destroy a datagram port. More...
 
int datagram_recv (struct datagram *d, char *data, int length, char *addr, int *port, int timeout)
 Receive a datagram. More...
 
int datagram_send (struct datagram *d, const char *data, int length, const char *addr, int port)
 Send a datagram. More...
 
int datagram_fd (struct datagram *d)
 Obtain the file descriptor of a datagram object. More...
 

Detailed Description

UDP datagram communications.

This module implements datagram communications using UDP. A datagram is a small, fixed size message send to a given host and port, which is not guaranteed to arrive.

This module is arguably misnamed: A struct datagram does not represent a datagram, but rather an open port that can be used to send datagrams with datagram_send.

Example sender:

include "datagram.h"
include "debug.h"
const char *message = "hello world!";
const char *address = "192.168.2.1";
int port = 40000;
d = datagram_create(DATAGRAM_PORT_ANY);
if(!d) fatal("couldn't create datagram port");
datagram_send(d,message,strlen(message),address,port);

And an example receiver:

include "datagram.h"
include "debug.h"
char message[DATAGRAM_PAYLOAD_MAX];
char address[DATAGRAM_ADDRESS_MAX];
int  port = 40000;
d = datagram_create(port);
if(!d) fatal("couldn't create datagram port");
length = datagram_recv(d,message,sizeof(message),&address,&port,10000000);
if(length>0) {
        message[length] = 0;
        printf("got message: %s\n",message);
} else {
        printf("no message received.\n");
}

Macro Definition Documentation

#define DATAGRAM_ADDRESS_MAX   48

Maximum number of characters in a text formatted datagram address.

#define DATAGRAM_PAYLOAD_MAX   65536

Maximum number of bytes in a datagram payload.

#define DATAGRAM_PORT_ANY   0

Used to indicate any available port.

#define DATAGRAM_ADDRESS_BROADCAST   "255.255.255.255"

The address to send to for broadcasting.

Function Documentation

struct datagram* datagram_create ( int  port)

Create a new port for sending or receiving datagrams.

Parameters
portThe UDP port number to bind to. On most versions of Unix, an ordinary user can only bind to ports greater than 1024.
Returns
A new object for sending or receiving datagrams. On failure, returns null and sets errno appropriately. A very common error is EADDRINUSE, which indicates another process is already bound to that port.
struct datagram* datagram_create_address ( const char *  address,
int  port 
)

Create a new address/port for sending or receiving datagrams.

Parameters
addressThe IP address to listen on.
portThe UDP port number to bind to. On most versions of Unix, an ordinary user can only bind to ports greater than 1024.
Returns
A new object for sending or receiving datagrams. On failure, returns null and sets errno appropriately. A very common error is EADDRINUSE, which indicates another process is already bound to that port.
void datagram_delete ( struct datagram *  d)

Destroy a datagram port.

Parameters
dThe datagram object to destroy.
int datagram_recv ( struct datagram *  d,
char *  data,
int  length,
char *  addr,
int *  port,
int  timeout 
)

Receive a datagram.

Parameters
dThe datagram object.
dataWhere to store the received message.
lengthThe length of the buffer, typically DATAGRAM_PAYLOAD_MAX.
addrPointer to a string of at least DATAGRAM_ADDRESS_MAX characters, which will be filled in with the IP address of the sender.
portPointer to an integer which will be filled in with the port number of the sender.
timeoutMaximum time to wait, in microseconds.
Returns
On success, returns the number of bytes received. On failure, returns less than zero and sets errno appropriately.
int datagram_send ( struct datagram *  d,
const char *  data,
int  length,
const char *  addr,
int  port 
)

Send a datagram.

Parameters
dThe datagram object.
dataThe data to send.
lengthThe length of the datagram.
addrThe address of the recipient.
portThe port of the recipient.
Returns
On success, returns the number of bytes sent. On failure, returns less than zero and sets errno appropriately.
int datagram_fd ( struct datagram *  d)

Obtain the file descriptor of a datagram object.

Parameters
dThe datagram object.
Returns
The file descriptor associated with the underlying socket.