StunMessage: libnice Reference Manual

## StunMessage StunMessage — STUN messages parsing and formatting functions |

## Stability Level

Stable, unless otherwise indicated

## Functions

bool | stun_message_init ()
uint16_t | stun_message_length ()
const void * | stun_message_find ()
StunMessageReturn | stun_message_find_flag ()
StunMessageReturn | stun_message_find32 ()
StunMessageReturn | stun_message_find64 ()
StunMessageReturn | stun_message_find_string ()
StunMessageReturn | stun_message_find_addr ()
StunMessageReturn | stun_message_find_xor_addr ()
StunMessageReturn | stun_message_find_xor_addr_full ()
StunMessageReturn | stun_message_find_error ()
void * | stun_message_append ()
StunMessageReturn | stun_message_append_bytes ()
StunMessageReturn | stun_message_append_flag ()
StunMessageReturn | stun_message_append32 ()
StunMessageReturn | stun_message_append64 ()
StunMessageReturn | stun_message_append_string ()
StunMessageReturn | stun_message_append_addr ()
StunMessageReturn | stun_message_append_xor_addr ()
StunMessageReturn | stun_message_append_xor_addr_full ()
StunMessageReturn | stun_message_append_error ()
int | stun_message_validate_buffer_length ()
ssize_t | stun_message_validate_buffer_length_fast ()
void | stun_message_id ()
StunClass | stun_message_get_class ()
StunMethod | stun_message_get_method ()
bool | stun_message_has_attribute ()
bool | stun_message_has_cookie ()
bool | stun_optional ()
const char * | stun_strerror ()

## Types and Values

struct | StunMessage
enum | StunClass
enum | StunMethod
enum | StunAttribute
typedef | StunTransactionId
enum | StunError
enum | StunMessageReturn
#define | STUN_MESSAGE_BUFFER_INCOMPLETE
#define | STUN_MESSAGE_BUFFER_INVALID
| StunInputVector

## Includes

    #include <stun/stunmessage.h>

## Description

The STUN Messages API allows you to create STUN messages easily as well as to parse existing messages.

## Functions

### stun_message_init ()

    bool
    stun_message_init (StunMessage *msg,
                       StunClass c,
                       StunMethod m,
                       const StunTransactionId id);

Initializes a STUN message buffer, with no attributes.

#### Parameters

msg | The StunMessage to initialize |
c | STUN message class (host byte order) |
m | STUN message method (host byte order) |
id | 16-bytes transaction ID |

#### Returns

`TRUE` if the initialization was successful

### stun_message_length ()

    uint16_t
    stun_message_length (const StunMessage *msg);

Get the length of the message (including the header)

#### Parameters

msg | The StunMessage |

#### Returns

The length of the message

### stun_message_find ()

    const void *
    stun_message_find (const StunMessage *msg,
                       StunAttribute type,
                       uint16_t *palen);

Finds an attribute in a STUN message and fetches its content

#### Parameters

msg | The StunMessage |
type | The StunAttribute to find |
palen | A pointer to store the length of the attribute |

#### Returns

A pointer to the start of the attribute payload if found, otherwise NULL.

### stun_message_find_flag ()

    StunMessageReturn
    stun_message_find_flag (const StunMessage *msg,
                            StunAttribute type);

Looks for a flag attribute within a valid STUN message.

#### Parameters

msg | The StunMessage |
type | The StunAttribute to find |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the attribute's size is not zero.

### stun_message_find32 ()

    StunMessageReturn
    stun_message_find32 (const StunMessage *msg,
                         StunAttribute type,
                         uint32_t *pval);

Extracts a 32-bits attribute from a STUN message.

#### Parameters

msg | The StunMessage |
type | The StunAttribute to find |
pval | A pointer where to store the value (host byte order) |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the attribute's size is not 4 bytes.

### stun_message_find64 ()

    StunMessageReturn
    stun_message_find64 (const StunMessage *msg,
                         StunAttribute type,
                         uint64_t *pval);

Extracts a 64-bits attribute from a STUN message.

#### Parameters

msg | The StunMessage |
type | The StunAttribute to find |
pval | A pointer where to store the value (host byte order) |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the attribute's size is not 8 bytes.

