## NiceAgent NiceAgent — ICE agent API implementation |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <agent.h>

                        NiceAgent;
    enum                NiceComponentState;
    enum                NiceComponentType;
    enum                NiceProxyType;
    enum                NiceCompatibility;
    void                (*NiceAgentRecvFunc)                (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             guint len,
                                                             gchar *buf,
                                                             gpointer user_data);
                        NiceInputMessage;
                        NiceOutputMessage;
    #define             NICE_AGENT_MAX_REMOTE_CANDIDATES
    NiceAgent *         nice_agent_new                      (GMainContext *ctx,
                                                             NiceCompatibility compat);
    NiceAgent *         nice_agent_new_reliable             (GMainContext *ctx,
                                                             NiceCompatibility compat);
    gboolean            nice_agent_add_local_address        (NiceAgent *agent,
                                                             NiceAddress *addr);
    void                nice_agent_set_port_range           (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             guint min_port,
                                                             guint max_port);
    guint               nice_agent_add_stream               (NiceAgent *agent,
                                                             guint n_components);
    void                nice_agent_remove_stream            (NiceAgent *agent,
                                                             guint stream_id);
    gboolean            nice_agent_set_relay_info           (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             const gchar *server_ip,
                                                             guint server_port,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             NiceRelayType type);
    gboolean            nice_agent_forget_relays            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);
    gboolean            nice_agent_gather_candidates        (NiceAgent *agent,
                                                             guint stream_id);
    gboolean            nice_agent_set_remote_credentials   (NiceAgent *agent,
                                                             guint stream_id,
                                                             const gchar *ufrag,
                                                             const gchar *pwd);
    gboolean            nice_agent_get_local_credentials    (NiceAgent *agent,
                                                             guint stream_id,
                                                             gchar **ufrag,
                                                             gchar **pwd);
    int                 nice_agent_set_remote_candidates    (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             const GSList *candidates);
    GSList *            nice_agent_get_remote_candidates    (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);
    GSList *            nice_agent_get_local_candidates     (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);
    gboolean            nice_agent_get_selected_pair        (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             NiceCandidate **local,
                                                             NiceCandidate **remote);
    gint                nice_agent_send                     (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             guint len,
                                                             const gchar *buf);
    gint                nice_agent_send_messages_nonblocking
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             const NiceOutputMessage *messages,
                                                             guint n_messages,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gssize              nice_agent_recv                     (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             guint8 *buf,
                                                             gsize buf_len,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gint                nice_agent_recv_messages            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             NiceInputMessage *messages,
                                                             guint n_messages,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gssize              nice_agent_recv_nonblocking         (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             guint8 *buf,
                                                             gsize buf_len,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gint                nice_agent_recv_messages_nonblocking
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             NiceInputMessage *messages,
                                                             guint n_messages,
                                                             GCancellable *cancellable,
                                                             GError **error);
    gboolean            nice_agent_attach_recv              (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             GMainContext *ctx,
                                                             NiceAgentRecvFunc func,
                                                             gpointer data);
    gboolean            nice_agent_set_selected_pair        (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             const gchar *lfoundation,
                                                             const gchar *rfoundation);
    gboolean            nice_agent_set_selected_remote_candidate
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             NiceCandidate *candidate);
    void                nice_agent_set_stream_tos           (NiceAgent *agent,
                                                             guint stream_id,
                                                             gint tos);
    void                nice_agent_set_software             (NiceAgent *agent,
                                                             const gchar *software);
    gboolean            nice_agent_restart                  (NiceAgent *agent);
    gboolean            nice_agent_restart_stream           (NiceAgent *agent,
                                                             guint stream_id);
    gboolean            nice_agent_set_stream_name          (NiceAgent *agent,
                                                             guint stream_id,
                                                             const gchar *name);
    const gchar *       nice_agent_get_stream_name          (NiceAgent *agent,
                                                             guint stream_id);
    NiceCandidate *     nice_agent_get_default_local_candidate
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);
    gchar *             nice_agent_generate_local_sdp       (NiceAgent *agent);
    gchar *             nice_agent_generate_local_stream_sdp
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             gboolean include_non_ice);
    gchar *             nice_agent_generate_local_candidate_sdp
                                                            (NiceAgent *agent,
                                                             NiceCandidate *candidate);
    int                 nice_agent_parse_remote_sdp         (NiceAgent *agent,
                                                             const gchar *sdp);
    GSList *            nice_agent_parse_remote_stream_sdp  (NiceAgent *agent,
                                                             guint stream_id,
                                                             const gchar *sdp,
                                                             gchar **ufrag,
                                                             gchar **pwd);
    NiceCandidate *     nice_agent_parse_remote_candidate_sdp
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             const gchar *sdp);
    GIOStream *         nice_agent_get_io_stream            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);
    GSocket *           nice_agent_get_selected_socket      (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);
    const gchar *       nice_component_state_to_string      (NiceComponentState state);

## Object Hierarchy

      GObject
       +----NiceAgent

## Properties

      "compatibility"            guint                 : Read / Write / Construct Only
      "controlling-mode"         gboolean              : Read / Write
      "full-mode"                gboolean              : Read / Write / Construct Only
      "main-context"             gpointer              : Read / Write / Construct Only
      "max-connectivity-checks"  guint                 : Read / Write
      "proxy-ip"                 gchar*                : Read / Write
      "proxy-password"           gchar*                : Read / Write
      "proxy-port"               guint                 : Read / Write
      "proxy-type"               guint                 : Read / Write
      "proxy-username"           gchar*                : Read / Write
      "reliable"                 gboolean              : Read / Write / Construct Only
      "stun-pacing-timer"        guint                 : Read / Write / Construct Only
      "stun-server"              gchar*                : Read / Write
      "stun-server-port"         guint                 : Read / Write
      "upnp"                     gboolean              : Read / Write / Construct
      "upnp-timeout"             guint                 : Read / Write / Construct

## Signals

      "candidate-gathering-done"                       : Run Last
      "component-state-changed"                        : Run Last
      "initial-binding-request-received"               : Run Last
      "new-candidate"                                  : Run Last
      "new-remote-candidate"                           : Run Last
      "new-selected-pair"                              : Run Last
      "reliable-transport-writable"                    : Run Last
      "streams-removed"                                : Run Last

## Description

The NiceAgent is your main object when using libnice. It is the agent that will take care of everything relating to ICE. It will take care of discovering your local candidates and do connectivity checks to create a stream of data between you and your peer.

