## NiceCandidate NiceCandidate — ICE candidate representation |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    struct              NiceCandidate;
    enum                NiceCandidateType;
    enum                NiceCandidateTransport;
    struct              TurnServer;
    enum                NiceRelayType;
    #define             NICE_CANDIDATE_MAX_FOUNDATION
    NiceCandidate *     nice_candidate_new                  (NiceCandidateType type);
    void                nice_candidate_free                 (NiceCandidate *candidate);
    NiceCandidate *     nice_candidate_copy                 (const NiceCandidate *candidate);

## 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/

## Details

### 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 NULL-terminated username string */
      gchar *password;        /* pointer to a NULL-terminated password string */
      TurnServer *turn;
      gpointer sockptr;
    };

A structure to represent an ICE candidate

### Note

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.

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

### enum NiceCandidateType

    typedef enum {
      NICE_CANDIDATE_TYPE_HOST,
      NICE_CANDIDATE_TYPE_SERVER_REFLEXIVE,
      NICE_CANDIDATE_TYPE_PEER_REFLEXIVE,
      NICE_CANDIDATE_TYPE_RELAYED,
    } NiceCandidateType;

An enum represneting the type of a candidate

`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

    typedef enum {
      NICE_CANDIDATE_TRANSPORT_UDP,
    } NiceCandidateTransport;

An enum representing the type of transport to use

`NICE_CANDIDATE_TRANSPORT_UDP` | UDP transport

### struct TurnServer

    struct TurnServer {
      gint ref_count;

      NiceAddress server;       /**< TURN server address */
      gchar *username;           /**< TURN username */
      gchar *password;           /**< TURN password */
      NiceRelayType type;             /**< TURN type */
    };

A structure to store the TURN relay settings

gint `ref_count`; |
NiceAddress `server`; | The NiceAddress of the TURN server
gchar *`username`; | The TURN username
gchar *`password`; | The TURN password
NiceRelayType `type`; | The NiceRelayType of the server

### enum NiceRelayType

    typedef enum {
      NICE_RELAY_TYPE_TURN_UDP,
      NICE_RELAY_TYPE_TURN_TCP,
      NICE_RELAY_TYPE_TURN_TLS
    } NiceRelayType;

An enum representing the type of relay to use

`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_new ()

    NiceCandidate *     nice_candidate_new                  (NiceCandidateType type);

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

`type` : | The NiceCandidateType of the candidate to create
Returns : | A new NiceCandidate

### nice_candidate_free ()

    void                nice_candidate_free                 (NiceCandidate *candidate);

Frees a NiceCandidate

`candidate` : | The candidate to free

### nice_candidate_copy ()

    NiceCandidate *     nice_candidate_copy                 (const NiceCandidate *candidate);

Makes a copy of a NiceCandidate

`candidate` : | The candidate to copy
Returns : | A new NiceCandidate, a copy of `candidate`

## See Also

NiceAddress