### stun_message_find_string ()

    StunMessageReturn
    stun_message_find_string (const StunMessage *msg,
                              StunAttribute type,
                              char *buf,
                              size_t buflen);

Extracts an UTF-8 string from a valid STUN message.

#### Parameters

msg | The StunMessage |
type | The StunAttribute to find |
buf | A pointer where to store the data |
buflen | The length of the buffer |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the attribute is improperly encoded `STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE` is return if the buffer size is too small to hold the string

The string will be nul-terminated.

### stun_message_find_addr ()

    StunMessageReturn
    stun_message_find_addr (const StunMessage *msg,
                            StunAttribute type,
                            struct sockaddr_storage *addr,
                            socklen_t *addrlen);

Extracts a network address attribute from a STUN message.

#### Parameters

msg | The StunMessage |
type | The StunAttribute to find |
addr | The sockaddr to be filled |
addrlen | The size of the `addr` variable. Must be set to the size of the `addr` socket address and will be set to the size of the extracted socket address. |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the attribute payload size is wrong or if the `addrlen` is too small `STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS` if the address family is unknown.

### stun_message_find_xor_addr ()

    StunMessageReturn
    stun_message_find_xor_addr (const StunMessage *msg,
                                StunAttribute type,
                                struct sockaddr_storage *addr,
                                socklen_t *addrlen);

Extracts an obfuscated network address attribute from a STUN message.

#### Parameters

msg | The StunMessage |
type | The StunAttribute to find |
addr | The sockaddr to be filled |
addrlen | The size of the `addr` variable. Must be set to the size of the `addr` socket address and will be set to the size of the extracted socket address. |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the attribute payload size is wrong or if the `addrlen` is too small `STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS` if the address family is unknown.

### stun_message_find_xor_addr_full ()

    StunMessageReturn
    stun_message_find_xor_addr_full (const StunMessage *msg,
                                     StunAttribute type,
                                     struct sockaddr_storage *addr,
                                     socklen_t *addrlen,
                                     uint32_t magic_cookie);

Extracts an obfuscated network address attribute from a STUN message.

#### Parameters

msg | The StunMessage |
type | The StunAttribute to find |
addr | The sockaddr to be filled |
addrlen | The size of the `addr` variable. Must be set to the size of the `addr` socket address and will be set to the size of the extracted socket address. |
magic_cookie | The magic cookie to use to XOR the address. |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the attribute payload size is wrong or if the `addrlen` is too small `STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS` if the address family is unknown.

### stun_message_find_error ()

    StunMessageReturn
    stun_message_find_error (const StunMessage *msg,
                             int *code);

Extract the error response code from a STUN message

#### Parameters

msg | The StunMessage |
code | A pointer where to store the value |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the value is invalid

### stun_message_append ()

    void *
    stun_message_append (StunMessage *msg,
                         StunAttribute type,
                         size_t length);

Reserves room for appending an attribute to an unfinished STUN message.

#### Parameters

msg | The StunMessage |
type | The StunAttribute to append |
length | The length of the attribute |

#### Returns

A pointer to an unitialized buffer of `length` bytes to where the attribute payload must be written, or NULL if there is not enough room in the STUN message buffer.

### stun_message_append_bytes ()

    StunMessageReturn
    stun_message_append_bytes (StunMessage *msg,
                               StunAttribute type,
                               const void *data,
                               size_t len);

Appends a binary value to a STUN message

#### Parameters

msg | The StunMessage |
type | The StunAttribute to append |
data | The data to append |
len | The length of the attribute |

#### Returns

A StunMessageReturn value.

### stun_message_append_flag ()

    StunMessageReturn
    stun_message_append_flag (StunMessage *msg,
                              StunAttribute type);

Appends an empty flag attribute to a STUN message

#### Parameters

msg | The StunMessage |
type | The StunAttribute to append |

#### Returns

A StunMessageReturn value.

### stun_message_append32 ()

    StunMessageReturn
    stun_message_append32 (StunMessage *msg,
                           StunAttribute type,
                           uint32_t value);

Appends a 32-bits value attribute to a STUN message

#### Parameters

msg | The StunMessage |
type | The StunAttribute to append |
value | The value to append (host byte order) |