Streams and their components are referenced by integer IDs (with respect to a given NiceAgent). These IDs are guaranteed to be positive (i.e. non-zero) for valid streams/components.

Each stream can receive data in one of two ways: using `nice_agent_attach_recv()` or `nice_agent_recv_messages()` (and the derived NiceInputStream and NiceIOStream classes accessible using `nice_agent_get_io_stream()`). `nice_agent_attach_recv()` is non-blocking: it takes a user-provided callback function and attaches the stream’s socket to the provided GMainContext, invoking the callback in that context for every packet received. `nice_agent_recv_messages()` instead blocks on receiving a packet, and writes it directly into a user-provided buffer. This reduces the number of callback invokations and (potentially) buffer copies required to receive packets. `nice_agent_recv_messages()` (or NiceInputStream) is designed to be used in a blocking loop in a separate thread.

Example 1. Simple example on how to use libnice

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    guint stream_id;
    gchar buffer[] = "hello world!";
    GSList *lcands = NULL;

    // Create a nice agent
    NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_RFC5245);

    // Connect the signals
    g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
                      G_CALLBACK (cb_candidate_gathering_done), NULL);
    g_signal_connect (G_OBJECT (agent), "component-state-changed",
                      G_CALLBACK (cb_component_state_changed), NULL);
    g_signal_connect (G_OBJECT (agent), "new-selected-pair",
                      G_CALLBACK (cb_new_selected_pair), NULL);

    // Create a new stream with one component and start gathering candidates
    stream_id = nice_agent_add_stream (agent, 1);
    nice_agent_gather_candidates (agent, stream_id);

    // Attach to the component to receive the data
    nice_agent_attach_recv (agent, stream_id, 1, NULL,
                           cb_nice_recv, NULL);

    // ... Wait until the signal candidate-gathering-done is fired ...
    lcands = nice_agent_get_local_candidates(agent, stream_id, 1);

    // ... Send local candidates to the peer and set the peer's remote candidates
    nice_agent_set_remote_candidates (agent, stream_id, 1, rcands);

    // ... Wait until the signal new-selected-pair is fired ...
    // Send our message!
    nice_agent_send (agent, stream_id, 1, sizeof(buffer), buffer);

    // Anything received will be received through the cb_nice_recv callback

    // Destroy the object
    g_object_unref(agent);

Refer to the examples in the examples/ subdirectory of the libnice source for complete examples.

## Details

### NiceAgent

    typedef struct _NiceAgent NiceAgent;

The NiceAgent is the main GObject of the libnice library and represents the ICE agent.

### enum NiceComponentState

    typedef enum {
      NICE_COMPONENT_STATE_DISCONNECTED,
      NICE_COMPONENT_STATE_GATHERING,
      NICE_COMPONENT_STATE_CONNECTING,
      NICE_COMPONENT_STATE_CONNECTED,
      NICE_COMPONENT_STATE_READY,
      NICE_COMPONENT_STATE_FAILED,
      NICE_COMPONENT_STATE_LAST
    } NiceComponentState;

An enum representing the state of a component.

See also: "component-state-changed"

`NICE_COMPONENT_STATE_DISCONNECTED` | No activity scheduled
`NICE_COMPONENT_STATE_GATHERING` | Gathering local candidates
`NICE_COMPONENT_STATE_CONNECTING` | Establishing connectivity
`NICE_COMPONENT_STATE_CONNECTED` | At least one working candidate pair
`NICE_COMPONENT_STATE_READY` | ICE concluded, candidate pair selection is now final
`NICE_COMPONENT_STATE_FAILED` | Connectivity checks have been completed, but connectivity was not established
`NICE_COMPONENT_STATE_LAST` | Dummy state

### enum NiceComponentType

    typedef enum {
      NICE_COMPONENT_TYPE_RTP = 1,
      NICE_COMPONENT_TYPE_RTCP = 2
    } NiceComponentType;

Convenience enum representing the type of a component for use as the component_id for RTP/RTCP usages.

Example 2. Example of use.

    1
    nice_agent_send (agent, stream_id, NICE_COMPONENT_TYPE_RTP, len, buf);

`NICE_COMPONENT_TYPE_RTP` | RTP Component type
`NICE_COMPONENT_TYPE_RTCP` | RTCP Component type

### enum NiceProxyType

    typedef enum {
      NICE_PROXY_TYPE_NONE = 0,
      NICE_PROXY_TYPE_SOCKS5,
      NICE_PROXY_TYPE_HTTP,
      NICE_PROXY_TYPE_LAST = NICE_PROXY_TYPE_HTTP,
    } NiceProxyType;

An enum to specify which proxy type to use for relaying. Note that the proxies will only be used with TCP TURN relaying.

See also: "proxy-type"

`NICE_PROXY_TYPE_NONE` | Do not use a proxy
`NICE_PROXY_TYPE_SOCKS5` | Use a SOCKS5 proxy
`NICE_PROXY_TYPE_HTTP` | Use an HTTP proxy
`NICE_PROXY_TYPE_LAST` | Dummy last proxy type

Since 0.0.4

### enum NiceCompatibility

    typedef enum {
      NICE_COMPATIBILITY_RFC5245 = 0,
      NICE_COMPATIBILITY_GOOGLE,
      NICE_COMPATIBILITY_MSN,
      NICE_COMPATIBILITY_WLM2009,
      NICE_COMPATIBILITY_OC2007,
      NICE_COMPATIBILITY_OC2007R2,
      NICE_COMPATIBILITY_DRAFT19 = NICE_COMPATIBILITY_RFC5245,
      NICE_COMPATIBILITY_LAST = NICE_COMPATIBILITY_OC2007R2,
    } NiceCompatibility;

An enum to specify which compatible specifications the NiceAgent should use. Use with `nice_agent_new()`

### Warning

`NICE_COMPATIBILITY_DRAFT19` is deprecated and should not be used in newly-written code. It is kept for compatibility reasons and represents the same compatibility as `NICE_COMPATIBILITY_RFC5245`

`NICE_COMPATIBILITY_RFC5245` | Use compatibility with the RFC5245 ICE specs
`NICE_COMPATIBILITY_GOOGLE` | Use compatibility for Google Talk specs
`NICE_COMPATIBILITY_MSN` | Use compatibility for MSN Messenger specs
`NICE_COMPATIBILITY_WLM2009` | Use compatibility with Windows Live Messenger 2009
`NICE_COMPATIBILITY_OC2007` | Use compatibility with Microsoft Office Communicator 2007
`NICE_COMPATIBILITY_OC2007R2` | Use compatibility with Microsoft Office Communicator 2007 R2
`NICE_COMPATIBILITY_DRAFT19` | Use compatibility for ICE Draft 19 specs
`NICE_COMPATIBILITY_LAST` | Dummy last compatibility mode

