## Bind Bind — STUN Binding Usage |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <stun/usages/bind.h>

    enum                StunUsageBindReturn;
    size_t              stun_usage_bind_create              (StunAgent *agent,
                                                             StunMessage *msg,
                                                             uint8_t *buffer,
                                                             size_t buffer_len);
    StunUsageBindReturn  stun_usage_bind_process            (StunMessage *msg,
                                                             struct sockaddr *addr,
                                                             socklen_t *addrlen,
                                                             struct sockaddr *alternate_server,
                                                             socklen_t *alternate_server_len);
    size_t              stun_usage_bind_keepalive           (StunAgent *agent,
                                                             StunMessage *msg,
                                                             uint8_t *buf,
                                                             size_t len);
    StunUsageBindReturn  stun_usage_bind_run                (const struct sockaddr *srv,
                                                             socklen_t srvlen,
                                                             struct sockaddr *addr,
                                                             socklen_t *addrlen);

## Description

The STUN Binding usage allows for easily creating and parsing STUN Binding requests and responses. It offers both an asynchronous and a synchronous API that uses the STUN timer usage.

## Details

### enum StunUsageBindReturn

    typedef enum {
      STUN_USAGE_BIND_RETURN_SUCCESS,
      STUN_USAGE_BIND_RETURN_ERROR,
      STUN_USAGE_BIND_RETURN_INVALID,
      STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER,
      STUN_USAGE_BIND_RETURN_TIMEOUT,
    } StunUsageBindReturn;

Return value of `stun_usage_bind_process()` and `stun_usage_bind_run()` which allows you to see what status the function call returned.

`STUN_USAGE_BIND_RETURN_SUCCESS` | The binding usage succeeded
`STUN_USAGE_BIND_RETURN_ERROR` | There was an unknown error in the bind usage
`STUN_USAGE_BIND_RETURN_INVALID` | The message is invalid and should be ignored
`STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER` | The binding request has an ALTERNATE-SERVER attribute
`STUN_USAGE_BIND_RETURN_TIMEOUT` | The binding was unsuccessful because it has timed out.

### stun_usage_bind_create ()

    size_t              stun_usage_bind_create              (StunAgent *agent,
                                                             StunMessage *msg,
                                                             uint8_t *buffer,
                                                             size_t buffer_len);

Create a new STUN binding request to use with a STUN server.

`agent` : | The StunAgent to use to create the binding request
`msg` : | The StunMessage to build
`buffer` : | The buffer to use for creating the StunMessage
`buffer_len` : | The size of the `buffer`
Returns : | The length of the built message.

### stun_usage_bind_process ()

    StunUsageBindReturn  stun_usage_bind_process            (StunMessage *msg,
                                                             struct sockaddr *addr,
                                                             socklen_t *addrlen,
                                                             struct sockaddr *alternate_server,
                                                             socklen_t *alternate_server_len);

Process a STUN binding response and extracts the mapped address from the STUN message. Also checks for the ALTERNATE-SERVER attribute.

`msg` : | The StunMessage to process
`addr` : | A pointer to a sockaddr structure to fill with the mapped address that the STUN server gives us
`addrlen` : | The length of `add`. rMust be set to the size of the `addr` socket address and will be set to the actual length of the socket address.
`alternate_server` : | A pointer to a sockaddr structure to fill with the address of an alternate server to which we should send our new STUN binding request, in case the currently used STUN server is requesting the use of an alternate server. This argument will only be filled if the return value of the function is STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER
`alternate_server_len` : | The length of `alternate_server`. Must be set to the size of the `alternate_server` socket address and will be set to the actual length of the socket address.
Returns : | A StunUsageBindReturn value. Note that STUN_USAGE_BIND_RETURN_TIMEOUT cannot be returned by this function

### stun_usage_bind_keepalive ()

    size_t              stun_usage_bind_keepalive           (StunAgent *agent,
                                                             StunMessage *msg,
                                                             uint8_t *buf,
                                                             size_t len);

Creates a STUN binding indication that can be used for a keepalive. Since this is an indication message, no STUN response will be generated and it can only be used as a keepalive message.

`agent` : | The StunAgent to use to build the message
`msg` : | The StunMessage to build
`buf` : | The buffer to use for creating the StunMessage
`len` : | The size of the `buf`
Returns : | The length of the message to send

### stun_usage_bind_run ()

    StunUsageBindReturn  stun_usage_bind_run                (const struct sockaddr *srv,
                                                             socklen_t srvlen,
                                                             struct sockaddr *addr,
                                                             socklen_t *addrlen);

This is a convenience function that will do a synchronous Binding request to a server and wait for its answer. It will use the StunUsageTrans and StunUsageTimer usages to send the request and handle the response.

`srv` : | A pointer to the sockaddr structure representing the STUN server's address
`srvlen` : | The length of `srv`
`addr` : | A pointer to a sockaddr structure to fill with the mapped address that the STUN server gives us
`addrlen` : | The length of `addr`
Returns : | A StunUsageBindReturn. Possible return values are STUN_USAGE_BIND_RETURN_SUCCESS, STUN_USAGE_BIND_RETURN_ERROR and STUN_USAGE_BIND_RETURN_TIMEOUT