NAME

udp_session -- run an UDP service with sessions

SYNOPSIS

   #include <afblib/udp_session.h>

   typedef struct udp_connection {
      void* handle;
      void* global_handle;
      // ...
   } udp_connection;

   typedef void (*udp_connection_handler)(udp_connection* link);

   void run_udp_service(hostport hp,
      int timeout, unsigned int max_retries,
      udp_connection_handler open_handler,
      udp_connection_handler input_handler,
      udp_connection_handler close_handler,
      void* global_handle);

   bool write_to_udp_link(udp_connection* link, void* buf, size_t len);
   ssize_t read_from_udp_link(udp_connection* link, void* buf, size_t len);
   void close_udp_link(udp_connection* link);

DESCRIPTION

run_udp_service creates an UDP socket that listens on the given hostport and waits for incoming packets. Each packet to the main socket opens a new session which is responded to using a new port which is used throughout the session (as in the TFTP protocol, see RFC 1350).

On each incoming packet to the main socket, open_handler is invoked which is expected to read one incoming packet using read_from_udp_link. For each incoming packet for one of the session sockets, input_handler is invoked which is likewise expected to invoke read_from_udp_link. Packets may be sent using write_to_udp_link. These packets are retransmitted up to max_retries times if no response comes within the timeperiod of timeout milliseconds. If multiple packets are sent without responding packets, just the last packet passed to write_to_udp_link will be retransmitted.

Connections are considered closed when close_udp_link is called, one associated I/O operation fails, or when the number of retransmissions hits the maximal number of retries max_retries. Pending output packets will be sent but no further input accepted. As soon a connection is no longer in use, close_handler will be invoked, allowing it to free the resources associated with that connection link.

A connection link provides following fields:

handle

This field is initially null and may be freely used to maintain a pointer to a custom session object.

global_handle

This field depends on the global_handle parameter passed to run_udp_service.

run_udp_service runs normally infinitely and returns in error cases only.

AUTHOR

Andreas F. Borchert