### NiceAgentRecvFunc ()

    void                (*NiceAgentRecvFunc)                (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             guint len,
                                                             gchar *buf,
                                                             gpointer user_data);

Callback function when data is received on a component

`agent` : | The NiceAgent Object
`stream_id` : | The id of the stream
`component_id` : | The id of the component of the stream which received the data
`len` : | The length of the data
`buf` : | The buffer containing the data received
`user_data` : | The user data set in `nice_agent_attach_recv()`

### NiceInputMessage

    typedef struct {
      GInputVector *buffers;
      gint n_buffers;  /* may be -1 to indicate @buffers is NULL-terminated */
      NiceAddress *from;  /* return location for address of message sender */
      gsize length;  /* sum of the lengths of @buffers */
    } NiceInputMessage;

Represents a single message received off the network. For reliable connections, this is essentially just an array of buffers (specifically, `from` can be ignored). for non-reliable connections, it represents a single packet as received from the OS.

`n_buffers` may be -1 to indicate that `buffers` is terminated by a GInputVector with a `NULL` buffer pointer.

By providing arrays of NiceInputMessages to functions like `nice_agent_recv_messages()`, multiple messages may be received with a single call, which is more efficient than making multiple calls in a loop. In this manner, `nice_agent_recv_messages()` is analogous to `recvmmsg()`; and NiceInputMessage to struct mmsghdr.

GInputVector *`buffers`; | unowned array of GInputVector buffers to store data in for this message. [array length=n_buffers]
gint `n_buffers`; | number of GInputVectors in `buffers`, or -1 to indicate `buffers` is `NULL`-terminated
NiceAddress *`from`; | return location to store the address of the peer who transmitted the message, or `NULL`. [allow-none]
gsize `length`; | total number of valid bytes contiguously stored in `buffers`

Since 0.1.5

### NiceOutputMessage

    typedef struct {
      GOutputVector *buffers;
      gint n_buffers;
    } NiceOutputMessage;

Represents a single message to transmit on the network. For reliable connections, this is essentially just an array of buffer. for non-reliable connections, it represents a single packet to send to the OS.

`n_buffers` may be -1 to indicate that `buffers` is terminated by a GOutputVector with a `NULL` buffer pointer.

By providing arrays of NiceOutputMessages to functions like `nice_agent_send_messages_nonblocking()`, multiple messages may be transmitted with a single call, which is more efficient than making multiple calls in a loop. In this manner, `nice_agent_send_messages_nonblocking()` is analogous to `sendmmsg()`; and NiceOutputMessage to struct mmsghdr.

GOutputVector *`buffers`; | unowned array of GOutputVector buffers which contain data to transmit for this message. [array length=n_buffers]
gint `n_buffers`; | number of GOutputVectors in `buffers`, or -1 to indicate `buffers` is `NULL`-terminated

Since 0.1.5

### NICE_AGENT_MAX_REMOTE_CANDIDATES

    #define NICE_AGENT_MAX_REMOTE_CANDIDATES    25

A hard limit for the number of remote candidates. This limit is enforced to protect against malevolent remote clients.

### nice_agent_new ()

    NiceAgent *         nice_agent_new                      (GMainContext *ctx,
                                                             NiceCompatibility compat);

Create a new NiceAgent. The returned object must be freed with `g_object_unref()`

`ctx` : | The Glib Mainloop Context to use for timers
`compat` : | The compatibility mode of the agent
Returns : | The new agent GObject

### nice_agent_new_reliable ()

    NiceAgent *         nice_agent_new_reliable             (GMainContext *ctx,
                                                             NiceCompatibility compat);

Create a new NiceAgent in reliable mode, which uses PseudoTcpSocket to assure reliability of the messages. The returned object must be freed with `g_object_unref()`

See also: "reliable-transport-writable"

`ctx` : | The Glib Mainloop Context to use for timers
`compat` : | The compatibility mode of the agent
Returns : | The new agent GObject

Since 0.0.11

### nice_agent_add_local_address ()

    gboolean            nice_agent_add_local_address        (NiceAgent *agent,
                                                             NiceAddress *addr);

Add a local address from which to derive local host candidates for candidate gathering.

Since 0.0.5, if this method is not called, libnice will automatically discover the local addresses available

See also: `nice_agent_gather_candidates()`

`agent` : | The NiceAgent Object
`addr` : | The address to listen to If the port is 0, then a random port will be chosen by the system
Returns : | `TRUE` on success, `FALSE` on fatal (memory allocation) errors

### nice_agent_set_port_range ()

    void                nice_agent_set_port_range           (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             guint min_port,
                                                             guint max_port);

Sets a preferred port range for allocating host candidates.

If a local host candidate cannot be created on that port range, then the `nice_agent_gather_candidates()` call will fail.

This MUST be called before `nice_agent_gather_candidates()`

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
`min_port` : | The minimum port to use
`max_port` : | The maximum port to use

### nice_agent_add_stream ()

    guint               nice_agent_add_stream               (NiceAgent *agent,
                                                             guint n_components);

Adds a data stream to `agent` containing `n_components` components. The returned stream ID is guaranteed to be positive on success.

`agent` : | The NiceAgent Object
`n_components` : | The number of components to add to the stream
Returns : | The ID of the new stream, 0 on failure

### nice_agent_remove_stream ()

    void                nice_agent_remove_stream            (NiceAgent *agent,
                                                             guint stream_id);

Remove and free a previously created data stream from `agent`

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream to remove

### nice_agent_set_relay_info ()

    gboolean            nice_agent_set_relay_info           (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             const gchar *server_ip,
                                                             guint server_port,
                                                             const gchar *username,
                                                             const gchar *password,
                                                             NiceRelayType type);

Sets the settings for using a relay server during the candidate discovery. This may be called multiple times to add multiple relay servers to the discovery process; one TCP and one UDP, for example.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
`server_ip` : | The IP address of the TURN server
`server_port` : | The port of the TURN server
`username` : | The TURN username to use for the allocate
`password` : | The TURN password to use for the allocate
`type` : | The type of relay to use
Returns : | `TRUE` if the TURN settings were accepted. `FALSE` if the address was invalid.

