agent/agent.h

   1 /*
   2  * This file is part of the Nice GLib ICE library.
   3  *
   4  * (C) 2006-2010 Collabora Ltd.
   5  *  Contact: Youness Alaoui
   6  * (C) 2006-2010 Nokia Corporation. All rights reserved.
   7  *  Contact: Kai Vehmanen
   8  *
   9  * The contents of this file are subject to the Mozilla Public License Version
  10  * 1.1 (the "License"); you may not use this file except in compliance with
  11  * the License. You may obtain a copy of the License at
  12  * http://www.mozilla.org/MPL/
  13  *
  14  * Software distributed under the License is distributed on an "AS IS" basis,
  15  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  16  * for the specific language governing rights and limitations under the
  17  * License.
  18  *
  19  * The Original Code is the Nice GLib ICE library.
  20  *
  21  * The Initial Developers of the Original Code are Collabora Ltd and Nokia
  22  * Corporation. All Rights Reserved.
  23  *
  24  * Contributors:
  25  *   Dafydd Harries, Collabora Ltd.
  26  *   Youness Alaoui, Collabora Ltd.
  27  *   Kai Vehmanen, Nokia
  28  *
  29  * Alternatively, the contents of this file may be used under the terms of the
  30  * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
  31  * case the provisions of LGPL are applicable instead of those above. If you
  32  * wish to allow use of your version of this file only under the terms of the
  33  * LGPL and not to allow others to use your version of this file under the
  34  * MPL, indicate your decision by deleting the provisions above and replace
  35  * them with the notice and other provisions required by the LGPL. If you do
  36  * not delete the provisions above, a recipient may use your version of this
  37  * file under either the MPL or the LGPL.
  38  */
  39
  40 #ifndef __LIBNICE_AGENT_H__
  41 #define __LIBNICE_AGENT_H__
  42
  43 /**
  44  * SECTION:agent
  45  * @short_description:  ICE agent API implementation
  46  * @see_also: #NiceCandidate, #NiceAddress
  47  * @include: agent.h
  48  * @stability: Stable
  49  *
  50  * The #NiceAgent is your main object when using libnice.
  51  * It is the agent that will take care of everything relating to ICE.
  52  * It will take care of discovering your local candidates and do
  53  *  connectivity checks to create a stream of data between you and your peer.
  54  *
  55  * A #NiceAgent must always be used with a #GMainLoop running the #GMainContext
  56  * passed into nice_agent_new() (or nice_agent_new_reliable()). Without the
  57  * #GMainContext being iterated, the agent’s timers will not fire, etc.
  58  *
  59  * Streams and their components are referenced by integer IDs (with respect to a
  60  * given #NiceAgent). These IDs are guaranteed to be positive (i.e. non-zero)
  61  * for valid streams/components.
  62  *
  63  * To complete the ICE connectivity checks, the user must either register
  64  * an I/O callback (with nice_agent_attach_recv()) or call nice_agent_recv_messages()
  65  * in a loop on a dedicated thread.
  66  * Technically, #NiceAgent does not poll the streams on its own, since
  67  * user data could arrive at any time; to receive STUN packets
  68  * required for establishing ICE connectivity, it is backpiggying
  69  * on the facility chosen by the user. #NiceAgent will handle all STUN
  70  * packets internally; they're never actually passed to the I/O callback
  71  * or returned from nice_agent_recv_messages() and related functions.
  72  *
  73  * Each stream can receive data in one of two ways: using
  74  * nice_agent_attach_recv() or nice_agent_recv_messages() (and the derived
  75  * #NiceInputStream and #NiceIOStream classes accessible using
  76  * nice_agent_get_io_stream()). nice_agent_attach_recv() is non-blocking: it
  77  * takes a user-provided callback function and attaches the stream’s socket to
  78  * the provided #GMainContext, invoking the callback in that context for every
  79  * packet received. nice_agent_recv_messages() instead blocks on receiving a
  80  * packet, and writes it directly into a user-provided buffer. This reduces the
  81  * number of callback invokations and (potentially) buffer copies required to
  82  * receive packets. nice_agent_recv_messages() (or #NiceInputStream) is designed
  83  * to be used in a blocking loop in a separate thread.
  84  *
  85  * <example>
  86  *   <title>Simple example on how to use libnice</title>
  87  *   <programlisting>
  88  *   guint stream_id;
  89  *   gchar buffer[] = "hello world!";
  90  *   gchar *ufrag = NULL, *pwd = NULL;
  91  *   gchar *remote_ufrag, *remote_pwd;
  92  *   GSList *lcands = NULL;
  93  *
  94  *   // Create a nice agent, passing in the global default GMainContext.
  95  *   NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_RFC5245);
  96  *   spawn_thread_to_run_main_loop (g_main_loop_new (NULL, FALSE));
  97  *
  98  *   // Connect the signals
  99  *   g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
 100  *                     G_CALLBACK (cb_candidate_gathering_done), NULL);
 101  *   g_signal_connect (G_OBJECT (agent), "component-state-changed",
 102  *                     G_CALLBACK (cb_component_state_changed), NULL);
 103  *   g_signal_connect (G_OBJECT (agent), "new-selected-pair",
 104  *                     G_CALLBACK (cb_new_selected_pair), NULL);
 105  *
 106  *   // Create a new stream with one component and start gathering candidates
 107  *   stream_id = nice_agent_add_stream (agent, 1);
 108  *   nice_agent_gather_candidates (agent, stream_id);
 109  *
 110  *   // Attach I/O callback the component to ensure that:
 111  *   // 1) agent gets its STUN packets (not delivered to cb_nice_recv)
 112  *   // 2) you get your own data
 113  *   nice_agent_attach_recv (agent, stream_id, 1, NULL,
 114  *                          cb_nice_recv, NULL);
 115  *
 116  *   // ... Wait until the signal candidate-gathering-done is fired ...
 117  *   lcands = nice_agent_get_local_candidates(agent, stream_id, 1);
 118
 119  *   nice_agent_get_local_credentials(agent, stream_id, &ufrag, &pwd);
 120  *
 121  *   // ... Send local candidates and credentials to the peer
 122  *
 123  *   // Set the peer's remote credentials and remote candidates
 124  *   nice_agent_set_remote_credentials (agent, stream_id, remote_ufrag, remote_pwd);
 125  *   nice_agent_set_remote_candidates (agent, stream_id, 1, rcands);
 126  *
 127  *   // ... Wait until the signal new-selected-pair is fired ...
 128  *   // Send our message!
 129  *   nice_agent_send (agent, stream_id, 1, sizeof(buffer), buffer);
 130  *
 131  *   // Anything received will be received through the cb_nice_recv callback.
 132  *   // You must be running a GMainLoop on the global default GMainContext in
 133  *   // another thread for this to work.
 134  *
 135  *   // Destroy the object
 136  *   g_object_unref(agent);
 137  *
 138  *   </programlisting>
 139  * </example>
 140  *
 141  * Refer to the examples in the examples/ subdirectory of the libnice source for
 142  * more complete examples.
 143  *
 144  */
 145
 146
 147 #include <glib-object.h>
 148 #include <gio/gio.h>
 149
 150 /**
 151  * NiceAgent:
 152  *
 153  * The #NiceAgent is the main GObject of the libnice library and represents
 154  * the ICE agent.
 155  */
 156 typedef struct _NiceAgent NiceAgent;
 157
 158 #include "address.h"
 159 #include "candidate.h"
 160 #include "debug.h"
 161
 162
 163 G_BEGIN_DECLS
 164
 165 /**
 166  * NiceInputMessage:
 167  * @buffers: (array length=n_buffers): unowned array of #GInputVector buffers to
 168  * store data in for this message
 169  * @n_buffers: number of #GInputVectors in @buffers, or -1 to indicate @buffers
 170  * is %NULL-terminated
 171  * @from: (allow-none): return location to store the address of the peer who
 172  * transmitted the message, or %NULL
 173  * @length: total number of valid bytes contiguously stored in @buffers
 174  *
 175  * Represents a single message received off the network. For reliable
 176  * connections, this is essentially just an array of buffers (specifically,
 177  * @from can be ignored). for non-reliable connections, it represents a single
 178  * packet as received from the OS.
 179  *
 180  * @n_buffers may be -1 to indicate that @buffers is terminated by a
 181  * #GInputVector with a %NULL buffer pointer.
 182  *
 183  * By providing arrays of #NiceInputMessages to functions like
 184  * nice_agent_recv_messages(), multiple messages may be received with a single
 185  * call, which is more efficient than making multiple calls in a loop. In this
 186  * manner, nice_agent_recv_messages() is analogous to recvmmsg(); and
 187  * #NiceInputMessage to struct mmsghdr.
 188  *
 189  * Since: 0.1.5
 190  */
 191 typedef struct {
 192   GInputVector *buffers;
 193   gint n_buffers;  /* may be -1 to indicate @buffers is NULL-terminated */
 194   NiceAddress *from;  /* return location for address of message sender */
 195   gsize length;  /* sum of the lengths of @buffers */
 196 } NiceInputMessage;
 197
 198 /**
 199  * NiceOutputMessage:
 200  * @buffers: (array length=n_buffers): unowned array of #GOutputVector buffers
 201  * which contain data to transmit for this message
 202  * @n_buffers: number of #GOutputVectors in @buffers, or -1 to indicate @buffers
 203  * is %NULL-terminated
 204  *
 205  * Represents a single message to transmit on the network. For
 206  * reliable connections, this is essentially just an array of
 207  * buffer. for non-reliable connections, it represents a single packet
 208  * to send to the OS.
 209  *
 210  * @n_buffers may be -1 to indicate that @buffers is terminated by a
 211  * #GOutputVector with a %NULL buffer pointer.
 212  *
 213  * By providing arrays of #NiceOutputMessages to functions like
 214  * nice_agent_send_messages_nonblocking(), multiple messages may be transmitted
 215  * with a single call, which is more efficient than making multiple calls in a
 216  * loop. In this manner, nice_agent_send_messages_nonblocking() is analogous to
 217  * sendmmsg(); and #NiceOutputMessage to struct mmsghdr.
 218  *
 219  * Since: 0.1.5
 220  */
 221 typedef struct {
 222   GOutputVector *buffers;
 223   gint n_buffers;
 224 } NiceOutputMessage;
 225
 226
 227 #define NICE_TYPE_AGENT nice_agent_get_type()
 228
 229 #define NICE_AGENT(obj) \
 230   (G_TYPE_CHECK_INSTANCE_CAST ((obj), \
 231   NICE_TYPE_AGENT, NiceAgent))
 232
 233 #define NICE_AGENT_CLASS(klass) \
 234   (G_TYPE_CHECK_CLASS_CAST ((klass), \
 235   NICE_TYPE_AGENT, NiceAgentClass))
 236
 237 #define NICE_IS_AGENT(obj) \
 238   (G_TYPE_CHECK_INSTANCE_TYPE ((obj), \
 239   NICE_TYPE_AGENT))
 240
 241 #define NICE_IS_AGENT_CLASS(klass) \
 242   (G_TYPE_CHECK_CLASS_TYPE ((klass), \
 243   NICE_TYPE_AGENT))
 244
 245 #define NICE_AGENT_GET_CLASS(obj) \
 246   (G_TYPE_INSTANCE_GET_CLASS ((obj), \
 247   NICE_TYPE_AGENT, NiceAgentClass))
 248
 249 typedef struct _NiceAgentClass NiceAgentClass;
 250
 251 struct _NiceAgentClass
 252 {
 253   GObjectClass parent_class;
 254 };
 255
 256
 257 GType nice_agent_get_type (void);
 258
 259
 260 /**
 261  * NICE_AGENT_MAX_REMOTE_CANDIDATES:
 262  *
 263  * A hard limit for the number of remote candidates. This
 264  * limit is enforced to protect against malevolent remote
 265  * clients.
 266  */
 267 #define NICE_AGENT_MAX_REMOTE_CANDIDATES    25
 268
 269 /**
 270  * NiceComponentState:
 271  * @NICE_COMPONENT_STATE_DISCONNECTED: No activity scheduled
 272  * @NICE_COMPONENT_STATE_GATHERING: Gathering local candidates
 273  * @NICE_COMPONENT_STATE_CONNECTING: Establishing connectivity
 274  * @NICE_COMPONENT_STATE_CONNECTED: At least one working candidate pair
 275  * @NICE_COMPONENT_STATE_READY: ICE concluded, candidate pair selection
 276  * is now final
 277  * @NICE_COMPONENT_STATE_FAILED: Connectivity checks have been completed,
 278  * but connectivity was not established
 279  * @NICE_COMPONENT_STATE_LAST: Dummy state
 280  *
 281  * An enum representing the state of a component.
 282  * <para> See also: #NiceAgent::component-state-changed </para>
 283  */
 284 typedef enum
 285 {
 286   NICE_COMPONENT_STATE_DISCONNECTED,
 287   NICE_COMPONENT_STATE_GATHERING,
 288   NICE_COMPONENT_STATE_CONNECTING,
 289   NICE_COMPONENT_STATE_CONNECTED,
 290   NICE_COMPONENT_STATE_READY,
 291   NICE_COMPONENT_STATE_FAILED,
 292   NICE_COMPONENT_STATE_LAST
 293 } NiceComponentState;
 294
 295
 296 /**
 297  * NiceComponentType:
 298  * @NICE_COMPONENT_TYPE_RTP: RTP Component type
 299  * @NICE_COMPONENT_TYPE_RTCP: RTCP Component type
 300  *
 301  * Convenience enum representing the type of a component for use as the
 302  * component_id for RTP/RTCP usages.
 303  <example>
 304    <title>Example of use.</title>
 305    <programlisting>
 306    nice_agent_send (agent, stream_id, NICE_COMPONENT_TYPE_RTP, len, buf);
 307    </programlisting>
 308   </example>
 309  */
 310 typedef enum
 311 {
 312   NICE_COMPONENT_TYPE_RTP = 1,
 313   NICE_COMPONENT_TYPE_RTCP = 2
 314 } NiceComponentType;
 315
 316
 317 /**
 318  * NiceCompatibility:
 319  * @NICE_COMPATIBILITY_RFC5245: Use compatibility with the RFC5245 ICE-UDP specs
 320  * and RFC6544 ICE-TCP specs
 321  * @NICE_COMPATIBILITY_GOOGLE: Use compatibility for Google Talk specs
 322  * @NICE_COMPATIBILITY_MSN: Use compatibility for MSN Messenger specs
 323  * @NICE_COMPATIBILITY_WLM2009: Use compatibility with Windows Live Messenger
 324  * 2009
 325  * @NICE_COMPATIBILITY_OC2007: Use compatibility with Microsoft Office Communicator 2007
 326  * @NICE_COMPATIBILITY_OC2007R2: Use compatibility with Microsoft Office Communicator 2007 R2
 327  * @NICE_COMPATIBILITY_DRAFT19: Use compatibility for ICE Draft 19 specs
 328  * @NICE_COMPATIBILITY_LAST: Dummy last compatibility mode
 329  *
 330  * An enum to specify which compatible specifications the #NiceAgent should use.
 331  * Use with nice_agent_new()
 332  *
 333  * <warning>@NICE_COMPATIBILITY_DRAFT19 is deprecated and should not be used
 334  * in newly-written code. It is kept for compatibility reasons and
 335  * represents the same compatibility as @NICE_COMPATIBILITY_RFC5245 </warning>
 336  <note>
 337    <para>
 338    If @NICE_COMPATIBILITY_RFC5245 compatibility mode is used for a non-reliable
 339    agent, then ICE-UDP will be used with higher priority and ICE-TCP will also
 340    be used when the UDP connectivity fails. If it is used with a reliable agent,
 341    then ICE-UDP will be used with the TCP-Over-UDP (#PseudoTcpSocket) if ICE-TCP
 342    fails and ICE-UDP succeeds.
 343   </para>
 344  </note>
 345  *
 346  */
 347 typedef enum
 348 {
 349   NICE_COMPATIBILITY_RFC5245 = 0,
 350   NICE_COMPATIBILITY_DRAFT19 = NICE_COMPATIBILITY_RFC5245,
 351   NICE_COMPATIBILITY_GOOGLE,
 352   NICE_COMPATIBILITY_MSN,
 353   NICE_COMPATIBILITY_WLM2009,
 354   NICE_COMPATIBILITY_OC2007,
 355   NICE_COMPATIBILITY_OC2007R2,
 356   NICE_COMPATIBILITY_LAST = NICE_COMPATIBILITY_OC2007R2,
 357 } NiceCompatibility;
 358
 359 /**
 360  * NiceProxyType:
 361  * @NICE_PROXY_TYPE_NONE: Do not use a proxy
 362  * @NICE_PROXY_TYPE_SOCKS5: Use a SOCKS5 proxy
 363  * @NICE_PROXY_TYPE_HTTP: Use an HTTP proxy
 364  * @NICE_PROXY_TYPE_LAST: Dummy last proxy type
 365  *
 366  * An enum to specify which proxy type to use for relaying.
 367  * Note that the proxies will only be used with TCP TURN relaying.
 368  * <para> See also: #NiceAgent:proxy-type </para>
 369  *
 370  * Since: 0.0.4
 371  */
 372 typedef enum
 373 {
 374   NICE_PROXY_TYPE_NONE = 0,
 375   NICE_PROXY_TYPE_SOCKS5,
 376   NICE_PROXY_TYPE_HTTP,
 377   NICE_PROXY_TYPE_LAST = NICE_PROXY_TYPE_HTTP,
 378 } NiceProxyType;
 379
 380 /**
 381  * NiceNominationMode:
 382  * @NICE_NOMINATION_MODE_AGGRESSIVE: Aggressive nomination mode
 383  * @NICE_NOMINATION_MODE_REGULAR: Regular nomination mode
 384  *
 385  * An enum to specity the kind of nomination mode to use by
 386  * the agent, as described in RFC 5245. Two modes exists,
 387  * regular and aggressive. They differ by the way the controlling
 388  * agent chooses to put the USE-CANDIDATE attribute in its STUN
 389  * messages. The aggressive mode is supposed to nominate a pair
 390  * faster, than the regular mode, potentially causing the nominated
 391  * pair to change until the connection check completes.
 392  *
 393  * Since: 0.1.15
 394  */
 395 typedef enum
 396 {
 397   NICE_NOMINATION_MODE_REGULAR = 0,
 398   NICE_NOMINATION_MODE_AGGRESSIVE,
 399 } NiceNominationMode;
 400
 401 /**
 402  * NiceAgentOption:
 403  * @NICE_AGENT_OPTION_REGULAR_NOMINATION: Enables regular nomination, default
 404  *  is aggrssive mode (see #NiceNominationMode).
 405  * @NICE_AGENT_OPTION_RELIABLE: Enables reliable mode, possibly using PseudoTCP, *  see nice_agent_new_reliable().
 406  * @NICE_AGENT_OPTION_LITE_MODE: Enable lite mode
 407  * @NICE_AGENT_OPTION_ICE_TRICKLE: Enable ICE trickle mode
 408  * @NICE_AGENT_OPTION_SUPPORT_RENOMINATION: Enable renomination triggered by NOMINATION STUN attribute
 409  * proposed here: https://tools.ietf.org/html/draft-thatcher-ice-renomination-00
 410  *
 411  * These are options that can be passed to nice_agent_new_full(). They set
 412  * various properties on the agent. Not including them sets the property to
 413  * the other value.
 414  *
 415  * Since: 0.1.15
 416  */
 417 typedef enum {
 418   NICE_AGENT_OPTION_REGULAR_NOMINATION = 1 << 0,
 419   NICE_AGENT_OPTION_RELIABLE = 1 << 1,
 420   NICE_AGENT_OPTION_LITE_MODE = 1 << 2,
 421   NICE_AGENT_OPTION_ICE_TRICKLE = 1 << 3,
 422   NICE_AGENT_OPTION_SUPPORT_RENOMINATION = 1 << 4,
 423 } NiceAgentOption;
 424
 425 /**
 426  * NiceAgentRecvFunc:
 427  * @agent: The #NiceAgent Object
 428  * @stream_id: The id of the stream
 429  * @component_id: The id of the component of the stream
 430  *        which received the data
 431  * @len: The length of the data
 432  * @buf: The buffer containing the data received
 433  * @user_data: The user data set in nice_agent_attach_recv()
 434  *
 435  * Callback function when data is received on a component
 436  *
 437  */
 438 typedef void (*NiceAgentRecvFunc) (
 439   NiceAgent *agent, guint stream_id, guint component_id, guint len,
 440   gchar *buf, gpointer user_data);
 441
 442
 443 /**
 444  * nice_agent_new:
 445  * @ctx: The Glib Mainloop Context to use for timers
 446  * @compat: The compatibility mode of the agent
 447  *
 448  * Create a new #NiceAgent.
 449  * The returned object must be freed with g_object_unref()
 450  *
 451  * Returns: The new agent GObject
 452  */
 453 NiceAgent *
 454 nice_agent_new (GMainContext *ctx, NiceCompatibility compat);
 455
 456
 457 /**
 458  * nice_agent_new_reliable:
 459  * @ctx: The Glib Mainloop Context to use for timers
 460  * @compat: The compatibility mode of the agent
 461  *
 462  * Create a new #NiceAgent in reliable mode. If the connectivity is established
 463  * through ICE-UDP, then a #PseudoTcpSocket will be transparently used to
 464  * ensure reliability of the messages.
 465  * The returned object must be freed with g_object_unref()
 466  * <para> See also: #NiceAgent::reliable-transport-writable </para>
 467  *
 468  * Since: 0.0.11
 469  *
 470  * Returns: The new agent GObject
 471  */
 472 NiceAgent *
 473 nice_agent_new_reliable (GMainContext *ctx, NiceCompatibility compat);
 474
 475 /**
 476  * nice_agent_new_full:
 477  * @ctx: The Glib Mainloop Context to use for timers
 478  * @compat: The compatibility mode of the agent
 479  * @flags: Flags to set the properties
 480  *
 481  * Create a new #NiceAgent with parameters that must be be defined at
 482  * construction time.
 483  * The returned object must be freed with g_object_unref()
 484  * <para> See also: #NiceNominationMode and #NiceAgentOption</para>
 485  *
 486  * Since: 0.1.15
 487  *
 488  * Returns: The new agent GObject
 489  */
 490 NiceAgent *
 491 nice_agent_new_full (GMainContext *ctx,
 492   NiceCompatibility compat,
 493   NiceAgentOption flags);
 494
 495 /**
 496  * nice_agent_add_local_address:
 497  * @agent: The #NiceAgent Object
 498  * @addr: The address to listen to
 499  * If the port is 0, then a random port will be chosen by the system
 500  *
 501  * Add a local address from which to derive local host candidates for
 502  * candidate gathering.
 503  * <para>
 504  * Since 0.0.5, if this method is not called, libnice will automatically
 505  * discover the local addresses available
 506  * </para>
 507  *
 508  * See also: nice_agent_gather_candidates()
 509  * Returns: %TRUE on success, %FALSE on fatal (memory allocation) errors
 510  */
 511 gboolean
 512 nice_agent_add_local_address (NiceAgent *agent, NiceAddress *addr);
 513
 514 /**
 515  * nice_agent_add_stream:
 516  * @agent: The #NiceAgent Object
 517  * @n_components: The number of components to add to the stream
 518  *
 519  * Adds a data stream to @agent containing @n_components components. The
 520  * returned stream ID is guaranteed to be positive on success.
 521  *
 522  * Returns: The ID of the new stream, 0 on failure
 523  **/
 524 guint
 525 nice_agent_add_stream (
 526   NiceAgent *agent,
 527   guint n_components);
 528
 529 /**
 530  * nice_agent_remove_stream:
 531  * @agent: The #NiceAgent Object
 532  * @stream_id: The ID of the stream to remove
 533  *
 534  * Remove and free a previously created data stream from @agent. If any I/O
 535  * streams have been created using nice_agent_get_io_stream(), they should be
 536  * closed completely using g_io_stream_close() before this is called, or they
 537  * will get broken pipe errors.
 538  *
 539  **/
 540 void
 541 nice_agent_remove_stream (
 542   NiceAgent *agent,
 543   guint stream_id);
 544
 545
 546 /**
 547  * nice_agent_set_port_range:
 548  * @agent: The #NiceAgent Object
 549  * @stream_id: The ID of the stream
 550  * @component_id: The ID of the component
 551  * @min_port: The minimum port to use
 552  * @max_port: The maximum port to use
 553  *
 554  * Sets a preferred port range for allocating host candidates.
 555  * <para>
 556  * If a local host candidate cannot be created on that port
 557  * range, then the nice_agent_gather_candidates() call will fail.
 558  * </para>
 559  * <para>
 560  * This MUST be called before nice_agent_gather_candidates()
 561  * </para>
 562  *
 563  */
 564 void
 565 nice_agent_set_port_range (
 566     NiceAgent *agent,
 567     guint stream_id,
 568     guint component_id,
 569     guint min_port,
 570     guint max_port);
 571
 572 /**
 573  * nice_agent_set_relay_info:
 574  * @agent: The #NiceAgent Object
 575  * @stream_id: The ID of the stream
 576  * @component_id: The ID of the component
 577  * @server_ip: The IP address of the TURN server
 578  * @server_port: The port of the TURN server
 579  * @username: The TURN username to use for the allocate
 580  * @password: The TURN password to use for the allocate
 581  * @type: The type of relay to use
 582  *
 583  * Sets the settings for using a relay server during the candidate discovery.
 584  * This may be called multiple times to add multiple relay servers to the
 585  * discovery process; one TCP and one UDP, for example.
 586  *
 587  * Returns: %TRUE if the TURN settings were accepted.
 588  * %FALSE if the address was invalid.
 589  */
 590 gboolean nice_agent_set_relay_info(
 591     NiceAgent *agent,
 592     guint stream_id,
 593     guint component_id,
 594     const gchar *server_ip,
 595     guint server_port,
 596     const gchar *username,
 597     const gchar *password,
 598     NiceRelayType type);
 599
 600 /**
 601  * nice_agent_gather_candidates:
 602  * @agent: The #NiceAgent object
 603  * @stream_id: The ID of the stream to start
 604  *
 605  * Allocate and start listening on local candidate ports and start the remote
 606  * candidate gathering process.
 607  * Once done, #NiceAgent::candidate-gathering-done is called for the stream.
 608  * As soon as this function is called, #NiceAgent::new-candidate signals may be
 609  * emitted, even before this function returns.
 610  *
 611  * nice_agent_get_local_candidates() will only return non-empty results after
 612  * calling this function.
 613  *
 614  * <para>See also: nice_agent_add_local_address()</para>
 615  * <para>See also: nice_agent_set_port_range()</para>
 616  *
 617  * Returns: %FALSE if the stream ID is invalid or if a host candidate couldn't
 618  * be allocated on the requested interfaces/ports; %TRUE otherwise
 619  *
 620  <note>
 621    <para>
 622     Local addresses can be previously set with nice_agent_add_local_address()
 623   </para>
 624   <para>
 625     Since 0.0.5, If no local address was previously added, then the nice agent
 626     will automatically detect the local address using
 627     nice_interfaces_get_local_ips()
 628    </para>
 629  </note>
 630  */
 631 gboolean
 632 nice_agent_gather_candidates (
 633   NiceAgent *agent,
 634   guint stream_id);
 635
 636 /**
 637  * nice_agent_set_remote_credentials:
 638  * @agent: The #NiceAgent Object
 639  * @stream_id: The ID of the stream
 640  * @ufrag: nul-terminated string containing an ICE username fragment
 641  *    (length must be between 22 and 256 chars)
 642  * @pwd: nul-terminated string containing an ICE password
 643  *    (length must be between 4 and 256 chars)
 644  *
 645  * Sets the remote credentials for stream @stream_id.
 646  *
 647  <note>
 648    <para>
 649      Stream credentials do not override per-candidate credentials if set
 650    </para>
 651    <para>
 652      Due to the native of peer-reflexive candidates, any agent using a per-stream
 653      credentials (RFC5245, WLM2009, OC2007R2 and DRAFT19) instead of
 654      per-candidate credentials (GOOGLE, MSN, OC2007), must
 655      use the nice_agent_set_remote_credentials() API instead of setting the
 656      username and password on the candidates.
 657    </para>
 658  </note>
 659  *
 660  * Returns: %TRUE on success, %FALSE on error.
 661  */
 662 gboolean
 663 nice_agent_set_remote_credentials (
 664   NiceAgent *agent,
 665   guint stream_id,
 666   const gchar *ufrag, const gchar *pwd);
 667
 668
 669 /**
 670  * nice_agent_set_local_credentials:
 671  * @agent: The #NiceAgent Object
 672  * @stream_id: The ID of the stream
 673  * @ufrag: nul-terminated string containing an ICE username fragment
 674  *    (length must be between 22 and 256 chars)
 675  * @pwd: nul-terminated string containing an ICE password
 676  *    (length must be between 4 and 256 chars)
 677  *
 678  * Sets the local credentials for stream @stream_id.
 679  *
 680  <note>
 681    <para>
 682      This is only effective before ICE negotiation has started.
 683    </para>
 684  </note>
 685  *
 686  * Since 0.1.11
 687  * Returns: %TRUE on success, %FALSE on error.
 688  */
 689 gboolean
 690 nice_agent_set_local_credentials (
 691   NiceAgent *agent,
 692   guint stream_id,
 693   const gchar *ufrag,
 694   const gchar *pwd);
 695
 696
 697 /**
 698  * nice_agent_get_local_credentials:
 699  * @agent: The #NiceAgent Object
 700  * @stream_id: The ID of the stream
 701  * @ufrag: (out callee-allocates): return location for a nul-terminated string
 702  * containing an ICE username fragment; must be freed with g_free()
 703  * @pwd: (out callee-allocates): return location for a nul-terminated string
 704  * containing an ICE password; must be freed with g_free()
 705  *
 706  * Gets the local credentials for stream @stream_id. This may be called any time
 707  * after creating a stream using nice_agent_add_stream().
 708  *
 709  * An error will be returned if this is called for a non-existent stream, or if
 710  * either of @ufrag or @pwd are %NULL.
 711  *
 712  * Returns: %TRUE on success, %FALSE on error.
 713  */
 714 gboolean
 715 nice_agent_get_local_credentials (
 716   NiceAgent *agent,
 717   guint stream_id,
 718   gchar **ufrag, gchar **pwd);
 719
 720 /**
 721  * nice_agent_set_remote_candidates:
 722  * @agent: The #NiceAgent Object
 723  * @stream_id: The ID of the stream the candidates are for
 724  * @component_id: The ID of the component the candidates are for
 725  * @candidates: (element-type NiceCandidate) (transfer none): a #GSList of
 726  * #NiceCandidate items describing each candidate to add
 727  *
 728  * Sets, adds or updates the remote candidates for a component of a stream.
 729  *
 730  <note>
 731    <para>
 732     NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit
 733     for remote candidates.
 734    </para>
 735    <para>
 736    You must first call nice_agent_gather_candidates() and wait for the
 737    #NiceAgent::candidate-gathering-done signale before
 738    calling nice_agent_set_remote_candidates()
 739    </para>
 740    <para>
 741     Since 0.1.3, there is no need to wait for the candidate-gathering-done signal.
 742     Remote candidates can be set even while gathering local candidates.
 743     Newly discovered local candidates will automatically be paired with
 744     existing remote candidates.
 745    </para>
 746  </note>
 747  *
 748  * Returns: The number of candidates added, negative on errors (memory
 749  * allocation error or invalid component)
 750  **/
 751 int
 752 nice_agent_set_remote_candidates (
 753   NiceAgent *agent,
 754   guint stream_id,
 755   guint component_id,
 756   const GSList *candidates);
 757
 758
 759 /**
 760  * nice_agent_send:
 761  * @agent: The #NiceAgent Object
 762  * @stream_id: The ID of the stream to send to
 763  * @component_id: The ID of the component to send to
 764  * @len: The length of the buffer to send
 765  * @buf: The buffer of data to send
 766  *
 767  * Sends a data payload over a stream's component.
 768  *
 769  <note>
 770    <para>
 771      Component state MUST be NICE_COMPONENT_STATE_READY, or as a special case,
 772      in any state if component was in READY state before and was then restarted
 773    </para>
 774    <para>
 775    In reliable mode, the -1 error value means either that you are not yet
 776    connected or that the send buffer is full (equivalent to EWOULDBLOCK).
 777    In both cases, you simply need to wait for the
 778    #NiceAgent::reliable-transport-writable signal to be fired before resending
 779    the data.
 780    </para>
 781    <para>
 782    In non-reliable mode, it will virtually never happen with UDP sockets, but
 783    it might happen if the active candidate is a TURN-TCP connection that got
 784    disconnected.
 785    </para>
 786    <para>
 787    In both reliable and non-reliable mode, a -1 error code could also mean that
 788    the stream_id and/or component_id are invalid.
 789    </para>
 790 </note>
 791  *
 792  * Returns: The number of bytes sent, or negative error code
 793  */
 794 gint
 795 nice_agent_send (
 796   NiceAgent *agent,
 797   guint stream_id,
 798   guint component_id,
 799   guint len,
 800   const gchar *buf);
 801
 802 /**
 803  * nice_agent_send_messages_nonblocking:
 804  * @agent: a #NiceAgent
 805  * @stream_id: the ID of the stream to send to
 806  * @component_id: the ID of the component to send to
 807  * @messages: (array length=n_messages): array of messages to send, of at least
 808  * @n_messages entries in length
 809  * @n_messages: number of entries in @messages
 810  * @cancellable: (allow-none): a #GCancellable to cancel the operation from
 811  * another thread, or %NULL
 812  * @error: (allow-none): return location for a #GError, or %NULL
 813  *
 814  * Sends multiple messages on the socket identified by the given
 815  * stream/component pair. Transmission is non-blocking, so a
 816  * %G_IO_ERROR_WOULD_BLOCK error may be returned if the send buffer is full.
 817  *
 818  * As with nice_agent_send(), the given component must be in
 819  * %NICE_COMPONENT_STATE_READY or, as a special case, in any state if it was
 820  * previously ready and was then restarted.
 821  *
 822  * On success, the number of messages written to the socket will be returned,
 823  * which may be less than @n_messages if transmission would have blocked
 824  * part-way through. Zero will be returned if @n_messages is zero, or if
 825  * transmission would have blocked on the first message.
 826  *
 827  * In reliable mode, it is instead recommended to use
 828  * nice_agent_send().  The return value can be less than @n_messages
 829  * or 0 even if it is still possible to send a partial message. In
 830  * this case, "nice-agent-writable" will never be triggered, so the
 831  * application would have to use nice_agent_sent() to fill the buffer or have
 832  * to retry sending at a later point.
 833  *
 834  * On failure, -1 will be returned and @error will be set. If the #NiceAgent is
 835  * reliable and the socket is not yet connected, %G_IO_ERROR_BROKEN_PIPE will be
 836  * returned; if the write buffer is full, %G_IO_ERROR_WOULD_BLOCK will be
 837  * returned. In both cases, wait for the #NiceAgent::reliable-transport-writable
 838  * signal before trying again. If the given @stream_id or @component_id are
 839  * invalid or not yet connected, %G_IO_ERROR_BROKEN_PIPE will be returned.
 840  * %G_IO_ERROR_FAILED will be returned for other errors.
 841  *
 842  * Returns: the number of messages sent (may be zero), or -1 on error
 843  *
 844  * Since: 0.1.5
 845  */
 846 gint
 847 nice_agent_send_messages_nonblocking (
 848     NiceAgent *agent,
 849     guint stream_id,
 850     guint component_id,
 851     const NiceOutputMessage *messages,
 852     guint n_messages,
 853     GCancellable *cancellable,
 854     GError **error);
 855
 856 /**
 857  * nice_agent_get_local_candidates:
 858  * @agent: The #NiceAgent Object
 859  * @stream_id: The ID of the stream
 860  * @component_id: The ID of the component
 861  *
 862  * Retrieve from the agent the list of all local candidates
 863  * for a stream's component
 864  *
 865  <note>
 866    <para>
 867      The caller owns the returned GSList as well as the candidates contained
 868      within it.
 869      To get full results, the client should wait for the
 870      #NiceAgent::candidate-gathering-done signal.
 871    </para>
 872  </note>
 873  *
 874  * Returns: (element-type NiceCandidate) (transfer full): a #GSList of
 875  * #NiceCandidate objects representing the local candidates of @agent
 876  **/
 877 GSList *
 878 nice_agent_get_local_candidates (
 879   NiceAgent *agent,
 880   guint stream_id,
 881   guint component_id);
 882
 883
 884 /**
 885  * nice_agent_get_remote_candidates:
 886  * @agent: The #NiceAgent Object
 887  * @stream_id: The ID of the stream
 888  * @component_id: The ID of the component
 889  *
 890  * Get a list of the remote candidates set on a stream's component
 891  *
 892  <note>
 893    <para>
 894      The caller owns the returned GSList as well as the candidates contained
 895      within it.
 896    </para>
 897    <para>
 898      The list of remote candidates can change during processing.
 899      The client should register for the #NiceAgent::new-remote-candidate signal
 900      to get notified of new remote candidates.
 901    </para>
 902  </note>
 903  *
 904  * Returns: (element-type NiceCandidate) (transfer full): a #GSList of
 905  * #NiceCandidates objects representing the remote candidates set on the @agent
 906  **/
 907 GSList *
 908 nice_agent_get_remote_candidates (
 909   NiceAgent *agent,
 910   guint stream_id,
 911   guint component_id);
 912
 913 /**
 914  * nice_agent_restart:
 915  * @agent: The #NiceAgent Object
 916  *
 917  * Restarts the session as defined in ICE draft 19. This function
 918  * needs to be called both when initiating (ICE spec section 9.1.1.1.
 919  * "ICE Restarts"), as well as when reacting (spec section 9.2.1.1.
 920  * "Detecting ICE Restart") to a restart.
 921  *
 922  * Returns: %TRUE on success %FALSE on error
 923  **/
 924 gboolean
 925 nice_agent_restart (
 926   NiceAgent *agent);
 927
 928 /**
 929  * nice_agent_restart_stream:
 930  * @agent: The #NiceAgent Object
 931  * @stream_id: The ID of the stream
 932  *
 933  * Restarts a single stream as defined in RFC 5245. This function
 934  * needs to be called both when initiating (ICE spec section 9.1.1.1.
 935  * "ICE Restarts"), as well as when reacting (spec section 9.2.1.1.
 936  * "Detecting ICE Restart") to a restart.
 937  *
 938  * Unlike nice_agent_restart(), this applies to a single stream. It also
 939  * does not generate a new tie breaker.
 940  *
 941  * Returns: %TRUE on success %FALSE on error
 942  *
 943  * Since: 0.1.6
 944  **/
 945 gboolean
 946 nice_agent_restart_stream (
 947     NiceAgent *agent,
 948     guint stream_id);
 949
 950
 951 /**
 952  * nice_agent_attach_recv: (skip)
 953  * @agent: The #NiceAgent Object
 954  * @stream_id: The ID of stream
 955  * @component_id: The ID of the component
 956  * @ctx: The Glib Mainloop Context to use for listening on the component
 957  * @func: The callback function to be called when data is received on
 958  * the stream's component (will not be called for STUN messages that
 959  * should be handled by #NiceAgent itself)
 960  * @data: user data associated with the callback
 961  *
 962  * Attaches the stream's component's sockets to the Glib Mainloop Context in
 963  * order to be notified whenever data becomes available for a component,
 964  * and to enable #NiceAgent to receive STUN messages (during the
 965  * establishment of ICE connectivity).
 966  *
 967  * This must not be used in combination with nice_agent_recv_messages() (or
 968  * #NiceIOStream or #NiceInputStream) on the same stream/component pair.
 969  *
 970  * Calling nice_agent_attach_recv() with a %NULL @func will detach any existing
 971  * callback and cause reception to be paused for the given stream/component
 972  * pair. You must iterate the previously specified #GMainContext sufficiently to
 973  * ensure all pending I/O callbacks have been received before calling this
 974  * function to unset @func, otherwise data loss of received packets may occur.
 975  *
 976  * Returns: %TRUE on success, %FALSE if the stream or component IDs are invalid.
 977  */
 978 gboolean
 979 nice_agent_attach_recv (
 980   NiceAgent *agent,
 981   guint stream_id,
 982   guint component_id,
 983   GMainContext *ctx,
 984   NiceAgentRecvFunc func,
 985   gpointer data);
 986
 987 /**
 988  * nice_agent_recv:
 989  * @agent: a #NiceAgent
 990  * @stream_id: the ID of the stream to receive on
 991  * @component_id: the ID of the component to receive on
 992  * @buf: (array length=buf_len) (out caller-allocates): caller-allocated buffer
 993  * to write the received data into, of length at least @buf_len
 994  * @buf_len: length of @buf
 995  * @cancellable: (allow-none): a #GCancellable to allow the operation to be
 996  * cancelled from another thread, or %NULL
 997  * @error: (allow-none): return location for a #GError, or %NULL
 998  *
 999  * A single-message version of nice_agent_recv_messages().
1000  *
1001  * Returns: the number of bytes written to @buf on success (guaranteed to be
1002  * greater than 0 unless @buf_len is 0), 0 if in reliable mode and the remote
1003  * peer closed the stream, or -1 on error
1004  *
1005  * Since: 0.1.5
1006  */
1007 gssize
1008 nice_agent_recv (
1009     NiceAgent *agent,
1010     guint stream_id,
1011     guint component_id,
1012     guint8 *buf,
1013     gsize buf_len,
1014     GCancellable *cancellable,
1015     GError **error);
1016
1017 /**
1018  * nice_agent_recv_messages:
1019  * @agent: a #NiceAgent
1020  * @stream_id: the ID of the stream to receive on
1021  * @component_id: the ID of the component to receive on
1022  * @messages: (array length=n_messages) (out caller-allocates): caller-allocated
1023  * array of #NiceInputMessages to write the received messages into, of length at
1024  * least @n_messages
1025  * @n_messages: number of entries in @messages
1026  * @cancellable: (allow-none): a #GCancellable to allow the operation to be
1027  * cancelled from another thread, or %NULL
1028  * @error: (allow-none): return location for a #GError, or %NULL
1029  *
1030  * Block on receiving data from the given stream/component combination on
1031  * @agent, returning only once exactly @n_messages messages have been received
1032  * and written into @messages, the stream is closed by the other end or by
1033  * calling nice_agent_remove_stream(), or @cancellable is cancelled.
1034  *
1035  * Any STUN packets received will not be added to @messages; instead,
1036  * they'll be passed for processing to #NiceAgent itself. Since #NiceAgent
1037  * does not poll for messages on its own, it's therefore essential to keep
1038  * calling this function for ICE connection establishment to work.
1039  *
1040  * In the non-error case, in reliable mode, this will block until all buffers in
1041  * all @n_messages have been filled with received data (i.e. @messages is
1042  * treated as a large, flat array of buffers). In non-reliable mode, it will
1043  * block until @n_messages messages have been received, each of which does not
1044  * have to fill all the buffers in its #NiceInputMessage. In the non-reliable
1045  * case, each #NiceInputMessage must have enough buffers to contain an entire
1046  * message (65536 bytes), or any excess data may be silently dropped.
1047  *
1048  * For each received message, #NiceInputMessage::length will be set to the
1049  * number of valid bytes stored in the message’s buffers. The bytes are stored
1050  * sequentially in the buffers; there are no gaps apart from at the end of the
1051  * buffer array (in non-reliable mode). If non-%NULL on input,
1052  * #NiceInputMessage::from will have the address of the sending peer stored in
1053  * it. The base addresses, sizes, and number of buffers in each message will not
1054  * be modified in any case.
1055  *
1056  * This must not be used in combination with nice_agent_attach_recv() on the
1057  * same stream/component pair.
1058  *
1059  * If the stream/component pair doesn’t exist, or if a suitable candidate socket
1060  * hasn’t yet been selected for it, a %G_IO_ERROR_BROKEN_PIPE error will be
1061  * returned. A %G_IO_ERROR_CANCELLED error will be returned if the operation was
1062  * cancelled. %G_IO_ERROR_FAILED will be returned for other errors.
1063  *
1064  * Returns: the number of valid messages written to @messages on success
1065  * (guaranteed to be greater than 0 unless @n_messages is 0), 0 if the remote
1066  * peer closed the stream, or -1 on error
1067  *
1068  * Since: 0.1.5
1069  */
1070 gint
1071 nice_agent_recv_messages (
1072     NiceAgent *agent,
1073     guint stream_id,
1074     guint component_id,
1075     NiceInputMessage *messages,
1076     guint n_messages,
1077     GCancellable *cancellable,
1078     GError **error);
1079
1080 /**
1081  * nice_agent_recv_nonblocking:
1082  * @agent: a #NiceAgent
1083  * @stream_id: the ID of the stream to receive on
1084  * @component_id: the ID of the component to receive on
1085  * @buf: (array length=buf_len) (out caller-allocates): caller-allocated buffer
1086  * to write the received data into, of length at least @buf_len
1087  * @buf_len: length of @buf
1088  * @cancellable: (allow-none): a #GCancellable to allow the operation to be
1089  * cancelled from another thread, or %NULL
1090  * @error: (allow-none): return location for a #GError, or %NULL
1091  *
1092  * A single-message version of nice_agent_recv_messages_nonblocking().
1093  *
1094  * Returns: the number of bytes received into @buf on success (guaranteed to be
1095  * greater than 0 unless @buf_len is 0), 0 if in reliable mode and the remote
1096  * peer closed the stream, or -1 on error
1097  *
1098  * Since: 0.1.5
1099  */
1100 gssize
1101 nice_agent_recv_nonblocking (
1102     NiceAgent *agent,
1103     guint stream_id,
1104     guint component_id,
1105     guint8 *buf,
1106     gsize buf_len,
1107     GCancellable *cancellable,
1108     GError **error);
1109
1110 /**
1111  * nice_agent_recv_messages_nonblocking:
1112  * @agent: a #NiceAgent
1113  * @stream_id: the ID of the stream to receive on
1114  * @component_id: the ID of the component to receive on
1115  * @messages: (array length=n_messages) (out caller-allocates): caller-allocated
1116  * array of #NiceInputMessages to write the received messages into, of length at
1117  * least @n_messages
1118  * @n_messages: number of entries in @messages
1119  * @cancellable: (allow-none): a #GCancellable to allow the operation to be
1120  * cancelled from another thread, or %NULL
1121  * @error: (allow-none): return location for a #GError, or %NULL
1122  *
1123  * Try to receive data from the given stream/component combination on @agent,
1124  * without blocking. If receiving data would block, -1 is returned and
1125  * %G_IO_ERROR_WOULD_BLOCK is set in @error. If any other error occurs, -1 is
1126  * returned and @error is set accordingly. Otherwise, 0 is returned if (and only
1127  * if) @n_messages is 0. In all other cases, the number of valid messages stored
1128  * in @messages is returned, and will be greater than 0.
1129  *
1130  * This function behaves similarly to nice_agent_recv_messages(), except that it
1131  * will not block on filling (in reliable mode) or receiving (in non-reliable
1132  * mode) exactly @n_messages messages. In reliable mode, it will receive bytes
1133  * into @messages until it would block; in non-reliable mode, it will receive
1134  * messages until it would block.
1135  *
1136  * Any STUN packets received will not be added to @messages; instead,
1137  * they'll be passed for processing to #NiceAgent itself. Since #NiceAgent
1138  * does not poll for messages on its own, it's therefore essential to keep
1139  * calling this function for ICE connection establishment to work.
1140  *
1141  * As this function is non-blocking, @cancellable is included only for parity
1142  * with nice_agent_recv_messages(). If @cancellable is cancelled before this
1143  * function is called, a %G_IO_ERROR_CANCELLED error will be returned
1144  * immediately.
1145  *
1146  * This must not be used in combination with nice_agent_attach_recv() on the
1147  * same stream/component pair.
1148  *
1149  * Returns: the number of valid messages written to @messages on success
1150  * (guaranteed to be greater than 0 unless @n_messages is 0), 0 if in reliable
1151  * mode and the remote peer closed the stream, or -1 on error
1152  *
1153  * Since: 0.1.5
1154  */
1155 gint
1156 nice_agent_recv_messages_nonblocking (
1157     NiceAgent *agent,
1158     guint stream_id,
1159     guint component_id,
1160     NiceInputMessage *messages,
1161     guint n_messages,
1162     GCancellable *cancellable,
1163     GError **error);
1164
1165 /**
1166  * nice_agent_set_selected_pair:
1167  * @agent: The #NiceAgent Object
1168  * @stream_id: The ID of the stream
1169  * @component_id: The ID of the component
1170  * @lfoundation: The local foundation of the candidate to use
1171  * @rfoundation: The remote foundation of the candidate to use
1172  *
1173  * Sets the selected candidate pair for media transmission
1174  * for a given stream's component. Calling this function will
1175  * disable all further ICE processing (connection check,
1176  * state machine updates, etc). Note that keepalives will
1177  * continue to be sent.
1178  *
1179  * Returns: %TRUE on success, %FALSE if the candidate pair cannot be found
1180  */
1181 gboolean
1182 nice_agent_set_selected_pair (
1183   NiceAgent *agent,
1184   guint stream_id,
1185   guint component_id,
1186   const gchar *lfoundation,
1187   const gchar *rfoundation);
1188
1189 /**
1190  * nice_agent_get_selected_pair:
1191  * @agent: The #NiceAgent Object
1192  * @stream_id: The ID of the stream
1193  * @component_id: The ID of the component
1194  * @local: The local selected candidate
1195  * @remote: The remote selected candidate
1196  *
1197  * Retreive the selected candidate pair for media transmission
1198  * for a given stream's component.
1199  *
1200  * Returns: %TRUE on success, %FALSE if there is no selected candidate pair
1201  */
1202 gboolean
1203 nice_agent_get_selected_pair (
1204   NiceAgent *agent,
1205   guint stream_id,
1206   guint component_id,
1207   NiceCandidate **local,
1208   NiceCandidate **remote);
1209
1210 /**
1211  * nice_agent_get_selected_socket:
1212  * @agent: The #NiceAgent Object
1213  * @stream_id: The ID of the stream
1214  * @component_id: The ID of the component
1215  *
1216  * Retreive the local socket associated with the selected candidate pair
1217  * for media transmission for a given stream's component.
1218  *
1219  * This is useful for adding ICE support to legacy applications that already
1220  * have a protocol that maintains a connection. If the socket is duplicated
1221  * before unrefing the agent, the application can take over and continue to use
1222  * it. New applications are encouraged to use the built in libnice stream
1223  * handling instead and let libnice handle the connection maintenance.
1224  *
1225  * Users of this method are encouraged to not use a TURN relay or any kind
1226  * of proxy, as in this case, the socket will not be available to the
1227  * application because the packets are encapsulated.
1228  *
1229  * Returns: (transfer full) (nullable): pointer to the #GSocket, or %NULL if
1230  * there is no selected candidate or if the selected candidate is a relayed
1231  * candidate.
1232  *
1233  * Since: 0.1.5
1234  */
1235 GSocket *
1236 nice_agent_get_selected_socket (
1237   NiceAgent *agent,
1238   guint stream_id,
1239   guint component_id);
1240
1241 /**
1242  * nice_agent_set_selected_remote_candidate:
1243  * @agent: The #NiceAgent Object
1244  * @stream_id: The ID of the stream
1245  * @component_id: The ID of the component
1246  * @candidate: The #NiceCandidate to select
1247  *
1248  * Sets the selected remote candidate for media transmission
1249  * for a given stream's component. This is used to force the selection of
1250  * a specific remote candidate even when connectivity checks are failing
1251  * (e.g. non-ICE compatible candidates).
1252  * Calling this function will disable all further ICE processing
1253  * (connection check, state machine updates, etc). Note that keepalives will
1254  * continue to be sent.
1255  *
1256  * Returns: %TRUE on success, %FALSE on failure
1257  */
1258 gboolean
1259 nice_agent_set_selected_remote_candidate (
1260   NiceAgent *agent,
1261   guint stream_id,
1262   guint component_id,
1263   NiceCandidate *candidate);
1264
1265
1266 /**
1267  * nice_agent_set_stream_tos:
1268  * @agent: The #NiceAgent Object
1269  * @stream_id: The ID of the stream
1270  * @tos: The ToS to set
1271  *
1272  * Sets the IP_TOS and/or IPV6_TCLASS field on the stream's sockets' options
1273  *
1274  * Since: 0.0.9
1275  */
1276 void nice_agent_set_stream_tos (
1277   NiceAgent *agent,
1278   guint stream_id,
1279   gint tos);
1280
1281
1282
1283 /**
1284  * nice_agent_set_software:
1285  * @agent: The #NiceAgent Object
1286  * @software: The value of the SOFTWARE attribute to add.
1287  *
1288  * This function will set the value of the SOFTWARE attribute to be added to
1289  * STUN requests, responses and error responses sent during connectivity checks.
1290  * <para>
1291  * The SOFTWARE attribute will only be added in the #NICE_COMPATIBILITY_RFC5245
1292  * and #NICE_COMPATIBILITY_WLM2009 compatibility modes.
1293  *
1294  * </para>
1295  * <note>
1296      <para>
1297        The @software argument will be appended with the libnice version before
1298        being sent.
1299      </para>
1300      <para>
1301        The @software argument must be in UTF-8 encoding and only the first
1302        128 characters will be sent.
1303      </para>
1304    </note>
1305  *
1306  * Since: 0.0.10
1307  *
1308  */
1309 void nice_agent_set_software (
1310     NiceAgent *agent,
1311     const gchar *software);
1312
1313 /**
1314  * nice_agent_set_stream_name:
1315  * @agent: The #NiceAgent Object
1316  * @stream_id: The ID of the stream to change
1317  * @name: The new name of the stream or %NULL
1318  *
1319  * This function will assign a media type to a stream. The only values
1320  * that can be used to produce a valid SDP are: "audio", "video",
1321  * "text", "application", "image" and "message".
1322  *
1323  * This is only useful when parsing and generating an SDP of the
1324  * candidates.
1325  *
1326  * <para>See also: nice_agent_generate_local_sdp()</para>
1327  * <para>See also: nice_agent_parse_remote_sdp()</para>
1328  * <para>See also: nice_agent_get_stream_name()</para>
1329  *
1330  * Returns: %TRUE if the name has been set. %FALSE in case of error
1331  * (invalid stream or duplicate name).
1332  * Since: 0.1.4
1333  */
1334 gboolean nice_agent_set_stream_name (
1335     NiceAgent *agent,
1336     guint stream_id,
1337     const gchar *name);
1338
1339 /**
1340  * nice_agent_get_stream_name:
1341  * @agent: The #NiceAgent Object
1342  * @stream_id: The ID of the stream to change
1343  *
1344  * This function will return the name assigned to a stream.
1345
1346  * <para>See also: nice_agent_set_stream_name()</para>
1347  *
1348  * Returns: The name of the stream. The name is only valid while the stream
1349  * exists or until it changes through a call to nice_agent_set_stream_name().
1350  *
1351  *
1352  * Since: 0.1.4
1353  */
1354 const gchar *nice_agent_get_stream_name (
1355     NiceAgent *agent,
1356     guint stream_id);
1357
1358 /**
1359  * nice_agent_get_default_local_candidate:
1360  * @agent: The #NiceAgent Object
1361  * @stream_id: The ID of the stream
1362  * @component_id: The ID of the component
1363  *
1364  * This helper function will return the recommended default candidate to be
1365  * used for non-ICE compatible clients. This will usually be the candidate
1366  * with the lowest priority, since it will be the longest path but the one with
1367  * the most chances of success.
1368  * <note>
1369      <para>
1370      This function is only useful in order to manually generate the
1371      local SDP
1372      </para>
1373  * </note>
1374  *
1375  * Returns: The candidate to be used as the default candidate, or %NULL in case
1376  * of error. Must be freed with nice_candidate_free() once done.
1377  *
1378  */
1379 NiceCandidate *
1380 nice_agent_get_default_local_candidate (
1381     NiceAgent *agent,
1382     guint stream_id,
1383     guint component_id);
1384
1385 /**
1386  * nice_agent_generate_local_sdp:
1387  * @agent: The #NiceAgent Object
1388  *
1389  * Generate an SDP string containing the local candidates and credentials for
1390  * all streams and components in the agent.
1391  *
1392  <note>
1393    <para>
1394      The SDP will not contain any codec lines and the 'm' line will not list
1395      any payload types.
1396    </para>
1397    <para>
1398     It is highly recommended to set names on the streams prior to calling this
1399     function. Unnamed streams will show up as '-' in the 'm' line, but the SDP
1400     will not be parseable with nice_agent_parse_remote_sdp() if a stream is
1401     unnamed.
1402    </para>
1403    <para>
1404      The default candidate in the SDP will be selected based on the lowest
1405      priority candidate for the first component.
1406    </para>
1407  </note>
1408  *
1409  * <para>See also: nice_agent_set_stream_name() </para>
1410  * <para>See also: nice_agent_parse_remote_sdp() </para>
1411  * <para>See also: nice_agent_generate_local_stream_sdp() </para>
1412  * <para>See also: nice_agent_generate_local_candidate_sdp() </para>
1413  * <para>See also: nice_agent_get_default_local_candidate() </para>
1414  *
1415  * Returns: A string representing the local SDP. Must be freed with g_free()
1416  * once done.
1417  *
1418  * Since: 0.1.4
1419  **/
1420 gchar *
1421 nice_agent_generate_local_sdp (
1422   NiceAgent *agent);
1423
1424 /**
1425  * nice_agent_generate_local_stream_sdp:
1426  * @agent: The #NiceAgent Object
1427  * @stream_id: The ID of the stream
1428  * @include_non_ice: Whether or not to include non ICE specific lines
1429  * (m=, c= and a=rtcp: lines)
1430  *
1431  * Generate an SDP string containing the local candidates and credentials
1432  * for a stream.
1433  *
1434  <note>
1435    <para>
1436      The SDP will not contain any codec lines and the 'm' line will not list
1437      any payload types.
1438    </para>
1439    <para>
1440     It is highly recommended to set the name of the stream prior to calling this
1441     function. Unnamed streams will show up as '-' in the 'm' line.
1442    </para>
1443    <para>
1444      The default candidate in the SDP will be selected based on the lowest
1445      priority candidate.
1446    </para>
1447  </note>
1448  *
1449  * <para>See also: nice_agent_set_stream_name() </para>
1450  * <para>See also: nice_agent_parse_remote_stream_sdp() </para>
1451  * <para>See also: nice_agent_generate_local_sdp() </para>
1452  * <para>See also: nice_agent_generate_local_candidate_sdp() </para>
1453  * <para>See also: nice_agent_get_default_local_candidate() </para>
1454  *
1455  * Returns: A string representing the local SDP for the stream. Must be freed
1456  * with g_free() once done.
1457  *
1458  * Since: 0.1.4
1459  **/
1460 gchar *
1461 nice_agent_generate_local_stream_sdp (
1462     NiceAgent *agent,
1463     guint stream_id,
1464     gboolean include_non_ice);
1465
1466 /**
1467  * nice_agent_generate_local_candidate_sdp:
1468  * @agent: The #NiceAgent Object
1469  * @candidate: The candidate to generate
1470  *
1471  * Generate an SDP string representing a local candidate.
1472  *
1473  * <para>See also: nice_agent_parse_remote_candidate_sdp() </para>
1474  * <para>See also: nice_agent_generate_local_sdp() </para>
1475  * <para>See also: nice_agent_generate_local_stream_sdp() </para>
1476  *
1477  * Returns: A string representing the SDP for the candidate. Must be freed
1478  * with g_free() once done.
1479  *
1480  * Since: 0.1.4
1481  **/
1482 gchar *
1483 nice_agent_generate_local_candidate_sdp (
1484     NiceAgent *agent,
1485     NiceCandidate *candidate);
1486
1487 /**
1488  * nice_agent_parse_remote_sdp:
1489  * @agent: The #NiceAgent Object
1490  * @sdp: The remote SDP to parse
1491  *
1492  * Parse an SDP string and extracts candidates and credentials from it and sets
1493  * them on the agent.
1494  *
1495  * <para>See also: nice_agent_set_stream_name() </para>
1496  * <para>See also: nice_agent_generate_local_sdp() </para>
1497  * <para>See also: nice_agent_parse_remote_stream_sdp() </para>
1498  * <para>See also: nice_agent_parse_remote_candidate_sdp() </para>
1499  *
1500  * Returns: The number of candidates added, negative on errors
1501  *
1502  * Since: 0.1.4
1503  **/
1504 int
1505 nice_agent_parse_remote_sdp (
1506     NiceAgent *agent,
1507     const gchar *sdp);
1508
1509
1510 /**
1511  * nice_agent_parse_remote_stream_sdp:
1512  * @agent: The #NiceAgent Object
1513  * @stream_id: The ID of the stream to parse
1514  * @sdp: The remote SDP to parse
1515  * @ufrag: Pointer to store the ice ufrag if non %NULL. Must be freed with
1516  * g_free() after use
1517  * @pwd: Pointer to store the ice password if non %NULL. Must be freed with
1518  * g_free() after use
1519  *
1520  * Parse an SDP string representing a single stream and extracts candidates
1521  * and credentials from it.
1522  *
1523  * <para>See also: nice_agent_generate_local_stream_sdp() </para>
1524  * <para>See also: nice_agent_parse_remote_sdp() </para>
1525  * <para>See also: nice_agent_parse_remote_candidate_sdp() </para>
1526  *
1527  * Returns: (element-type NiceCandidate) (transfer full): A #GSList of
1528  * candidates parsed from the SDP, or %NULL in case of errors
1529  *
1530  * Since: 0.1.4
1531  **/
1532 GSList *
1533 nice_agent_parse_remote_stream_sdp (
1534     NiceAgent *agent,
1535     guint stream_id,
1536     const gchar *sdp,
1537     gchar **ufrag,
1538     gchar **pwd);
1539
1540
1541 /**
1542  * nice_agent_parse_remote_candidate_sdp:
1543  * @agent: The #NiceAgent Object
1544  * @stream_id: The ID of the stream the candidate belongs to
1545  * @sdp: The remote SDP to parse
1546  *
1547  * Parse an SDP string and extracts the candidate from it.
1548  *
1549  * <para>See also: nice_agent_generate_local_candidate_sdp() </para>
1550  * <para>See also: nice_agent_parse_remote_sdp() </para>
1551  * <para>See also: nice_agent_parse_remote_stream_sdp() </para>
1552  *
1553  * Returns: The parsed candidate or %NULL if there was an error.
1554  *
1555  * Since: 0.1.4
1556  **/
1557 NiceCandidate *
1558 nice_agent_parse_remote_candidate_sdp (
1559     NiceAgent *agent,
1560     guint stream_id,
1561     const gchar *sdp);
1562
1563 /**
1564  * nice_agent_get_io_stream:
1565  * @agent: A #NiceAgent
1566  * @stream_id: The ID of the stream to wrap
1567  * @component_id: The ID of the component to wrap
1568  *
1569  * Gets a #GIOStream wrapper around the given stream and component in
1570  * @agent. The I/O stream will be valid for as long as @stream_id is valid.
1571  * The #GInputStream and #GOutputStream implement #GPollableInputStream and
1572  * #GPollableOutputStream.
1573  *
1574  * This function may only be called on reliable #NiceAgents. It is a
1575  * programming error to try and create an I/O stream wrapper for an
1576  * unreliable stream.
1577  *
1578  * Returns: (transfer full): A #GIOStream.
1579  *
1580  * Since: 0.1.5
1581  */
1582 GIOStream *
1583 nice_agent_get_io_stream (
1584     NiceAgent *agent,
1585     guint stream_id,
1586     guint component_id);
1587
1588 /**
1589  * nice_component_state_to_string:
1590  * @state: a #NiceComponentState
1591  *
1592  * Returns a string representation of the state, generally to use in debug
1593  * messages.
1594  *
1595  * Returns: (transfer none): a string representation of @state
1596  * Since: 0.1.6
1597  */
1598 const gchar *
1599 nice_component_state_to_string (NiceComponentState state);
1600
1601 /**
1602  * nice_agent_forget_relays:
1603  * @agent: The #NiceAgent Object
1604  * @stream_id: The ID of the stream
1605  * @component_id: The ID of the component
1606  *
1607  * Forget all the relay servers previously added using
1608  * nice_agent_set_relay_info(). Currently connected streams will keep
1609  * using the relay as long as they have not been restarted and haven't
1610  * succesfully negotiated a different path.
1611  *
1612  * Returns: %FALSE if the component could not be found, %TRUE otherwise
1613  *
1614  * Since: 0.1.6
1615  */
1616 gboolean
1617 nice_agent_forget_relays (NiceAgent *agent,
1618     guint stream_id,
1619     guint component_id);
1620
1621 /**
1622  * nice_agent_get_component_state:
1623  * @agent: The #NiceAgent Object
1624  * @stream_id: The ID of the stream
1625  * @component_id: The ID of the component
1626  *
1627  * Retrieves the current state of a component.
1628  *
1629  * Returns: the #NiceComponentState of the component and
1630  * %NICE_COMPONENT_STATE_FAILED if the component was invalid.
1631  *
1632  * Since: 0.1.8
1633  */
1634 NiceComponentState
1635 nice_agent_get_component_state (NiceAgent *agent,
1636     guint stream_id,
1637     guint component_id);
1638
1639 /**
1640  * nice_agent_peer_candidate_gathering_done:
1641  * @agent: The #NiceAgent Object
1642  * @stream_id: The ID of the stream
1643  *
1644  * Notifies the agent that the remote peer has concluded candidate gathering and
1645  * thus no more remote candidates are expected to arrive for @stream_id.
1646  *
1647  * This will allow the stream components without a successful connectivity check
1648  * to stop waiting for more candidates to come and finally transit into
1649  * %NICE_COMPONENT_STATE_FAILED.
1650  *
1651  * Calling the function has an effect only when #NiceAgent:trickle-ice is %TRUE.
1652  *
1653  * Returns: %FALSE if the stream could not be found, %TRUE otherwise
1654  *
1655  * Since: 0.1.16
1656  */
1657 gboolean
1658 nice_agent_peer_candidate_gathering_done (
1659     NiceAgent *agent,
1660     guint stream_id);
1661
1662 /**
1663  * nice_agent_close_async:
1664  * @agent: The #NiceAgent object
1665  * @callback: (nullable): A callback that will be called when the closing is
1666  *  complete
1667  * @callback_data: (nullable): A pointer that will be passed to the callback
1668  *
1669  * Asynchronously closes resources the agent has allocated on remote servers.
1670  *
1671  * The agent will call the callback in the current #GMainContext in
1672  * which this function is called. The #GAsyncResult in the callback
1673  * can be ignored as this operation never fails.
1674  *
1675  * Calling this function before freeing the agent makes sure the allocated relay
1676  * ports aren't left behind on TURN server but properly removed.
1677  *
1678  * Since: 0.1.16
1679  */
1680 void
1681 nice_agent_close_async (NiceAgent *agent, GAsyncReadyCallback callback,
1682     gpointer callback_data);
1683
1684 /**
1685  * nice_agent_get_sockets:
1686  * @agent: The #NiceAgent Object
1687  * @stream_id: The ID of the stream
1688  * @component_id: The ID of the component
1689  *
1690  * Each component can have multiple sockets, this is an API to retrieve them all
1691  * to be able to set properties. Most of the sockets for a component are created when
1692  * calling nice_agent_gather_candidates(), so this API should be called right after to
1693  * able to set properties on the sockets before they are used.
1694  *
1695  * These sockets can be a mix of UDP & TCP sockets depending on the compatibility mode
1696  * and options that have been set.
1697  *
1698  * Returns: (element-type GSocket) (transfer full): An array
1699  * containing all of the sockets for this component. Free with
1700  * g_ptr_array_unref() when done.
1701  *
1702  * Since: 0.1.17
1703  */
1704 GPtrArray *
1705 nice_agent_get_sockets (NiceAgent *agent, guint stream_id, guint component_id);
1706
1707 G_END_DECLS
1708
1709 #endif /* __LIBNICE_AGENT_H__ */