#### Returns

A StunMessageReturn value.

### stun_message_append64 ()

    StunMessageReturn
    stun_message_append64 (StunMessage *msg,
                           StunAttribute type,
                           uint64_t value);

Appends a 64-bits value attribute to a STUN message

#### Parameters

msg | The StunMessage |
type | The StunAttribute to append |
value | The value to append (host byte order) |

#### Returns

A StunMessageReturn value.

### stun_message_append_string ()

    StunMessageReturn
    stun_message_append_string (StunMessage *msg,
                                StunAttribute type,
                                const char *str);

Adds an attribute from a nul-terminated string to a STUN message

#### Parameters

msg | The StunMessage |
type | The StunAttribute to append |
str | The string to append |

#### Returns

A StunMessageReturn value.

### stun_message_append_addr ()

    StunMessageReturn
    stun_message_append_addr (StunMessage *msg,
                              StunAttribute type,
                              const struct sockaddr *addr,
                              socklen_t addrlen);

Append a network address attribute to a STUN message

#### Parameters

msg | The StunMessage |
type | The StunAttribute to append |
addr | The sockaddr to be append |
addrlen | The size of the `addr` variable. |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the `addrlen` is too small `STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS` if the address family is unknown.

### stun_message_append_xor_addr ()

    StunMessageReturn
    stun_message_append_xor_addr (StunMessage *msg,
                                  StunAttribute type,
                                  const struct sockaddr_storage *addr,
                                  socklen_t addrlen);

Append an obfuscated network address attribute to a STUN message

#### Parameters

msg | The StunMessage |
type | The StunAttribute to append |
addr | The sockaddr to be append |
addrlen | The size of the `addr` variable. |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the `addrlen` is too small `STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS` if the address family is unknown.

### stun_message_append_xor_addr_full ()

    StunMessageReturn
    stun_message_append_xor_addr_full (StunMessage *msg,
                                       StunAttribute type,
                                       const struct sockaddr_storage *addr,
                                       socklen_t addrlen,
                                       uint32_t magic_cookie);

Append an obfuscated network address attribute from a STUN message.

#### Parameters

msg | The StunMessage |
type | The StunAttribute to append |
addr | The sockaddr to be append |
addrlen | The size of the `addr` variable. |
magic_cookie | The magic cookie to use to XOR the address. |

#### Returns

A StunMessageReturn value. `STUN_MESSAGE_RETURN_INVALID` is returned if the `addrlen` is too small `STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS` if the address family is unknown.

### stun_message_append_error ()

    StunMessageReturn
    stun_message_append_error (StunMessage *msg,
                               StunError code);

Appends the ERROR-CODE attribute to the STUN message and fills it according to code

#### Parameters

msg | The StunMessage |
code | The error code value |

#### Returns

A StunMessageReturn value.

### stun_message_validate_buffer_length ()

    int
    stun_message_validate_buffer_length (const uint8_t *msg,
                                         size_t length,
                                         bool has_padding);

This function will take a data buffer and will try to validate whether it is a STUN message or if it's not or if it's an incomplete STUN message and will provide us with the length of the STUN message.

#### Parameters

msg | The buffer to validate |
length | The length of the buffer |
has_padding | Set TRUE if attributes should be padded to multiple of 4 bytes |

#### Returns

The length of the valid STUN message in the buffer.

See also: STUN_MESSAGE_BUFFER_INCOMPLETE

See also: STUN_MESSAGE_BUFFER_INVALID

### stun_message_validate_buffer_length_fast ()

    ssize_t
    stun_message_validate_buffer_length_fast
                                   (StunInputVector *buffers,
                                    int n_buffers,
                                    size_t total_length,
                                    bool has_padding);

Quickly validate whether the message in the given `buffers` is potentially a valid STUN message, an incomplete STUN message, or if it’s definitely not one at all.

This is designed as a first-pass validation only, and does not check the message’s attributes for validity. If this function returns success, the buffers can be compacted and a more thorough validation can be performed using `stun_message_validate_buffer_length()`. If it fails, the buffers definitely do not contain a complete, valid STUN message.

#### Parameters