### nice_agent_forget_relays ()

    gboolean            nice_agent_forget_relays            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);

Forget all the relay servers previously added using `nice_agent_set_relay_info()`. Currently connected streams will keep using the relay as long as they have not been restarted and haven't succesfully negotiated a different path.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
Returns : | `FALSE` if the component could not be found, `TRUE` otherwise

Since 0.1.6

### nice_agent_gather_candidates ()

    gboolean            nice_agent_gather_candidates        (NiceAgent *agent,
                                                             guint stream_id);

Allocate and start listening on local candidate ports and start the remote candidate gathering process. Once done, "candidate-gathering-done" is called for the stream. As soon as this function is called, "new-candidate" signals may be emitted, even before this function returns.

`nice_agent_get_local_candidates()` will only return non-empty results after calling this function.

See also: `nice_agent_add_local_address()`

See also: `nice_agent_set_port_range()`

`agent` : | The NiceAgent object
`stream_id` : | The ID of the stream to start
Returns : | `FALSE` if the stream ID is invalid or if a host candidate couldn't be allocated on the requested interfaces/ports; `TRUE` otherwise ### Note Local addresses can be previously set with `nice_agent_add_local_address()` Since 0.0.5, If no local address was previously added, then the nice agent will automatically detect the local address using `nice_interfaces_get_local_ips()`

### nice_agent_set_remote_credentials ()

    gboolean            nice_agent_set_remote_credentials   (NiceAgent *agent,
                                                             guint stream_id,
                                                             const gchar *ufrag,
                                                             const gchar *pwd);

Sets the remote credentials for stream `stream_id`.

### Note

Stream credentials do not override per-candidate credentials if set

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`ufrag` : | NULL-terminated string containing an ICE username fragment (length must be between 22 and 256 chars)
`pwd` : | NULL-terminated string containing an ICE password (length must be between 4 and 256 chars)
Returns : | `TRUE` on success, `FALSE` on error.

### nice_agent_get_local_credentials ()

    gboolean            nice_agent_get_local_credentials    (NiceAgent *agent,
                                                             guint stream_id,
                                                             gchar **ufrag,
                                                             gchar **pwd);

Gets the local credentials for stream `stream_id`. This may be called any time after creating a stream using `nice_agent_add_stream()`.

An error will be returned if this is called for a non-existent stream, or if either of `ufrag` or `pwd` are `NULL`.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`ufrag` : | return location for a nul-terminated string containing an ICE username fragment; must be freed with `g_free()`. [out callee-allocates]
`pwd` : | return location for a nul-terminated string containing an ICE password; must be freed with `g_free()`. [out callee-allocates]
Returns : | `TRUE` on success, `FALSE` on error.

### nice_agent_set_remote_candidates ()

    int                 nice_agent_set_remote_candidates    (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             const GSList *candidates);

Sets, adds or updates the remote candidates for a component of a stream.

### Note

NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit for remote candidates.

You must first call `nice_agent_gather_candidates()` and wait for the "candidate-gathering-done" signale before calling `nice_agent_set_remote_candidates()`

Since 0.1.3, there is no need to wait for the candidate-gathering-done signal. Remote candidates can be set even while gathering local candidates. Newly discovered local candidates will automatically be paired with existing remote candidates.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream the candidates are for
`component_id` : | The ID of the component the candidates are for
`candidates` : | a GSList of NiceCandidate items describing each candidate to add
Returns : | The number of candidates added, negative on errors (memory allocation error or invalid component)

### nice_agent_get_remote_candidates ()

    GSList *            nice_agent_get_remote_candidates    (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);

Get a list of the remote candidates set on a stream's component

### Note

The caller owns the returned GSList as well as the candidates contained within it.

The list of remote candidates can change during processing. The client should register for the "new-remote-candidate" signal to get notified of new remote candidates.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
Returns : | a GSList of NiceCandidates objects representing the remote candidates set on the `agent`

### nice_agent_get_local_candidates ()

    GSList *            nice_agent_get_local_candidates     (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);

Retreive from the agent the list of all local candidates for a stream's component

### Note

The caller owns the returned GSList as well as the candidates contained within it. To get full results, the client should wait for the "candidate-gathering-done" signal.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
Returns : | a GSList of NiceCandidate objects representing the local candidates of `agent`

### nice_agent_get_selected_pair ()

    gboolean            nice_agent_get_selected_pair        (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             NiceCandidate **local,
                                                             NiceCandidate **remote);

Retreive the selected candidate pair for media transmission for a given stream's component.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
`local` : | The local selected candidate
`remote` : | The remote selected candidate
Returns : | `TRUE` on success, `FALSE` if there is no selected candidate pair

### nice_agent_send ()

    gint                nice_agent_send                     (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             guint len,
                                                             const gchar *buf);

Sends a data payload over a stream's component.

### Note

Component state MUST be NICE_COMPONENT_STATE_READY, or as a special case, in any state if component was in READY state before and was then restarted

In reliable mode, the -1 error value means either that you are not yet connected or that the send buffer is full (equivalent to EWOULDBLOCK). In both cases, you simply need to wait for the "reliable-transport-writable" signal to be fired before resending the data.

In non-reliable mode, it will virtually never happen with UDP sockets, but it might happen if the active candidate is a TURN-TCP connection that got disconnected.

In both reliable and non-reliable mode, a -1 error code could also mean that the stream_id and/or component_id are invalid.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream to send to
`component_id` : | The ID of the component to send to
`len` : | The length of the buffer to send
`buf` : | The buffer of data to send
Returns : | The number of bytes sent, or negative error code

### nice_agent_send_messages_nonblocking ()

    gint                nice_agent_send_messages_nonblocking
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             const NiceOutputMessage *messages,
                                                             guint n_messages,
                                                             GCancellable *cancellable,
                                                             GError **error);

Sends multiple messages on the socket identified by the given stream/component pair. Transmission is non-blocking, so a `G_IO_ERROR_WOULD_BLOCK` error may be returned if the send buffer is full.

As with `nice_agent_send()`, the given component must be in `NICE_COMPONENT_STATE_READY` or, as a special case, in any state if it was previously ready and was then restarted.

On success, the number of messages written to the socket will be returned, which may be less than `n_messages` if transmission would have blocked part-way through. Zero will be returned if `n_messages` is zero, or if transmission would have blocked on the first message.

