ICE: libnice Reference Manual

ICE

ICE — STUN ICE Usage

Stability Level

Stable, unless otherwise indicated

Functions

size_t	stun_usage_ice_conncheck_create ()
StunUsageIceReturn	stun_usage_ice_conncheck_process ()
StunUsageIceReturn	stun_usage_ice_conncheck_create_reply ()
uint32_t	stun_usage_ice_conncheck_priority ()
bool	stun_usage_ice_conncheck_use_candidate ()

Types and Values

enum	StunUsageIceCompatibility
enum	StunUsageIceReturn

Includes

#include <stun/usages/ice.h>

Description

The STUN ICE usage allows for easily creating and parsing STUN Binding requests and responses used for ICE connectivity checks. The API allows you to create a connectivity check message, parse a response or create a reply to an incoming connectivity check request.

Functions

stun_usage_ice_conncheck_create ()

size_t
stun_usage_ice_conncheck_create (StunAgent *agent,
                                 StunMessage *msg,
                                 uint8_t *buffer,
                                 size_t buffer_len,
                                 const uint8_t *username,
                                 const size_t username_len,
                                 const uint8_t *password,
                                 const size_t password_len,
                                 bool cand_use,
                                 bool controlling,
                                 uint32_t priority,
                                 uint64_t tie,
                                 const char *candidate_identifier,
                                 StunUsageIceCompatibility compatibility);

Builds an ICE connectivity check STUN message. If the compatibility is not STUN_USAGE_ICE_COMPATIBILITY_RFC5245, the cand_use , controlling , priority and tie arguments are not used. If the compatibility is not STUN_USAGE_ICE_COMPATIBILITY_MSICE2, the candidate_identifier argument is not used.

Parameters

agent	The StunAgent to use to build the request
msg	The StunMessage to build
buffer	The buffer to use for creating the StunMessage
buffer_len	The size of the `buffer`
username	The username to use in the request
username_len	The length of `username`
password	The key to use for building the MESSAGE-INTEGRITY
password_len	The length of `password`
cand_use	Set to `TRUE` to append the USE-CANDIDATE flag to the request
controlling	Set to `TRUE` if you are the controlling agent or set to `FALSE` if you are the controlled agent.
priority	The value of the PRIORITY attribute
tie	The value of the tie-breaker to put in the ICE-CONTROLLED or ICE-CONTROLLING attribute
candidate_identifier	The foundation value to put in the CANDIDATE-IDENTIFIER attribute
compatibility	The compatibility mode to use for building the conncheck request

Returns

The length of the message built.

stun_usage_ice_conncheck_process ()

StunUsageIceReturn
stun_usage_ice_conncheck_process (StunMessage *msg,
                                  struct sockaddr_storage *addr,
                                  socklen_t *addrlen,
                                  StunUsageIceCompatibility compatibility);

Process an ICE connectivity check STUN message and retrieve the mapped address from the message

Parameters

msg	The StunMessage to process
addr	A pointer to a sockaddr structure to fill with the mapped address that the STUN connectivity check response contains
addrlen	The length of `addr`
compatibility	The compatibility mode to use for processing the conncheck response

Returns

A StunUsageIceReturn value

stun_usage_ice_conncheck_create_reply ()

StunUsageIceReturn
stun_usage_ice_conncheck_create_reply (StunAgent *agent,
                                       StunMessage *req,
                                       StunMessage *msg,
                                       uint8_t *buf,
                                       size_t *plen,
                                       const struct sockaddr_storage *src,
                                       socklen_t srclen,
                                       bool *control,
                                       uint64_t tie,
                                       StunUsageIceCompatibility compatibility);

Tries to parse a STUN connectivity check request and builds a response accordingly.

In case of error, the msg is filled with the appropriate error response to be sent and the value of plen is set to the size of that message. If plen has a size of 0, then no error response should be sent.

Parameters

agent	The StunAgent to use to build the response
req	The original STUN request to reply to
msg	The StunMessage to build
buf	The buffer to use for creating the StunMessage
plen	A pointer containing the size of the `buffer` on input. Will contain the length of the message built on output.
src	A pointer to a sockaddr structure containing the source address from which the request was received. Will be used as the mapped address in the response
srclen	The length of `addr`
control	Set to `TRUE` if you are the controlling agent or set to `FALSE` if you are the controlled agent.
tie	The value of the tie-breaker to put in the ICE-CONTROLLED or ICE-CONTROLLING attribute
compatibility	The compatibility mode to use for building the conncheck response

Returns

A StunUsageIceReturn value

stun_usage_ice_conncheck_priority ()

uint32_t
stun_usage_ice_conncheck_priority (const StunMessage *msg);

Extracts the priority from a STUN message.

Parameters

msg

The StunMessage to parse

Returns

host byte order priority, or 0 if not specified.

stun_usage_ice_conncheck_use_candidate ()

bool
stun_usage_ice_conncheck_use_candidate
                               (const StunMessage *msg);

Extracts the USE-CANDIDATE attribute flag from a STUN message.

Parameters

msg

The StunMessage to parse

Returns

TRUE if the flag is set, FALSE if not.

Types and Values

enum StunUsageIceCompatibility

This enum defines which compatibility modes this ICE usage can use

STUN_USAGE_ICE_COMPATIBILITY_DRAFT19 and STUN_USAGE_ICE_COMPATIBILITY_WLM2009 are deprecated and should not be used in newly-written code. They are kept for compatibility reasons and represent the same compatibilities as STUN_USAGE_ICE_COMPATIBILITY_RFC5245 and STUN_USAGE_ICE_COMPATIBILITY_MSICE2 respectively.

Members

STUN_USAGE_ICE_COMPATIBILITY_RFC5245	The ICE compatibility with RFC 5245
STUN_USAGE_ICE_COMPATIBILITY_GOOGLE	The ICE compatibility with Google's implementation of ICE
STUN_USAGE_ICE_COMPATIBILITY_MSN	The ICE compatibility with MSN's implementation of ICE
STUN_USAGE_ICE_COMPATIBILITY_MSICE2	The ICE compatibility with [MS-ICE2] specification
STUN_USAGE_ICE_COMPATIBILITY_DRAFT19	The ICE compatibility with draft 19
STUN_USAGE_ICE_COMPATIBILITY_WLM2009	An alias for `STUN_USAGE_ICE_COMPATIBILITY_MSICE2`

enum StunUsageIceReturn

Return value of stun_usage_ice_conncheck_process() and stun_usage_ice_conncheck_create_reply() which allows you to see what status the function call returned.

Members

STUN_USAGE_ICE_RETURN_SUCCESS	The function succeeded
STUN_USAGE_ICE_RETURN_ERROR	There was an unspecified error
STUN_USAGE_ICE_RETURN_INVALID	The message is invalid for processing
STUN_USAGE_ICE_RETURN_ROLE_CONFLICT	A role conflict was detected
STUN_USAGE_ICE_RETURN_INVALID_REQUEST	The message is an not a request
STUN_USAGE_ICE_RETURN_INVALID_METHOD	The method of the request is invalid
STUN_USAGE_ICE_RETURN_MEMORY_ERROR	The buffer size is too small to hold the STUN reply
STUN_USAGE_ICE_RETURN_INVALID_ADDRESS	The mapped address argument has an invalid address family
STUN_USAGE_ICE_RETURN_NO_MAPPED_ADDRESS	The response is valid but no MAPPED-ADDRESS or XOR-MAPPED-ADDRESS attribute was found