buffers | array of contiguous StunInputVectors containing already-received message data. | [array length=n_buffers][in caller-allocated]
n_buffers | number of entries in `buffers` or if -1 , then buffers is terminated by a StunInputVector with the buffer pointer being `NULL`. |
total_length | total number of valid bytes stored consecutively in `buffers` |
has_padding | `TRUE` if attributes should be padded to 4-byte boundaries |

#### Returns

The length of the valid STUN message in the buffer, or zero or -1 on failure

See also: STUN_MESSAGE_BUFFER_INCOMPLETE

See also: STUN_MESSAGE_BUFFER_INVALID

Since: 0.1.5

### stun_message_id ()

    void
    stun_message_id (const StunMessage *msg,
                     StunTransactionId id);

Retreive the STUN transaction id from a STUN message

#### Parameters

msg | The StunMessage |
id | The StunTransactionId to fill |

### stun_message_get_class ()

    StunClass
    stun_message_get_class (const StunMessage *msg);

Retreive the STUN class from a STUN message

#### Parameters

msg | The StunMessage |

#### Returns

The StunClass

### stun_message_get_method ()

    StunMethod
    stun_message_get_method (const StunMessage *msg);

Retreive the STUN method from a STUN message

#### Parameters

msg | The StunMessage |

#### Returns

The StunMethod

### stun_message_has_attribute ()

    bool
    stun_message_has_attribute (const StunMessage *msg,
                                StunAttribute type);

Checks if an attribute is present within a STUN message.

#### Parameters

msg | The StunMessage |
type | The StunAttribute to look for |

#### Returns

`TRUE` if the attribute is found, `FALSE` otherwise

### stun_message_has_cookie ()

    bool
    stun_message_has_cookie (const StunMessage *msg);

Checks if the STUN message has a RFC5389 compatible cookie

#### Parameters

msg | The StunMessage |

#### Returns

`TRUE` if the cookie is present, `FALSE` otherwise

### stun_optional ()

    bool
    stun_optional (uint16_t t);

Helper function that checks whether a STUN attribute is a mandatory or an optional attribute

#### Parameters

t | An attribute type |

#### Returns

`TRUE` if the attribute is an optional one

### stun_strerror ()

    const char *
    stun_strerror (StunError code);

Transforms a STUN error-code into a human readable string

#### Parameters

code | host-byte order error code |

#### Returns

A static pointer to a nul-terminated error message string.

## Types and Values

### struct StunMessage

    struct StunMessage {
      StunAgent *agent;
      uint8_t *buffer;
      size_t buffer_len;
      uint8_t *key;
      size_t key_len;
      uint8_t long_term_key[16];
      bool long_term_valid;
    };

This structure represents a STUN message

#### Members

StunAgent *`agent`; | The agent that created or validated this message |
uint8_t *`buffer`; | The buffer containing the STUN message |
size_t `buffer_len`; | The length of the buffer (not the size of the message) |
uint8_t *`key`; | The short term credentials key to use for authentication validation or that was used to finalize this message |
size_t `key_len`; | The length of the associated key |
uint8_t `long_term_key`[16]; | The long term credential key to use for authentication validation or that was used to finalize this message |
bool `long_term_valid`; | Whether or not the long_term_key variable contains valid data |

### enum StunClass

This enum is used to represent the class of a STUN message, as defined in RFC5389

#### Members

STUN_REQUEST | A STUN Request message |
STUN_INDICATION | A STUN indication message |
STUN_RESPONSE | A STUN Response message |
STUN_ERROR | A STUN Error message |

### enum StunMethod

This enum is used to represent the method of a STUN message, as defined by various RFCs

#### Members

STUN_BINDING | The Binding method as defined by the RFC5389 |
STUN_SHARED_SECRET | The Shared-Secret method as defined by the RFC3489 |
STUN_ALLOCATE | The Allocate method as defined by the TURN draft 12 |
STUN_SET_ACTIVE_DST | The Set-Active-Destination method as defined by the TURN draft 4 |
STUN_REFRESH | The Refresh method as defined by the TURN draft 12 |
STUN_SEND | The Send method as defined by the TURN draft 00 |
STUN_CONNECT | The Connect method as defined by the TURN draft 4 |
STUN_OLD_SET_ACTIVE_DST | The older Set-Active-Destination method as defined by the TURN draft 0 |
STUN_IND_SEND | The Send method used in indication messages as defined by the TURN draft 12 |
STUN_IND_DATA | The Data method used in indication messages as defined by the TURN draft 12 |
STUN_IND_CONNECT_STATUS | The Connect-Status method used in indication messages as defined by the TURN draft 4 |
STUN_CREATEPERMISSION | The CreatePermission method as defined by the TURN draft 12 |
STUN_CHANNELBIND | The ChannelBind method as defined by the TURN draft 12 |