In reliable mode, it is instead recommended to use `nice_agent_send()`. The return value can be less than `n_messages` or 0 even if it is still possible to send a partial message. In this case, "nice-agent-writable" will never be triggered, so the application would have to use `nice_agent_sent()` to fill the buffer or have to retry sending at a later point.

On failure, -1 will be returned and `error` will be set. If the NiceAgent is reliable and the socket is not yet connected, `G_IO_ERROR_BROKEN_PIPE` will be returned; if the write buffer is full, `G_IO_ERROR_WOULD_BLOCK` will be returned. In both cases, wait for the "reliable-transport-writable" signal before trying again. If the given `stream_id` or `component_id` are invalid or not yet connected, `G_IO_ERROR_BROKEN_PIPE` will be returned. `G_IO_ERROR_FAILED` will be returned for other errors.

`agent` : | a NiceAgent
`stream_id` : | the ID of the stream to send to
`component_id` : | the ID of the component to send to
`messages` : | array of messages to send, of at least `n_messages` entries in length. [array length=n_messages]
`n_messages` : | number of entries in `messages`
`cancellable` : | a GCancellable to cancel the operation from another thread, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | the number of messages sent (may be zero), or -1 on error

Since 0.1.5

### nice_agent_recv ()

    gssize              nice_agent_recv                     (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             guint8 *buf,
                                                             gsize buf_len,
                                                             GCancellable *cancellable,
                                                             GError **error);

A single-message version of `nice_agent_recv_messages()`.

`agent` : | a NiceAgent
`stream_id` : | the ID of the stream to receive on
`component_id` : | the ID of the component to receive on
`buf` : | caller-allocated buffer to write the received data into, of length at least `buf_len`. [array length=buf_len][out caller-allocates]
`buf_len` : | length of `buf`
`cancellable` : | a GCancellable to allow the operation to be cancelled from another thread, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | the number of bytes written to `buf` on success (guaranteed to be greater than 0 unless `buf_len` is 0), or -1 on error

Since 0.1.5

### nice_agent_recv_messages ()

    gint                nice_agent_recv_messages            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             NiceInputMessage *messages,
                                                             guint n_messages,
                                                             GCancellable *cancellable,
                                                             GError **error);

Block on receiving data from the given stream/component combination on `agent`, returning only once exactly `n_messages` messages have been received and written into `messages`, the stream is closed by the other end or by calling `nice_agent_remove_stream()`, or `cancellable` is cancelled.

In the non-error case, in reliable mode, this will block until all buffers in all `n_messages` have been filled with received data (i.e. `messages` is treated as a large, flat array of buffers). In non-reliable mode, it will block until `n_messages` messages have been received, each of which does not have to fill all the buffers in its NiceInputMessage. In the non-reliable case, each NiceInputMessage must have enough buffers to contain an entire message (65536 bytes), or any excess data may be silently dropped.

For each received message, "length" will be set to the number of valid bytes stored in the message’s buffers. The bytes are stored sequentially in the buffers; there are no gaps apart from at the end of the buffer array (in non-reliable mode). If non-`NULL` on input, "from" will have the address of the sending peer stored in it. The base addresses, sizes, and number of buffers in each message will not be modified in any case.

This must not be used in combination with `nice_agent_attach_recv()` on the same stream/component pair.

If the stream/component pair doesn’t exist, or if a suitable candidate socket hasn’t yet been selected for it, a `G_IO_ERROR_BROKEN_PIPE` error will be returned. A `G_IO_ERROR_CANCELLED` error will be returned if the operation was cancelled. `G_IO_ERROR_FAILED` will be returned for other errors.

`agent` : | a NiceAgent
`stream_id` : | the ID of the stream to receive on
`component_id` : | the ID of the component to receive on
`messages` : | caller-allocated array of NiceInputMessages to write the received messages into, of length at least `n_messages`. [array length=n_messages][out caller-allocates]
`n_messages` : | number of entries in `messages`
`cancellable` : | a GCancellable to allow the operation to be cancelled from another thread, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | the number of valid messages written to `messages` on success (guaranteed to be greater than 0 unless `n_messages` is 0), or -1 on error

Since 0.1.5

### nice_agent_recv_nonblocking ()

    gssize              nice_agent_recv_nonblocking         (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             guint8 *buf,
                                                             gsize buf_len,
                                                             GCancellable *cancellable,
                                                             GError **error);

A single-message version of `nice_agent_recv_messages_nonblocking()`.

`agent` : | a NiceAgent
`stream_id` : | the ID of the stream to receive on
`component_id` : | the ID of the component to receive on
`buf` : | caller-allocated buffer to write the received data into, of length at least `buf_len`. [array length=buf_len][out caller-allocates]
`buf_len` : | length of `buf`
`cancellable` : | a GCancellable to allow the operation to be cancelled from another thread, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | the number of bytes received into `buf` on success (guaranteed to be greater than 0 unless `buf_len` is 0), or -1 on error

Since 0.1.5

### nice_agent_recv_messages_nonblocking ()

    gint                nice_agent_recv_messages_nonblocking
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             NiceInputMessage *messages,
                                                             guint n_messages,
                                                             GCancellable *cancellable,
                                                             GError **error);

Try to receive data from the given stream/component combination on `agent`, without blocking. If receiving data would block, -1 is returned and `G_IO_ERROR_WOULD_BLOCK` is set in `error`. If any other error occurs, -1 is returned and `error` is set accordingly. Otherwise, 0 is returned if (and only if) `n_messages` is 0. In all other cases, the number of valid messages stored in `messages` is returned, and will be greater than 0.

This function behaves similarly to `nice_agent_recv_messages()`, except that it will not block on filling (in reliable mode) or receiving (in non-reliable mode) exactly `n_messages` messages. In reliable mode, it will receive bytes into `messages` until it would block; in non-reliable mode, it will receive messages until it would block.

As this function is non-blocking, `cancellable` is included only for parity with `nice_agent_recv_messages()`. If `cancellable` is cancelled before this function is called, a `G_IO_ERROR_CANCELLED` error will be returned immediately.

This must not be used in combination with `nice_agent_attach_recv()` on the same stream/component pair.

`agent` : | a NiceAgent
`stream_id` : | the ID of the stream to receive on
`component_id` : | the ID of the component to receive on
`messages` : | caller-allocated array of NiceInputMessages to write the received messages into, of length at least `n_messages`. [array length=n_messages][out caller-allocates]
`n_messages` : | number of entries in `messages`
`cancellable` : | a GCancellable to allow the operation to be cancelled from another thread, or `NULL`. [allow-none]
`error` : | return location for a GError, or `NULL`. [allow-none]
Returns : | the number of valid messages written to `messages` on success (guaranteed to be greater than 0 unless `n_messages` is 0), or -1 on error

