NiceCandidate: libnice Reference Manual

## NiceCandidate NiceCandidate — ICE candidate representation |

## Stability Level

Stable, unless otherwise indicated

## Functions

NiceCandidate * | nice_candidate_new ()
void | nice_candidate_free ()
NiceCandidate * | nice_candidate_copy ()
gboolean | nice_candidate_equal_target ()

## Types and Values

struct | NiceCandidate
enum | NiceCandidateType
enum | NiceCandidateTransport
struct | TurnServer
enum | NiceRelayType
#define | NICE_CANDIDATE_MAX_FOUNDATION
#define | NICE_CANDIDATE_MAX_TURN_SERVERS
#define | NICE_CANDIDATE_MAX_LOCAL_ADDRESSES

## Object Hierarchy

        GBoxed
        ╰── NiceCandidate
        GEnum
        ├── NiceCandidateTransport
        ├── NiceCandidateType
        ╰── NiceRelayType

## Description

A representation of an ICE candidate. Make sure you read the ICE drafts[1] to understand correctly the concept of ICE candidates.

[1] http://tools.ietf.org/wg/mmusic/draft-ietf-mmusic-ice/

## Functions

### nice_candidate_new ()

    NiceCandidate *
    nice_candidate_new (NiceCandidateType type);

Creates a new candidate. Must be freed with `nice_candidate_free()`

#### Parameters

type | The NiceCandidateType of the candidate to create |

#### Returns

A new NiceCandidate

### nice_candidate_free ()

    void
    nice_candidate_free (NiceCandidate *candidate);

Frees a NiceCandidate

#### Parameters

candidate | The candidate to free |

### nice_candidate_copy ()

    NiceCandidate *
    nice_candidate_copy (const NiceCandidate *candidate);

Makes a copy of a NiceCandidate

#### Parameters

candidate | The candidate to copy |

#### Returns

A new NiceCandidate, a copy of `candidate`

### nice_candidate_equal_target ()

    gboolean
    nice_candidate_equal_target (const NiceCandidate *candidate1,
                                 const NiceCandidate *candidate2);

Verifies that the candidates point to the same place, meaning they have the same transport and the same address. It ignores all other aspects.

#### Parameters

candidate1 | A candidate |
candidate2 | A candidate |

#### Returns

`TRUE` if the candidates point to the same place

Since: 0.1.15

## Types and Values

### struct NiceCandidate

    struct NiceCandidate {
      NiceCandidateType type;
      NiceCandidateTransport transport;
      NiceAddress addr;
      NiceAddress base_addr;
      guint32 priority;
      guint stream_id;
      guint component_id;
      gchar foundation[NICE_CANDIDATE_MAX_FOUNDATION];
      gchar *username;        /* pointer to a nul-terminated username string */
      gchar *password;        /* pointer to a nul-terminated password string */
      TurnServer *turn;
      gpointer sockptr;
      guint64 keepalive_next_tick; /* next tick timestamp */
    };

A structure to represent an ICE candidate

The `priority` is an integer as specified in the ICE draft 19. If you are using the MSN or the GOOGLE compatibility mode (which are based on ICE draft 6, which uses a floating point qvalue as priority), then the `priority` value will represent the qvalue multiplied by 1000.

#### Members

NiceCandidateType `type`; | The type of candidate |
NiceCandidateTransport `transport`; | The transport being used for the candidate |
NiceAddress `addr`; | The NiceAddress of the candidate |
NiceAddress `base_addr`; | The NiceAddress of the base address used by the candidate |
guint32 `priority`; | The priority of the candidate see note |
guint `stream_id`; | The ID of the stream to which belongs the candidate |
guint `component_id`; | The ID of the component to which belongs the candidate |
gchar `foundation`[NICE_CANDIDATE_MAX_FOUNDATION]; | The foundation of the candidate |
gchar *`username`; | The candidate-specific username to use (overrides the one set by `nice_agent_set_local_credentials()` or `nice_agent_set_remote_credentials()`) |
gchar *`password`; | The candidate-specific password to use (overrides the one set by `nice_agent_set_local_credentials()` or `nice_agent_set_remote_credentials()`) |
TurnServer *`turn`; | The TurnServer settings if the candidate is of type `NICE_CANDIDATE_TYPE_RELAYED` |
gpointer `sockptr`; | The underlying socket |
guint64 `keepalive_next_tick`; | The timestamp for the next keepalive |

### enum NiceCandidateType

An enum represneting the type of a candidate

#### Members

NICE_CANDIDATE_TYPE_HOST | A host candidate |
NICE_CANDIDATE_TYPE_SERVER_REFLEXIVE | A server reflexive candidate |
NICE_CANDIDATE_TYPE_PEER_REFLEXIVE | A peer reflexive candidate |
NICE_CANDIDATE_TYPE_RELAYED | A relay candidate |

### enum NiceCandidateTransport

An enum representing the type of transport to use

#### Members

NICE_CANDIDATE_TRANSPORT_UDP | UDP transport |
NICE_CANDIDATE_TRANSPORT_TCP_ACTIVE | TCP Active transport |
NICE_CANDIDATE_TRANSPORT_TCP_PASSIVE | TCP Passive transport |
NICE_CANDIDATE_TRANSPORT_TCP_SO | TCP Simultaneous-Open transport |

### struct TurnServer

    struct TurnServer {
      gint ref_count;

      NiceAddress server;
      gchar *username;
      gchar *password;
      guint8 *decoded_username;
      guint8 *decoded_password;
      gsize decoded_username_len;
      gsize decoded_password_len;
      NiceRelayType type;
      guint preference;
    };

A structure to store the TURN relay settings

#### Members

gint `ref_count`; | Reference count for the structure. |
NiceAddress `server`; | The NiceAddress of the TURN server |
gchar *`username`; | The TURN username |
gchar *`password`; | The TURN password |
guint8 *`decoded_username`; | The base64 decoded TURN username |
guint8 *`decoded_password`; | The base64 decoded TURN password |
gsize `decoded_username_len`; | The length of `decoded_username` |
gsize `decoded_password_len`; | The length of `decoded_password` |
NiceRelayType `type`; | The NiceRelayType of the server |
guint `preference`; | A unique identifier used to compute priority |

### enum NiceRelayType

An enum representing the type of relay to use

#### Members

NICE_RELAY_TYPE_TURN_UDP | A TURN relay using UDP |
NICE_RELAY_TYPE_TURN_TCP | A TURN relay using TCP |
NICE_RELAY_TYPE_TURN_TLS | A TURN relay using TLS over TCP |

### NICE_CANDIDATE_MAX_FOUNDATION

    #define NICE_CANDIDATE_MAX_FOUNDATION                (32+1)

The maximum size a candidate foundation can have.

### NICE_CANDIDATE_MAX_TURN_SERVERS

    #define NICE_CANDIDATE_MAX_TURN_SERVERS              8

The maximum number of turns servers.

### NICE_CANDIDATE_MAX_LOCAL_ADDRESSES

    #define NICE_CANDIDATE_MAX_LOCAL_ADDRESSES           64

The maximum number of local addresses. The constraint is that the maximum number of local addresses and number of turn servers must fit on 9 bits, to ensure candidate priority uniqueness. See also `NICE_CANDIDATE_MAX_TURN_SERVERS` . We choose 6 bits for the number of local addresses, and 3 bits for the number of turn servers.

## See Also

NiceAddress