### enum StunAttribute

Known STUN attribute types as defined by various RFCs and drafts

#### Members

STUN_ATTRIBUTE_MAPPED_ADDRESS | The MAPPED-ADDRESS attribute as defined by RFC5389 |
STUN_ATTRIBUTE_RESPONSE_ADDRESS | The RESPONSE-ADDRESS attribute as defined by RFC3489 |
STUN_ATTRIBUTE_CHANGE_REQUEST | The CHANGE-REQUEST attribute as defined by RFC3489 |
STUN_ATTRIBUTE_SOURCE_ADDRESS | The SOURCE-ADDRESS attribute as defined by RFC3489 |
STUN_ATTRIBUTE_CHANGED_ADDRESS | The CHANGED-ADDRESS attribute as defined by RFC3489 |
STUN_ATTRIBUTE_USERNAME | The USERNAME attribute as defined by RFC5389 |
STUN_ATTRIBUTE_PASSWORD | The PASSWORD attribute as defined by RFC3489 |
STUN_ATTRIBUTE_MESSAGE_INTEGRITY | The MESSAGE-INTEGRITY attribute as defined by RFC5389 |
STUN_ATTRIBUTE_ERROR_CODE | The ERROR-CODE attribute as defined by RFC5389 |
STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES | The UNKNOWN-ATTRIBUTES attribute as defined by RFC5389 |
STUN_ATTRIBUTE_REFLECTED_FROM | The REFLECTED-FROM attribute as defined by RFC3489 |
STUN_ATTRIBUTE_CHANNEL_NUMBER | The CHANNEL-NUMBER attribute as defined by TURN draft 09 and 12 |
STUN_ATTRIBUTE_LIFETIME | The LIFETIME attribute as defined by TURN draft 04, 09 and 12 |
STUN_ATTRIBUTE_MS_ALTERNATE_SERVER | The ALTERNATE-SERVER attribute as defined by [MS-TURN] |
STUN_ATTRIBUTE_MAGIC_COOKIE | The MAGIC-COOKIE attribute as defined by the rosenberg-midcom TURN draft 08 |
STUN_ATTRIBUTE_BANDWIDTH | The BANDWIDTH attribute as defined by TURN draft 04 |
STUN_ATTRIBUTE_DESTINATION_ADDRESS | The DESTINATION-ADDRESS attribute as defined by the rosenberg-midcom TURN draft 08 |
STUN_ATTRIBUTE_REMOTE_ADDRESS | The REMOTE-ADDRESS attribute as defined by TURN draft 04 |
STUN_ATTRIBUTE_PEER_ADDRESS | The PEER-ADDRESS attribute as defined by TURN draft 09 |
STUN_ATTRIBUTE_XOR_PEER_ADDRESS | The XOR-PEER-ADDRESS attribute as defined by TURN draft 12 |
STUN_ATTRIBUTE_DATA | The DATA attribute as defined by TURN draft 04, 09 and 12 |
STUN_ATTRIBUTE_REALM | The REALM attribute as defined by RFC5389 |
STUN_ATTRIBUTE_NONCE | The NONCE attribute as defined by RFC5389 |
STUN_ATTRIBUTE_RELAY_ADDRESS | The RELAY-ADDRESS attribute as defined by TURN draft 04 |
STUN_ATTRIBUTE_RELAYED_ADDRESS | The RELAYED-ADDRESS attribute as defined by TURN draft 09 |
STUN_ATTRIBUTE_XOR_RELAYED_ADDRESS | The XOR-RELAYED-ADDRESS attribute as defined by TURN draft 12 |
STUN_ATTRIBUTE_REQUESTED_ADDRESS_TYPE | The REQUESTED-ADDRESS-TYPE attribute as defined by TURN-IPV6 draft 05 |
STUN_ATTRIBUTE_REQUESTED_PORT_PROPS | The REQUESTED-PORT-PROPS attribute as defined by TURN draft 04 |
STUN_ATTRIBUTE_REQUESTED_PROPS | The REQUESTED-PROPS attribute as defined by TURN draft 09 |
STUN_ATTRIBUTE_EVEN_PORT | The EVEN-PORT attribute as defined by TURN draft 12 |
STUN_ATTRIBUTE_REQUESTED_TRANSPORT | The REQUESTED-TRANSPORT attribute as defined by TURN draft 12 |
STUN_ATTRIBUTE_DONT_FRAGMENT | The DONT-FRAGMENT attribute as defined by TURN draft 12 |
STUN_ATTRIBUTE_XOR_MAPPED_ADDRESS | The XOR-MAPPED-ADDRESS attribute as defined by RFC5389 |
STUN_ATTRIBUTE_TIMER_VAL | The TIMER-VAL attribute as defined by TURN draft 04 |
STUN_ATTRIBUTE_REQUESTED_IP | The REQUESTED-IP attribute as defined by TURN draft 04 |
STUN_ATTRIBUTE_RESERVATION_TOKEN | The RESERVATION-TOKEN attribute as defined by TURN draft 09 and 12 |
STUN_ATTRIBUTE_CONNECT_STAT | The CONNECT-STAT attribute as defined by TURN draft 04 |
STUN_ATTRIBUTE_PRIORITY | The PRIORITY attribute as defined by ICE draft 19 |
STUN_ATTRIBUTE_USE_CANDIDATE | The USE-CANDIDATE attribute as defined by ICE draft 19 |
STUN_ATTRIBUTE_OPTIONS | The OPTIONS optional attribute as defined by libjingle |
STUN_ATTRIBUTE_MS_VERSION | The MS-VERSION optional attribute as defined by [MS-TURN] |
STUN_ATTRIBUTE_MS_XOR_MAPPED_ADDRESS | The XOR-MAPPED-ADDRESS optional attribute as defined by [MS-TURN] |
STUN_ATTRIBUTE_SOFTWARE | The SOFTWARE optional attribute as defined by RFC5389 |
STUN_ATTRIBUTE_ALTERNATE_SERVER | The ALTERNATE-SERVER optional attribute as defined by RFC5389 |
STUN_ATTRIBUTE_FINGERPRINT | The FINGERPRINT optional attribute as defined by RFC5389 |
STUN_ATTRIBUTE_ICE_CONTROLLED | The ICE-CONTROLLED optional attribute as defined by ICE draft 19 |
STUN_ATTRIBUTE_ICE_CONTROLLING | The ICE-CONTROLLING optional attribute as defined by ICE draft 19 |
STUN_ATTRIBUTE_MS_SEQUENCE_NUMBER | The MS-SEQUENCE NUMBER optional attribute as defined by [MS-TURN] |
STUN_ATTRIBUTE_CANDIDATE_IDENTIFIER | The CANDIDATE-IDENTIFIER optional attribute as defined by [MS-ICE2] |
STUN_ATTRIBUTE_MS_IMPLEMENTATION_VERSION | The IMPLEMENTATION-VERSION optional attribute as defined by [MS-ICE2] |
STUN_ATTRIBUTE_NOMINATION | The NOMINATION attribute as defined by draft-thatcher-ice-renomination-00 and deployed in Google Chrome |

