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

port	The 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

address	The IP address to listen on.
port	The 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

d	The datagram object to destroy.

int datagram_recv	(	struct datagram *	d,
		char *	data,
		int	length,
		char *	addr,
		int *	port,
		int	timeout
	)

Receive a datagram.

Parameters

d	The datagram object.
data	Where to store the received message.
length	The length of the buffer, typically DATAGRAM_PAYLOAD_MAX.
addr	Pointer to a string of at least DATAGRAM_ADDRESS_MAX characters, which will be filled in with the IP address of the sender.
port	Pointer to an integer which will be filled in with the port number of the sender.
timeout	Maximum 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

d	The datagram object.
data	The data to send.
length	The length of the datagram.
addr	The address of the recipient.
port	The 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

d	The datagram object.

Returns

The file descriptor associated with the underlying socket.