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 ()
const gchar * | nice_candidate_transport_to_string ()
const gchar * | nice_candidate_type_to_string ()
void | nice_candidate_relay_address ()
gboolean | nice_candidate_stun_server_address ()

## Types and Values

struct | NiceCandidate
enum | NiceCandidateType
enum | NiceCandidateTransport
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

### nice_candidate_transport_to_string ()

    const gchar *
    nice_candidate_transport_to_string (NiceCandidateTransport transport);

Useful for debugging functions, just returns a static string with the candidate transport.

#### Parameters

transport | a NiceCandidateTransport |

#### Returns

a static string with the candidate transport

Since: 0.1.19

### nice_candidate_type_to_string ()

    const gchar *
    nice_candidate_type_to_string (NiceCandidateType type);

Useful for debugging functions, just returns a static string with the candidate type.

#### Parameters

type | a NiceCandidateType |

#### Returns

a static string with the candidate type

Since: 0.1.19

### nice_candidate_relay_address ()

    void
    nice_candidate_relay_address (const NiceCandidate *candidate,
                                  NiceAddress *addr);

In case the given candidate is relayed through a TURN server, use this utility function to get its address.

#### Parameters

candidate | A relay candidate |
addr | The NiceAddress to fill |

Since: 0.1.19

### nice_candidate_stun_server_address ()

    gboolean
    nice_candidate_stun_server_address (const NiceCandidate *candidate,
                                        NiceAddress *addr);

In case the given candidate server-reflexive, use this utility function to get its address. The address will be filled only if the candidate was generated using an STUN server.

#### Parameters

candidate | A server-reflexive candidate |
addr | The NiceAddress to fill |

#### Returns

TRUE if it's a STUN created ICE candidate, or FALSE if the reflexed's server was not STUN.

Since: 0.1.20

## 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 */
    };

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

### enum NiceCandidateType

An enum representing the type of a candidate

#### Members

NICE_CANDIDATE_TYPE_HOST | A host candidate |
NICE_CANDIDATE_TYPE_SERVER_REFLEXIVE | A server reflexive candidate (or a NAT-assisted 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 |

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