### StunTransactionId

    typedef uint8_t StunTransactionId[STUN_MESSAGE_TRANS_ID_LEN];

A type that holds a STUN transaction id.

### enum StunError

STUN error codes as defined by various RFCs and drafts

#### Members

STUN_ERROR_TRY_ALTERNATE | The ERROR-CODE value for the "Try Alternate" error as defined in RFC5389 |
STUN_ERROR_BAD_REQUEST | The ERROR-CODE value for the "Bad Request" error as defined in RFC5389 |
STUN_ERROR_UNAUTHORIZED | The ERROR-CODE value for the "Unauthorized" error as defined in RFC5389 |
STUN_ERROR_UNKNOWN_ATTRIBUTE | The ERROR-CODE value for the "Unknown Attribute" error as defined in RFC5389 |
STUN_ERROR_ALLOCATION_MISMATCH | The ERROR-CODE value for the "Allocation Mismatch" error as defined in TURN draft 12. Equivalent to the "No Binding" error defined in TURN draft 04. |
STUN_ERROR_STALE_NONCE | The ERROR-CODE value for the "Stale Nonce" error as defined in RFC5389 |
STUN_ERROR_ACT_DST_ALREADY | The ERROR-CODE value for the "Active Destination Already Set" error as defined in TURN draft 04. |
STUN_ERROR_UNSUPPORTED_FAMILY | The ERROR-CODE value for the "Address Family not Supported" error as defined in TURN IPV6 Draft 05. |
STUN_ERROR_WRONG_CREDENTIALS | The ERROR-CODE value for the "Wrong Credentials" error as defined in TURN Draft 12. |
STUN_ERROR_UNSUPPORTED_TRANSPORT | he ERROR-CODE value for the "Unsupported Transport Protocol" error as defined in TURN Draft 12. |
STUN_ERROR_INVALID_IP | The ERROR-CODE value for the "Invalid IP Address" error as defined in TURN draft 04. |
STUN_ERROR_INVALID_PORT | The ERROR-CODE value for the "Invalid Port" error as defined in TURN draft 04. |
STUN_ERROR_OP_TCP_ONLY | The ERROR-CODE value for the "Operation for TCP Only" error as defined in TURN draft 04. |
STUN_ERROR_CONN_ALREADY | The ERROR-CODE value for the "Connection Already Exists" error as defined in TURN draft 04. |
STUN_ERROR_ALLOCATION_QUOTA_REACHED | The ERROR-CODE value for the "Allocation Quota Reached" error as defined in TURN draft 12. |
STUN_ERROR_ROLE_CONFLICT | The ERROR-CODE value for the "Role Conflict" error as defined in ICE draft 19. |
STUN_ERROR_SERVER_ERROR | The ERROR-CODE value for the "Server Error" error as defined in RFC5389 |
STUN_ERROR_SERVER_CAPACITY | The ERROR-CODE value for the "Insufficient Capacity" error as defined in TURN draft 04. |
STUN_ERROR_INSUFFICIENT_CAPACITY | The ERROR-CODE value for the "Insufficient Capacity" error as defined in TURN draft 12. |
STUN_ERROR_MAX | The maximum possible ERROR-CODE value as defined by RFC 5389. |