Since 0.1.5

### nice_agent_attach_recv ()

    gboolean            nice_agent_attach_recv              (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             GMainContext *ctx,
                                                             NiceAgentRecvFunc func,
                                                             gpointer data);

Attaches the stream's component's sockets to the Glib Mainloop Context in order to be notified whenever data becomes available for a component.

This must not be used in combination with `nice_agent_recv_messages()` (or NiceIOStream or NiceInputStream) on the same stream/component pair.

Calling `nice_agent_attach_recv()` with a `NULL` `func` will detach any existing callback and cause reception to be paused for the given stream/component pair. You must iterate the previously specified GMainContext sufficiently to ensure all pending I/O callbacks have been received before calling this function to unset `func`, otherwise data loss of received packets may occur.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of stream
`component_id` : | The ID of the component
`ctx` : | The Glib Mainloop Context to use for listening on the component
`func` : | The callback function to be called when data is received on the stream's component
`data` : | user data associated with the callback
Returns : | `TRUE` on success, `FALSE` if the stream or component IDs are invalid.

### nice_agent_set_selected_pair ()

    gboolean            nice_agent_set_selected_pair        (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             const gchar *lfoundation,
                                                             const gchar *rfoundation);

Sets the selected candidate pair for media transmission for a given stream's component. Calling this function will disable all further ICE processing (connection check, state machine updates, etc). Note that keepalives will continue to be sent.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
`lfoundation` : | The local foundation of the candidate to use
`rfoundation` : | The remote foundation of the candidate to use
Returns : | `TRUE` on success, `FALSE` if the candidate pair cannot be found

### nice_agent_set_selected_remote_candidate ()

    gboolean            nice_agent_set_selected_remote_candidate
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id,
                                                             NiceCandidate *candidate);

Sets the selected remote candidate for media transmission for a given stream's component. This is used to force the selection of a specific remote candidate even when connectivity checks are failing (e.g. non-ICE compatible candidates). Calling this function will disable all further ICE processing (connection check, state machine updates, etc). Note that keepalives will continue to be sent.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
`candidate` : | The NiceCandidate to select
Returns : | `TRUE` on success, `FALSE` on failure

### nice_agent_set_stream_tos ()

    void                nice_agent_set_stream_tos           (NiceAgent *agent,
                                                             guint stream_id,
                                                             gint tos);

Sets the IP_TOS and/or IPV6_TCLASS field on the stream's sockets' options

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`tos` : | The ToS to set

Since 0.0.9

### nice_agent_set_software ()

    void                nice_agent_set_software             (NiceAgent *agent,
                                                             const gchar *software);

This function will set the value of the SOFTWARE attribute to be added to STUN requests, responses and error responses sent during connectivity checks.

The SOFTWARE attribute will only be added in the NICE_COMPATIBILITY_RFC5245 and NICE_COMPATIBILITY_WLM2009 compatibility modes.

### Note

The `software` argument will be appended with the libnice version before being sent.

The `software` argument must be in UTF-8 encoding and only the first 128 characters will be sent.

`agent` : | The NiceAgent Object
`software` : | The value of the SOFTWARE attribute to add.

Since 0.0.10

### nice_agent_restart ()

    gboolean            nice_agent_restart                  (NiceAgent *agent);

Restarts the session as defined in ICE draft 19. This function needs to be called both when initiating (ICE spec section 9.1.1.1. "ICE Restarts"), as well as when reacting (spec section 9.2.1.1. "Detecting ICE Restart") to a restart.

`agent` : | The NiceAgent Object
Returns : | `TRUE` on success `FALSE` on error

### nice_agent_restart_stream ()

    gboolean            nice_agent_restart_stream           (NiceAgent *agent,
                                                             guint stream_id);

Restarts a single stream as defined in RFC 5245. This function needs to be called both when initiating (ICE spec section 9.1.1.1. "ICE Restarts"), as well as when reacting (spec section 9.2.1.1. "Detecting ICE Restart") to a restart.

Unlike `nice_agent_restart()`, this applies to a single stream. It also does not generate a new tie breaker.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
Returns : | `TRUE` on success `FALSE` on error

Since 0.1.6

### nice_agent_set_stream_name ()

    gboolean            nice_agent_set_stream_name          (NiceAgent *agent,
                                                             guint stream_id,
                                                             const gchar *name);

This function will assign a unique name to a stream. This is only useful when parsing and generating an SDP of the candidates.

See also: `nice_agent_generate_local_sdp()`

See also: `nice_agent_parse_remote_sdp()`

See also: `nice_agent_get_stream_name()`

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream to change
`name` : | The new name of the stream or `NULL`
Returns : | `TRUE` if the name has been set. `FALSE` in case of error (invalid stream or duplicate name).

Since 0.1.4

### nice_agent_get_stream_name ()

    const gchar *       nice_agent_get_stream_name          (NiceAgent *agent,
                                                             guint stream_id);

This function will return the name assigned to a stream.

See also: `nice_agent_set_stream_name()`

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream to change
Returns : | The name of the stream. The name is only valid while the stream exists or until it changes through a call to `nice_agent_set_stream_name()`.

Since 0.1.4

### nice_agent_get_default_local_candidate ()

    NiceCandidate *     nice_agent_get_default_local_candidate
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);

This helper function will return the recommended default candidate to be used for non-ICE compatible clients. This will usually be the candidate with the lowest priority, since it will be the longest path but the one with the most chances of success.

### Note

This function is only useful in order to manually generate the local SDP

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
Returns : | The candidate to be used as the default candidate, or `NULL` in case of error. Must be freed with `nice_candidate_free()` once done.

### nice_agent_generate_local_sdp ()

    gchar *             nice_agent_generate_local_sdp       (NiceAgent *agent);

Generate an SDP string containing the local candidates and credentials for all streams and components in the agent.

### Note

The SDP will not contain any codec lines and the 'm' line will not list any payload types.

It is highly recommended to set names on the streams prior to calling this function. Unnamed streams will show up as '-' in the 'm' line, but the SDP will not be parseable with `nice_agent_parse_remote_sdp()` if a stream is unnamed.

The default candidate in the SDP will be selected based on the lowest priority candidate for the first component.

See also: `nice_agent_set_stream_name()`

See also: `nice_agent_parse_remote_sdp()`

