UCL Common Library Reference
<<< Previous Page | Home | Up | Next Page >>>

# NETUDP

## Name

NETUDP -- A UDP interface for IPv4 and IPv6.

## Synopsis

    #include <net_udp.h>

    struct      socket_udp;
    int         udp_addr_valid                  (const char *addr);
    socket_udp* udp_init                        (const char *addr,
                                                 uint16_t rx_port,
                                                 uint16_t tx_port,
                                                 int ttl);
    socket_udp* udp_init_if                     (const char *addr,
                                                 const char *iface,
                                                 uint16_t rx_port,
                                                 uint16_t tx_port,
                                                 int ttl);
    void        udp_exit                        (socket_udp *s);
    int         udp_send                        (socket_udp *s,
                                                 char *buffer,
                                                 int buflen);
    int         udp_recv                        (socket_udp *s,
                                                 char *buffer,
                                                 int buflen);
    int         udp_select                      (struct timeval *timeout);
    void        udp_fd_zero                     (void);
    void        udp_fd_set                      (socket_udp *s);
    int         udp_fd_isset                    (socket_udp *s);
    const char* udp_host_addr                   (socket_udp *s);
    int         udp_fd                          (socket_udp *s);

## Description

These functions provide a unified interface for sending are receiving UDP datagrams over IPv4 and IPv6 networks.

For IPv6 addresses to work the common library must be built with IPv6 enabled. On UNIX, the configure script has an option `--enable-ip-v6` for this purpose. On Win32, there is a project configuration to use the Microsoft IPv6 stack when installed.

## Details

### struct socket_udp

    struct socket_udp;

An opaque data structure containing information for a UDP session.

### udp_addr_valid ()

    int         udp_addr_valid                  (const char *addr);

`addr` : | string representation of IPv4 or IPv6 network address.
Returns : | TRUE if `addr` is valid, FALSE otherwise.

### udp_init ()

    socket_udp* udp_init                        (const char *addr,
                                                 uint16_t rx_port,
                                                 uint16_t tx_port,
                                                 int ttl);

Creates a session for sending and receiving UDP datagrams over IP networks.

`addr` : | character string containing an IPv4 or IPv6 network address.
`rx_port` : | receive port.
`tx_port` : | transmit port.
`ttl` : | time-to-live value for transmitted packets.
Returns : | a pointer to a valid socket_udp structure on success, NULL otherwise.

### udp_init_if ()

    socket_udp* udp_init_if                     (const char *addr,
                                                 const char *iface,
                                                 uint16_t rx_port,
                                                 uint16_t tx_port,
                                                 int ttl);

Creates a session for sending and receiving UDP datagrams over IP networks. The session uses `iface` as the interface to send and receive datagrams on.

`addr` : | character string containing an IPv4 or IPv6 network address.
`iface` : | character string containing an interface name.
`rx_port` : | receive port.
`tx_port` : | transmit port.
`ttl` : | time-to-live value for transmitted packets.
Returns : | a pointer to a socket_udp structure on success, NULL otherwise.

### udp_exit ()

    void        udp_exit                        (socket_udp *s);

Closes UDP session.

`s` : | UDP session to be terminated.

### udp_send ()

    int         udp_send                        (socket_udp *s,
                                                 char *buffer,
                                                 int buflen);

Transmits a UDP datagram containing data from `buffer`.

`s` : | UDP session.
`buffer` : | pointer to buffer to be transmitted.
`buflen` : | length of `buffer`.
Returns : | 0 on success, -1 on failure.

### udp_recv ()

    int         udp_recv                        (socket_udp *s,
                                                 char *buffer,
                                                 int buflen);

Reads from datagram queue associated with UDP session.

`s` : | UDP session.
`buffer` : | buffer to read data into.
`buflen` : | length of `buffer`.
Returns : | number of bytes read, returns 0 if no data is available.

### udp_select ()

    int         udp_select                      (struct timeval *timeout);

Waits for data to arrive for UDP sessions.

`timeout` : | maximum period to wait for data to arrive.
Returns : | number of UDP sessions ready for reading.

### udp_fd_zero ()

    void        udp_fd_zero                     (void);

Clears file descriptor from set associated with UDP sessions (see select(2)).

### udp_fd_set ()

    void        udp_fd_set                      (socket_udp *s);

Adds file descriptor associated of `s` to set associated with UDP sessions.

`s` : | UDP session.

### udp_fd_isset ()

    int         udp_fd_isset                    (socket_udp *s);

Checks if file descriptor associated with UDP session is ready for reading. This function should be called after udp_select().

`s` : | UDP session.
Returns : | non-zero if set, zero otherwise.

### udp_host_addr ()

    const char* udp_host_addr                   (socket_udp *s);

`s` : | UDP session.
Returns : | character string containing network address associated with session `s`.

### udp_fd ()

    int         udp_fd                          (socket_udp *s);

This function allows applications to apply their own socketopt()'s and ioctl()'s to the UDP session.

`s` : | UDP session.
Returns : | file descriptor of socket used by session `s`.

<<< Previous Page | Home | Up | Next Page >>>
MD5 | RTP