### enum StunMessageReturn

The return value of most stun_message_* functions. This enum will report on whether an operation was successful or not and what error occured if any.

#### Members

STUN_MESSAGE_RETURN_SUCCESS | The operation was successful |
STUN_MESSAGE_RETURN_NOT_FOUND | The attribute was not found |
STUN_MESSAGE_RETURN_INVALID | The argument or data is invalid |
STUN_MESSAGE_RETURN_NOT_ENOUGH_SPACE | There is not enough space in the message to append data to it, or not enough in an argument to fill it with the data requested. |
STUN_MESSAGE_RETURN_UNSUPPORTED_ADDRESS | The address in the arguments or in the STUN message is not supported. |

### STUN_MESSAGE_BUFFER_INCOMPLETE

    #define STUN_MESSAGE_BUFFER_INCOMPLETE 0

Convenience macro for `stun_message_validate_buffer_length()` meaning that the data to validate does not hold a complete STUN message

### STUN_MESSAGE_BUFFER_INVALID

    #define STUN_MESSAGE_BUFFER_INVALID -1

Convenience macro for `stun_message_validate_buffer_length()` meaning that the data to validate is not a valid STUN message

### StunInputVector

    typedef struct {
      const uint8_t *buffer;
      size_t size;
    } StunInputVector;

Container for a single buffer which also stores its length. This is designed for vectored I/O: typically an array of StunInputVectors is passed to functions, providing multiple buffers which store logically contiguous received data.

This is guaranteed to be layed out identically in memory to GInputVector.

#### Members

const uint8_t *`buffer`; | a buffer containing already-received binary data |
size_t `size`; | length of `buffer` , in bytes |

Since: 0.1.5

## See Also

StunAgent