See also: `nice_agent_generate_local_stream_sdp()`

See also: `nice_agent_generate_local_candidate_sdp()`

See also: `nice_agent_get_default_local_candidate()`

`agent` : | The NiceAgent Object
Returns : | A string representing the local SDP. Must be freed with `g_free()` once done.

Since 0.1.4

### nice_agent_generate_local_stream_sdp ()

    gchar *             nice_agent_generate_local_stream_sdp
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             gboolean include_non_ice);

Generate an SDP string containing the local candidates and credentials for a stream.

### Note

The SDP will not contain any codec lines and the 'm' line will not list any payload types.

It is highly recommended to set the name of the stream prior to calling this function. Unnamed streams will show up as '-' in the 'm' line.

The default candidate in the SDP will be selected based on the lowest priority candidate.

See also: `nice_agent_set_stream_name()`

See also: `nice_agent_parse_remote_stream_sdp()`

See also: `nice_agent_generate_local_sdp()`

See also: `nice_agent_generate_local_candidate_sdp()`

See also: `nice_agent_get_default_local_candidate()`

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`include_non_ice` : | Whether or not to include non ICE specific lines (m=, c= and a=rtcp: lines)
Returns : | A string representing the local SDP for the stream. Must be freed with `g_free()` once done.

Since 0.1.4

### nice_agent_generate_local_candidate_sdp ()

    gchar *             nice_agent_generate_local_candidate_sdp
                                                            (NiceAgent *agent,
                                                             NiceCandidate *candidate);

Generate an SDP string representing a local candidate.

See also: `nice_agent_parse_remote_candidate_sdp()`

See also: `nice_agent_generate_local_sdp()`

See also: `nice_agent_generate_local_stream_sdp()`

`agent` : | The NiceAgent Object
`candidate` : | The candidate to generate
Returns : | A string representing the SDP for the candidate. Must be freed with `g_free()` once done.

Since 0.1.4

### nice_agent_parse_remote_sdp ()

    int                 nice_agent_parse_remote_sdp         (NiceAgent *agent,
                                                             const gchar *sdp);

Parse an SDP string and extracts candidates and credentials from it and sets them on the agent.

### Note

This function will return an error if a stream has not been assigned a name with `nice_agent_set_stream_name()` as it becomes troublesome to assign the streams from the agent to the streams in the SDP.

See also: `nice_agent_set_stream_name()`

See also: `nice_agent_generate_local_sdp()`

See also: `nice_agent_parse_remote_stream_sdp()`

See also: `nice_agent_parse_remote_candidate_sdp()`

`agent` : | The NiceAgent Object
`sdp` : | The remote SDP to parse
Returns : | The number of candidates added, negative on errors

Since 0.1.4

### nice_agent_parse_remote_stream_sdp ()

    GSList *            nice_agent_parse_remote_stream_sdp  (NiceAgent *agent,
                                                             guint stream_id,
                                                             const gchar *sdp,
                                                             gchar **ufrag,
                                                             gchar **pwd);

Parse an SDP string representing a single stream and extracts candidates and credentials from it.

See also: `nice_agent_generate_local_stream_sdp()`

See also: `nice_agent_parse_remote_sdp()`

See also: `nice_agent_parse_remote_candidate_sdp()`

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream to parse
`sdp` : | The remote SDP to parse
`ufrag` : | Pointer to store the ice ufrag if non `NULL`. Must be freed with `g_free()` after use
`pwd` : | Pointer to store the ice password if non `NULL`. Must be freed with `g_free()` after use
Returns : | A GSList of candidates parsed from the SDP, or `NULL` in case of errors

Since 0.1.4

### nice_agent_parse_remote_candidate_sdp ()

    NiceCandidate *     nice_agent_parse_remote_candidate_sdp
                                                            (NiceAgent *agent,
                                                             guint stream_id,
                                                             const gchar *sdp);

Parse an SDP string and extracts the candidate from it.

See also: `nice_agent_generate_local_candidate_sdp()`

See also: `nice_agent_parse_remote_sdp()`

See also: `nice_agent_parse_remote_stream_sdp()`

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream the candidate belongs to
`sdp` : | The remote SDP to parse
Returns : | The parsed candidate or `NULL` if there was an error.

Since 0.1.4

### nice_agent_get_io_stream ()

    GIOStream *         nice_agent_get_io_stream            (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);

Gets a GIOStream wrapper around the given stream and component in `agent`. The I/O stream will be valid for as long as `stream_id` is valid. The GInputStream and GOutputStream implement GPollableInputStream and GPollableOutputStream.

This function may only be called on reliable NiceAgents. It is a programming error to try and create an I/O stream wrapper for an unreliable stream.

`agent` : | A NiceAgent
`stream_id` : | The ID of the stream to wrap
`component_id` : | The ID of the component to wrap
Returns : | A GIOStream. [transfer full]

Since 0.1.5

### nice_agent_get_selected_socket ()

    GSocket *           nice_agent_get_selected_socket      (NiceAgent *agent,
                                                             guint stream_id,
                                                             guint component_id);

Retreive the local socket associated with the selected candidate pair for media transmission for a given stream's component.

This is useful for adding ICE support to legacy applications that already have a protocol that maintains a connection. If the socket is duplicated before unrefing the agent, the application can take over and continue to use it. New applications are encouraged to use the built in libnice stream handling instead and let libnice handle the connection maintenance.

Users of this method are encouraged to not use a TURN relay or any kind of proxy, as in this case, the socket will not be available to the application because the packets are encapsulated.

`agent` : | The NiceAgent Object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
Returns : | (transfer full) pointer to the GSocket, or NULL if there is no selected candidate or if the selected candidate is a relayed candidate.

Since 0.1.5

### nice_component_state_to_string ()

    const gchar *       nice_component_state_to_string      (NiceComponentState state);

Returns a string representation of the state, generally to use in debug messages.

`state` : | a NiceComponentState
Returns : | a string representation of `state`. [transfer none]

Since 0.1.6

## Property Details

### The `"compatibility"` property

      "compatibility"            guint                 : Read / Write / Construct Only

The Nice agent can work in various compatibility modes depending on what the application/peer needs.

See also: NiceCompatibility

Allowed values: <= 5

Default value: 0

### The `"controlling-mode"` property

      "controlling-mode"         gboolean              : Read / Write

Whether the agent is in controlling mode.

Default value: FALSE

### The `"full-mode"` property

      "full-mode"                gboolean              : Read / Write / Construct Only

