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.
#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.

## Functions

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

## 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

## DATAGRAM_ADDRESS_MAX

#define DATAGRAM_ADDRESS_MAX 48

Maximum number of characters in a text formatted datagram address.

## DATAGRAM_PAYLOAD_MAX

#define DATAGRAM_PAYLOAD_MAX 65536

Maximum number of bytes in a datagram payload.

## DATAGRAM_PORT_ANY

#define DATAGRAM_PORT_ANY 0

Used to indicate any available port.

## DATAGRAM_ADDRESS_BROADCAST

#define DATAGRAM_ADDRESS_BROADCAST "255.255.255.255"

The address to send to for broadcasting.

## Function Documentation

## datagram_create()

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.

## datagram_create_address()

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.

## datagram_delete()

void datagram_delete | ( | struct datagram * | d | ) |

Destroy a datagram port.

Parameters

  d | The datagram object to destroy.

## datagram_recv()

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.

## datagram_send()

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.

## datagram_fd()

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.