GstRTSPAddressPool

## GstRTSPAddressPool GstRTSPAddressPool — A pool of network addresses |

## Synopsis

    #define             GST_RTSP_ADDRESS_POOL_ANY_IPV4
    #define             GST_RTSP_ADDRESS_POOL_ANY_IPV6
    struct              GstRTSPAddress;
    enum                GstRTSPAddressFlags;
    GstRTSPAddress *    gst_rtsp_address_copy               (GstRTSPAddress *addr);
    void                gst_rtsp_address_free               (GstRTSPAddress *addr);

    struct              GstRTSPAddressPool;
    struct              GstRTSPAddressPoolClass;
    enum                GstRTSPAddressPoolResult;
    GstRTSPAddressPool * gst_rtsp_address_pool_new          (void);
    void                gst_rtsp_address_pool_clear         (GstRTSPAddressPool *pool);
    void                gst_rtsp_address_pool_dump          (GstRTSPAddressPool *pool);
    gboolean            gst_rtsp_address_pool_add_range     (GstRTSPAddressPool *pool,
                                                             const gchar *min_address,
                                                             const gchar *max_address,
                                                             guint16 min_port,
                                                             guint16 max_port,
                                                             guint8 ttl);
    gboolean            gst_rtsp_address_pool_has_unicast_addresses
                                                            (GstRTSPAddressPool *pool);
    GstRTSPAddress *    gst_rtsp_address_pool_acquire_address
                                                            (GstRTSPAddressPool *pool,
                                                             GstRTSPAddressFlags flags,
                                                             gint n_ports);
    GstRTSPAddressPoolResult gst_rtsp_address_pool_reserve_address
                                                            (GstRTSPAddressPool *pool,
                                                             const gchar *ip_address,
                                                             guint port,
                                                             guint n_ports,
                                                             guint ttl,
                                                             GstRTSPAddress **address);

## Description

The GstRTSPAddressPool is an object that maintains a collection of network addresses. It is used to allocate server ports and server multicast addresses but also to reserve client provided destination addresses.

A range of addresses can be added with `gst_rtsp_address_pool_add_range()`. Both multicast and unicast addresses can be added.

With `gst_rtsp_address_pool_acquire_address()` an unused address and port range can be acquired from the pool. With `gst_rtsp_address_pool_reserve_address()` a specific address can be retrieved. Both methods return a boxed GstRTSPAddress that should be freed with `gst_rtsp_address_free()` after usage, which brings the address back into the pool.

Last reviewed on 2013-07-16 (1.0.0)

## Details

### GST_RTSP_ADDRESS_POOL_ANY_IPV4

    #define GST_RTSP_ADDRESS_POOL_ANY_IPV4  "0.0.0.0"

Used with `gst_rtsp_address_pool_add_range()` to bind to all IPv4 addresses

### GST_RTSP_ADDRESS_POOL_ANY_IPV6

    #define GST_RTSP_ADDRESS_POOL_ANY_IPV6  "::"

Used with `gst_rtsp_address_pool_add_range()` to bind to all IPv6 addresses

### struct GstRTSPAddress

    struct GstRTSPAddress {
      GstRTSPAddressPool *pool;

      gchar *address;
      guint16 port;
      gint n_ports;
      guint8 ttl;
    };

An address

GstRTSPAddressPool *`pool`; | the GstRTSPAddressPool owner of this address
gchar *`address`; | the address
guint16 `port`; | the port number
gint `n_ports`; | number of ports
guint8 `ttl`; | TTL or 0 for unicast addresses

### enum GstRTSPAddressFlags

    typedef enum {
      GST_RTSP_ADDRESS_FLAG_NONE      = 0,
      GST_RTSP_ADDRESS_FLAG_IPV4      = (1 << 0),
      GST_RTSP_ADDRESS_FLAG_IPV6      = (1 << 1),
      GST_RTSP_ADDRESS_FLAG_EVEN_PORT = (1 << 2),
      GST_RTSP_ADDRESS_FLAG_MULTICAST = (1 << 3),
      GST_RTSP_ADDRESS_FLAG_UNICAST   = (1 << 4),
    } GstRTSPAddressFlags;

Flags used to control allocation of addresses

`GST_RTSP_ADDRESS_FLAG_NONE` | no flags
`GST_RTSP_ADDRESS_FLAG_IPV4` | an IPv4 address
`GST_RTSP_ADDRESS_FLAG_IPV6` | and IPv6 address
`GST_RTSP_ADDRESS_FLAG_EVEN_PORT` | address with an even port
`GST_RTSP_ADDRESS_FLAG_MULTICAST` | a multicast address
`GST_RTSP_ADDRESS_FLAG_UNICAST` | a unicast address

### gst_rtsp_address_copy ()

    GstRTSPAddress *    gst_rtsp_address_copy               (GstRTSPAddress *addr);

Make a copy of `addr`.

`addr` : | a GstRTSPAddress
Returns : | a copy of `addr`.

### gst_rtsp_address_free ()

    void                gst_rtsp_address_free               (GstRTSPAddress *addr);

Free `addr` and releasing it back into the pool when owned by a pool.

`addr` : | a GstRTSPAddress