Whether agent runs in ICE full mode.

Default value: TRUE

### The `"main-context"` property

      "main-context"             gpointer              : Read / Write / Construct Only

A GLib main context is needed for all timeouts used by libnice. This is a property being set by the `nice_agent_new()` call.

### The `"max-connectivity-checks"` property

      "max-connectivity-checks"  guint                 : Read / Write

Upper limit for the total number of connectivity checks performed.

Default value: 0

### The `"proxy-ip"` property

      "proxy-ip"                 gchar*                : Read / Write

The proxy server IP used to bypass a proxy firewall

Default value: NULL

Since 0.0.4

### The `"proxy-password"` property

      "proxy-password"           gchar*                : Read / Write

The password used to authenticate with the proxy

Default value: NULL

Since 0.0.4

### The `"proxy-port"` property

      "proxy-port"               guint                 : Read / Write

The proxy server port used to bypass a proxy firewall

Allowed values: [1,65536]

Default value: 1

Since 0.0.4

### The `"proxy-type"` property

      "proxy-type"               guint                 : Read / Write

The type of proxy set in the proxy-ip property

Allowed values: <= 2

Default value: 0

Since 0.0.4

### The `"proxy-username"` property

      "proxy-username"           gchar*                : Read / Write

The username used to authenticate with the proxy

Default value: NULL

Since 0.0.4

### The `"reliable"` property

      "reliable"                 gboolean              : Read / Write / Construct Only

Whether the agent should use PseudoTcp to ensure a reliable transport of messages

Default value: FALSE

Since 0.0.11

### The `"stun-pacing-timer"` property

      "stun-pacing-timer"        guint                 : Read / Write / Construct Only

Timer 'Ta' (msecs) used in the IETF ICE specification for pacing candidate gathering and sending of connectivity checks.

Allowed values: >= 1

Default value: 20

### The `"stun-server"` property

      "stun-server"              gchar*                : Read / Write

The IP address (not the hostname) of the STUN server to use.

Default value: NULL

### The `"stun-server-port"` property

      "stun-server-port"         guint                 : Read / Write

Port of the STUN server used to gather server-reflexive candidates.

Allowed values: [1,65536]

Default value: 1

### The `"upnp"` property

      "upnp"                     gboolean              : Read / Write / Construct

Whether the agent should use UPnP to open a port in the router and get the external IP

Default value: TRUE

Since 0.0.7

### The `"upnp-timeout"` property

      "upnp-timeout"             guint                 : Read / Write / Construct

The maximum amount of time (in milliseconds) to wait for UPnP discovery to finish before signaling the "candidate-gathering-done" signal

Allowed values: [100,60000]

Default value: 200

Since 0.0.7

## Signal Details

### The `"candidate-gathering-done"` signal

    void                user_function                      (NiceAgent *agent,
                                                            guint      stream_id,
                                                            gpointer   user_data)      : Run Last

This signal is fired whenever a stream has finished gathering its candidates after a call to `nice_agent_gather_candidates()`

`agent` : | The NiceAgent object
`stream_id` : | The ID of the stream
`user_data` : | user data set when the signal handler was connected.

### The `"component-state-changed"` signal

    void                user_function                      (NiceAgent *agent,
                                                            guint      stream_id,
                                                            guint      component_id,
                                                            guint      state,
                                                            gpointer   user_data)         : Run Last

This signal is fired whenever a component's state changes

`agent` : | The NiceAgent object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
`state` : | The NiceComponentState of the component
`user_data` : | user data set when the signal handler was connected.

### The `"initial-binding-request-received"` signal

    void                user_function                      (NiceAgent *agent,
                                                            guint      stream_id,
                                                            gpointer   user_data)      : Run Last

This signal is fired when we received our first binding request from the peer.

`agent` : | The NiceAgent object
`stream_id` : | The ID of the stream
`user_data` : | user data set when the signal handler was connected.

### The `"new-candidate"` signal

    void                user_function                      (NiceAgent *agent,
                                                            guint      stream_id,
                                                            guint      component_id,
                                                            gchar     *foundation,
                                                            gpointer   user_data)         : Run Last

This signal is fired when the agent discovers a new local candidate.

See also: "candidate-gathering-done"

`agent` : | The NiceAgent object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
`foundation` : | The foundation of the new candidate
`user_data` : | user data set when the signal handler was connected.

### The `"new-remote-candidate"` signal

    void                user_function                      (NiceAgent *agent,
                                                            guint      stream_id,
                                                            guint      component_id,
                                                            gchar     *foundation,
                                                            gpointer   user_data)         : Run Last

This signal is fired when the agent discovers a new remote candidate. This can happen with peer reflexive candidates.

`agent` : | The NiceAgent object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
`foundation` : | The foundation of the new candidate
`user_data` : | user data set when the signal handler was connected.

### The `"new-selected-pair"` signal

    void                user_function                      (NiceAgent *agent,
                                                            guint      stream_id,
                                                            guint      component_id,
                                                            gchar     *lfoundation,
                                                            gchar     *rfoundation,
                                                            gpointer   user_data)         : Run Last

This signal is fired once a candidate pair is selected for data transfer for a stream's component

`agent` : | The NiceAgent object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
`lfoundation` : | The local foundation of the selected candidate pair
`rfoundation` : | The remote foundation of the selected candidate pair
`user_data` : | user data set when the signal handler was connected.

### The `"reliable-transport-writable"` signal

    void                user_function                      (NiceAgent *agent,
                                                            guint      stream_id,
                                                            guint      component_id,
                                                            gpointer   user_data)         : Run Last

This signal is fired on the reliable NiceAgent when the underlying reliable transport becomes writable. This signal is only emitted when the `nice_agent_send()` function returns less bytes than requested to send (or -1) and once when the connection is established.

`agent` : | The NiceAgent object
`stream_id` : | The ID of the stream
`component_id` : | The ID of the component
`user_data` : | user data set when the signal handler was connected.

Since 0.0.11

### The `"streams-removed"` signal

    void                user_function                      (NiceAgent           *agent,
                                                            _NiceAgentStreamIds *stream_ids,
                                                            gpointer             user_data)       : Run Last

This signal is fired whenever one or more streams are removed from the `agent`.

`agent` : | The NiceAgent object
`stream_ids` : | An array of unsigned integer stream IDs, ending with a 0 ID. [array zero-terminated=1][element-type uint]
`user_data` : | user data set when the signal handler was connected.

Since 0.1.5

## See Also

NiceAddress