### struct GstRTSPAddressPool

    struct GstRTSPAddressPool {
      GObject       parent;
    };

An address pool, all member are private

GObject `parent`; | the parent GObject

### struct GstRTSPAddressPoolClass

    struct GstRTSPAddressPoolClass {
      GObjectClass  parent_class;
    };

Opaque Address pool class.

### enum GstRTSPAddressPoolResult

    typedef enum {
      GST_RTSP_ADDRESS_POOL_OK         =  0,
      /* errors */
      GST_RTSP_ADDRESS_POOL_EINVAL     = -1,
      GST_RTSP_ADDRESS_POOL_ERESERVED  = -2,
      GST_RTSP_ADDRESS_POOL_ERANGE     = -3,

      GST_RTSP_ADDRESS_POOL_ELAST      = -4,
    } GstRTSPAddressPoolResult;

Result codes from RTSP address pool functions.

`GST_RTSP_ADDRESS_POOL_OK` | no error
`GST_RTSP_ADDRESS_POOL_EINVAL` | invalid arguments were provided to a function
`GST_RTSP_ADDRESS_POOL_ERESERVED` | the addres has already been reserved
`GST_RTSP_ADDRESS_POOL_ERANGE` | the address is not in the pool
`GST_RTSP_ADDRESS_POOL_ELAST` | last error

### gst_rtsp_address_pool_new ()

    GstRTSPAddressPool * gst_rtsp_address_pool_new          (void);

Make a new GstRTSPAddressPool.

Returns : | a new GstRTSPAddressPool

### gst_rtsp_address_pool_clear ()

    void                gst_rtsp_address_pool_clear         (GstRTSPAddressPool *pool);

Clear all addresses in `pool`. There should be no outstanding allocations.

`pool` : | a GstRTSPAddressPool

### gst_rtsp_address_pool_dump ()

    void                gst_rtsp_address_pool_dump          (GstRTSPAddressPool *pool);

Dump the free and allocated addresses to stdout.

`pool` : | a GstRTSPAddressPool

### gst_rtsp_address_pool_add_range ()

    gboolean            gst_rtsp_address_pool_add_range     (GstRTSPAddressPool *pool,
                                                             const gchar *min_address,
                                                             const gchar *max_address,
                                                             guint16 min_port,
                                                             guint16 max_port,
                                                             guint8 ttl);

Adds the addresses from `min_addess` to `max_address` (inclusive) to `pool`. The valid port range for the addresses will be from `min_port` to `max_port` inclusive.

When `ttl` is 0, `min_address` and `max_address` should be unicast addresses. `min_address` and `max_address` can be set to GST_RTSP_ADDRESS_POOL_ANY_IPV4 or GST_RTSP_ADDRESS_POOL_ANY_IPV6 to bind to all available IPv4 or IPv6 addresses.

When `ttl` > 0, `min_address` and `max_address` should be multicast addresses.

`pool` : | a GstRTSPAddressPool
`min_address` : | a minimum address to add
`max_address` : | a maximum address to add
`min_port` : | the minimum port
`max_port` : | the maximum port
`ttl` : | a TTL or 0 for unicast addresses
Returns : | `TRUE` if the addresses could be added.

### gst_rtsp_address_pool_has_unicast_addresses ()

    gboolean            gst_rtsp_address_pool_has_unicast_addresses
                                                            (GstRTSPAddressPool *pool);

Used to know if the pool includes any unicast addresses.

`pool` : | a GstRTSPAddressPool
Returns : | `TRUE` if the pool includes any unicast addresses, `FALSE` otherwise

### gst_rtsp_address_pool_acquire_address ()

    GstRTSPAddress *    gst_rtsp_address_pool_acquire_address
                                                            (GstRTSPAddressPool *pool,
                                                             GstRTSPAddressFlags flags,
                                                             gint n_ports);

Take an address and ports from `pool`. `flags` can be used to control the allocation. `n_ports` consecutive ports will be allocated of which the first one can be found in `port`.

`pool` : | a GstRTSPAddressPool
`flags` : | flags
`n_ports` : | the amount of ports
Returns : | a GstRTSPAddress that should be freed with gst_rtsp_address_free after use or `NULL` when no address could be acquired.

### gst_rtsp_address_pool_reserve_address ()

    GstRTSPAddressPoolResult gst_rtsp_address_pool_reserve_address
                                                            (GstRTSPAddressPool *pool,
                                                             const gchar *ip_address,
                                                             guint port,
                                                             guint n_ports,
                                                             guint ttl,
                                                             GstRTSPAddress **address);

Take a specific address and ports from `pool`. `n_ports` consecutive ports will be allocated of which the first one can be found in `port`.

If `ttl` is 0, `address` should be a unicast address. If `ttl` > 0, `address` should be a valid multicast address.

`pool` : | a GstRTSPAddressPool
`ip_address` : | The IP address to reserve
`port` : | The first port to reserve
`n_ports` : | The number of ports
`ttl` : | The requested ttl
`address` : | (out) storage for a GstRTSPAddress
Returns : | GST_RTSP_ADDRESS_POOL_OK if an address was reserved. The address is returned in `address` and should be freed with gst_rtsp_address_free after use.

## See Also

GstRTSPStream, GstRTSPStreamTransport