agent/agent.h

   1 /*
   2  * This file is part of the Nice GLib ICE library.
   3  *
   4  * (C) 2006, 2007 Collabora Ltd.
   5  *  Contact: Dafydd Harries
   6  * (C) 2006, 2007 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  *   Kai Vehmanen, Nokia
  27  *
  28  * Alternatively, the contents of this file may be used under the terms of the
  29  * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
  30  * case the provisions of LGPL are applicable instead of those above. If you
  31  * wish to allow use of your version of this file only under the terms of the
  32  * LGPL and not to allow others to use your version of this file under the
  33  * MPL, indicate your decision by deleting the provisions above and replace
  34  * them with the notice and other provisions required by the LGPL. If you do
  35  * not delete the provisions above, a recipient may use your version of this
  36  * file under either the MPL or the LGPL.
  37  */
  38
  39 #ifndef _AGENT_H
  40 #define _AGENT_H
  41
  42 /**
  43  * SECTION:agent
  44  * @short_description:  ICE agent API implementation
  45  * @see_also: #NiceCandidate
  46  * @see_also: #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  <example>
  56    <title>Simple example on how to use libnice</title>
  57    <programlisting>
  58    NiceAddress base_addr;
  59    guint stream_id;
  60    gchar buffer[] = "hello world!";
  61    GSList *lcands = NULL;
  62
  63    // Create a nice agent
  64    NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_DRAFT19);
  65
  66    // Connect the signals
  67    g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
  68                      G_CALLBACK (cb_candidate_gathering_done), NULL);
  69    g_signal_connect (G_OBJECT (lagent), "component-state-changed",
  70                      G_CALLBACK (cb_component_state_changed), NULL);
  71    g_signal_connect (G_OBJECT (lagent), "new-selected-pair",
  72                      G_CALLBACK (cb_new_selected_pair), NULL);
  73
  74    // Create a new stream with one component and start gathering candidates
  75    stream_id = nice_agent_add_stream (agent, 1);
  76    nice_agent_gather_candidates (agent, stream_id);
  77
  78    // Attach to the component to receive the data
  79    nice_agent_attach_recv (agent, stream_id, 1, NULL,
  80                           cb_nice_recv, NULL);
  81
  82    // ... Wait until the signal candidate-gathering-done is fired ...
  83    lcands = nice_agent_get_local_candidates(agent, stream_id, 1);
  84
  85    // ... Send local candidates to the peer and set the peer's remote candidates
  86    nice_agent_set_remote_candidates (agent, stream_id, 1, rcands);
  87
  88    // ... Wait until the signal new-selected-pair is fired ...
  89    // Send our message!
  90    nice_agent_send (lagent, ls_id, 1, sizeof(buffer), buffer);
  91
  92    // Anything received will be received through the cb_nice_recv callback
  93
  94    // Destroy the object
  95    g_object_unref(agent);
  96
  97    </programlisting>
  98  </example>
  99  */
 100
 101
 102 #include <glib-object.h>
 103
 104 /**
 105  * NiceAgent:
 106  *
 107  * The #NiceAgent is the main GObject of the libnice library and represents
 108  * the ICE agent.
 109  */
 110 typedef struct _NiceAgent NiceAgent;
 111
 112 #include "address.h"
 113 #include "candidate.h"
 114 #include "debug.h"
 115
 116
 117 G_BEGIN_DECLS
 118
 119 #define NICE_TYPE_AGENT nice_agent_get_type()
 120
 121 #define NICE_AGENT(obj) \
 122   (G_TYPE_CHECK_INSTANCE_CAST ((obj), \
 123   NICE_TYPE_AGENT, NiceAgent))
 124
 125 #define NICE_AGENT_CLASS(klass) \
 126   (G_TYPE_CHECK_CLASS_CAST ((klass), \
 127   NICE_TYPE_AGENT, NiceAgentClass))
 128
 129 #define NICE_IS_AGENT(obj) \
 130   (G_TYPE_CHECK_INSTANCE_TYPE ((obj), \
 131   NICE_TYPE_AGENT))
 132
 133 #define NICE_IS_AGENT_CLASS(klass) \
 134   (G_TYPE_CHECK_CLASS_TYPE ((klass), \
 135   NICE_TYPE_AGENT))
 136
 137 #define NICE_AGENT_GET_CLASS(obj) \
 138   (G_TYPE_INSTANCE_GET_CLASS ((obj), \
 139   NICE_TYPE_AGENT, NiceAgentClass))
 140
 141 typedef struct _NiceAgentClass NiceAgentClass;
 142
 143 struct _NiceAgentClass
 144 {
 145   GObjectClass parent_class;
 146 };
 147
 148
 149 GType nice_agent_get_type (void);
 150
 151
 152 /**
 153  * NICE_AGENT_MAX_REMOTE_CANDIDATES:
 154  *
 155  * A hard limit for the number of remote candidates. This
 156  * limit is enforced to protect against malevolent remote
 157  * clients.
 158  */
 159 #define NICE_AGENT_MAX_REMOTE_CANDIDATES    25
 160
 161 /**
 162  * NiceComponentState:
 163  * @NICE_COMPONENT_STATE_DISCONNECTED: No activity scheduled
 164  * @NICE_COMPONENT_STATE_GATHERING: Gathering local candidates
 165  * @NICE_COMPONENT_STATE_CONNECTING: Establishing connectivity
 166  * @NICE_COMPONENT_STATE_CONNECTED: At least one working candidate pair
 167  * @NICE_COMPONENT_STATE_READY: ICE concluded, candidate pair selection
 168  * is now final
 169  * @NICE_COMPONENT_STATE_FAILED: Connectivity checks have been completed,
 170  * but connectivity was not established
 171  * @NICE_COMPONENT_STATE_LAST: Dummy state
 172  *
 173  * An enum representing the state of a component.
 174  * <para> See also: #NiceAgent::component-state-changed </para>
 175  */
 176 typedef enum
 177 {
 178   NICE_COMPONENT_STATE_DISCONNECTED,
 179   NICE_COMPONENT_STATE_GATHERING,
 180   NICE_COMPONENT_STATE_CONNECTING,
 181   NICE_COMPONENT_STATE_CONNECTED,
 182   NICE_COMPONENT_STATE_READY,
 183   NICE_COMPONENT_STATE_FAILED,
 184   NICE_COMPONENT_STATE_LAST
 185 } NiceComponentState;
 186
 187
 188 /**
 189  * NiceComponentType:
 190  * @NICE_COMPONENT_TYPE_RTP: RTP Component type
 191  * @NICE_COMPONENT_TYPE_RTCP: RTCP Component type
 192  *
 193  * Convenience enum representing the type of a component for use as the
 194  * component_id for RTP/RTCP usages.
 195  <example>
 196    <title>Example of use.</title>
 197    <programlisting>
 198    nice_agent_send (agent, stream_id, NICE_COMPONENT_TYPE_RTP, len, buf);
 199    </programlisting>
 200   </example>
 201  */
 202 typedef enum
 203 {
 204   NICE_COMPONENT_TYPE_RTP = 1,
 205   NICE_COMPONENT_TYPE_RTCP = 2
 206 } NiceComponentType;
 207
 208
 209 /**
 210  * NiceCompatibility:
 211  * @NICE_COMPATIBILITY_DRAFT19: Use compatibility for ICE Draft 19 specs
 212  * @NICE_COMPATIBILITY_GOOGLE: Use compatibility for Google Talk specs
 213  * @NICE_COMPATIBILITY_MSN: Use compatibility for MSN Messenger specs
 214  * @NICE_COMPATIBILITY_WLM2009: Use compatibility with Windows Live Messenger
 215  * 2009
 216  * @NICE_COMPATIBILITY_LAST: Dummy last compatibility mode
 217  *
 218  * An enum to specify which compatible specifications the #NiceAgent should use.
 219  * Use with nice_agent_new()
 220  */
 221 typedef enum
 222 {
 223   NICE_COMPATIBILITY_DRAFT19 = 0,
 224   NICE_COMPATIBILITY_GOOGLE,
 225   NICE_COMPATIBILITY_MSN,
 226   NICE_COMPATIBILITY_WLM2009,
 227   NICE_COMPATIBILITY_LAST = NICE_COMPATIBILITY_WLM2009
 228 } NiceCompatibility;
 229
 230 /**
 231  * NiceProxyType:
 232  * @NICE_PROXY_TYPE_NONE: Do not use a proxy
 233  * @NICE_PROXY_TYPE_SOCKS5: Use a SOCKS5 proxy
 234  * @NICE_PROXY_TYPE_HTTP: Use an HTTP proxy
 235  * @NICE_PROXY_TYPE_LAST: Dummy last proxy type
 236  *
 237  * An enum to specify which proxy type to use for relaying.
 238  * Note that the proxies will only be used with TCP TURN relaying.
 239  * <para> See also: #NiceAgent:proxy-type </para>
 240  */
 241 typedef enum
 242 {
 243   NICE_PROXY_TYPE_NONE = 0,
 244   NICE_PROXY_TYPE_SOCKS5,
 245   NICE_PROXY_TYPE_HTTP,
 246   NICE_PROXY_TYPE_LAST = NICE_PROXY_TYPE_HTTP,
 247 } NiceProxyType;
 248
 249
 250 /**
 251  * NiceAgentRecvFunc:
 252  * @agent: The #NiceAgent Object
 253  * @stream_id: The id of the stream
 254  * @component_id: The id of the component of the stream
 255  *        which received the data
 256  * @len: The length of the data
 257  * @buf: The buffer containing the data received
 258  * @user_data: The user data set in nice_agent_attach_recv()
 259  *
 260  * Callback function when data is received on a component
 261  *
 262  */
 263 typedef void (*NiceAgentRecvFunc) (
 264   NiceAgent *agent, guint stream_id, guint component_id, guint len,
 265   gchar *buf, gpointer user_data);
 266
 267
 268 /**
 269  * nice_agent_new:
 270  * @ctx: The Glib Mainloop Context to use for timers
 271  * @compat: The compatibility mode of the agent
 272  *
 273  * Create a new #NiceAgent.
 274  * The returned object must be freed with g_object_unref()
 275  *
 276  * Returns: The new agent GObject
 277  */
 278 NiceAgent *
 279 nice_agent_new (GMainContext *ctx, NiceCompatibility compat);
 280
 281 /**
 282  * nice_agent_add_local_address:
 283  * @agent: The #NiceAgent Object
 284  * @addr: The address to listen to
 285  * If the port is 0, then a random port will be chosen by the system
 286  *
 287  * Add a local address from which to derive local host candidates
 288  *
 289  * Returns: %TRUE on success, %FALSE on fatal (memory allocation) errors
 290  */
 291 gboolean
 292 nice_agent_add_local_address (NiceAgent *agent, NiceAddress *addr);
 293
 294
 295 /**
 296  * nice_agent_add_stream:
 297  * @agent: The #NiceAgent Object
 298  * @n_components: The number of components to add to the stream
 299  *
 300  * Adds a data stream to @agent containing @n_components components.
 301  *
 302  * Returns: The ID of the new stream, 0 on failure
 303  **/
 304 guint
 305 nice_agent_add_stream (
 306   NiceAgent *agent,
 307   guint n_components);
 308
 309 /**
 310  * nice_agent_remove_stream:
 311  * @agent: The #NiceAgent Object
 312  * @stream_id: The ID of the stream to remove
 313  *
 314  * Remove and free a previously created data stream from @agent
 315  *
 316  **/
 317 void
 318 nice_agent_remove_stream (
 319   NiceAgent *agent,
 320   guint stream_id);
 321
 322 /**
 323  * nice_agent_set_relay_info:
 324  * @agent: The #NiceAgent Object
 325  * @stream_id: The ID of the stream
 326  * @component_id: The ID of the component
 327  * @server_ip: The IP address of the TURN server
 328  * @server_port: The port of the TURN server
 329  * @username: The TURN username to use for the allocate
 330  * @password: The TURN password to use for the allocate
 331  * @type: The type of relay to use
 332  *
 333  * Sets the settings for using a relay server during the candidate discovery.
 334  *
 335  * Returns: %TRUE if the TURN settings were accepted.
 336  * %FALSE if the address was invalid.
 337  */
 338 gboolean nice_agent_set_relay_info(
 339     NiceAgent *agent,
 340     guint stream_id,
 341     guint component_id,
 342     const gchar *server_ip,
 343     guint server_port,
 344     const gchar *username,
 345     const gchar *password,
 346     NiceRelayType type);
 347
 348 /**
 349  * nice_agent_gather_candidates:
 350  * @agent: The #NiceAgent Object
 351  * @stream_id: The id of the stream to start
 352  *
 353  * Start the candidate gathering process.
 354  * Once done, #NiceAgent::candidate-gathering-done is called for the stream
 355  *
 356  <note>
 357    <para>
 358     Local addresses can be previously set with nice_agent_add_local_address()
 359   </para>
 360   <para>
 361     If no local address was previously added, then the nice agent will
 362     automatically detect the local address using nice_interfaces_get_local_ips()
 363    </para>
 364  </note>
 365  */
 366 void
 367 nice_agent_gather_candidates (
 368   NiceAgent *agent,
 369   guint stream_id);
 370
 371 /**
 372  * nice_agent_set_remote_credentials:
 373  * @agent: The #NiceAgent Object
 374  * @stream_id: The ID of the stream
 375  * @ufrag: NULL-terminated string containing an ICE username fragment
 376  *    (length must be between 22 and 256 chars)
 377  * @pwd: NULL-terminated string containing an ICE password
 378  *    (length must be between 4 and 256 chars)
 379  *
 380  * Sets the remote credentials for stream @stream_id.
 381  *
 382  <note>
 383    <para>
 384      Stream credentials do not override per-candidate credentials if set
 385    </para>
 386  </note>
 387  *
 388  * Returns: %TRUE on success, %FALSE on error.
 389  */
 390 gboolean
 391 nice_agent_set_remote_credentials (
 392   NiceAgent *agent,
 393   guint stream_id,
 394   const gchar *ufrag, const gchar *pwd);
 395
 396
 397
 398 /**
 399  * nice_agent_get_local_credentials:
 400  * @agent: The #NiceAgent Object
 401  * @stream_id: The ID of the stream
 402  * @ufrag: a pointer to a NULL-terminated string containing
 403  * an ICE username fragment [OUT].
 404  * This string must be freed with g_free()
 405  * @pwd: a pointer to a NULL-terminated string containing an ICE
 406  * password [OUT]
 407  * This string must be freed with g_free()
 408  *
 409  * Gets the local credentials for stream @stream_id.
 410  *
 411  * Returns: %TRUE on success, %FALSE on error.
 412  */
 413 gboolean
 414 nice_agent_get_local_credentials (
 415   NiceAgent *agent,
 416   guint stream_id,
 417   gchar **ufrag, gchar **pwd);
 418
 419 /**
 420  * nice_agent_set_remote_candidates:
 421  * @agent: The #NiceAgent Object
 422  * @stream_id: The ID of the stream the candidates are for
 423  * @component_id: The ID of the component the candidates are for
 424  * @candidates: a #GList of #NiceCandidate items describing each candidate to add
 425  *
 426  * Sets, adds or updates the remote candidates for a component of a stream.
 427  *
 428  <note>
 429    <para>
 430     NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit
 431     for remote candidates.
 432    </para>
 433    <para>
 434    You must first call nice_agent_gather_candidates() and wait for the
 435    #NiceAgent::candidate-gathering-done signale before
 436    calling nice_agent_set_remote_candidates()
 437    </para>
 438  </note>
 439  *
 440  * Returns: The number of candidates added, negative on errors (memory allocation
 441  * or if the local candidates are not done gathering yet)
 442  **/
 443 int
 444 nice_agent_set_remote_candidates (
 445   NiceAgent *agent,
 446   guint stream_id,
 447   guint component_id,
 448   const GSList *candidates);
 449
 450
 451 /**
 452  * nice_agent_send:
 453  * @agent: The #NiceAgent Object
 454  * @stream_id: The ID of the stream to send to
 455  * @component_id: The ID of the component to send to
 456  * @len: The length of the buffer to send
 457  * @buf: The buffer of data to send
 458  *
 459  * Sends a data payload over a stream's component.
 460  *
 461  <note>
 462    <para>
 463      Component state MUST be NICE_COMPONENT_STATE_READY, or as a special case,
 464      in any state if component was in READY state before and was then restarted
 465    </para>
 466  </note>
 467  *
 468  * Returns: The number of bytes sent, or negative error code
 469  */
 470 gint
 471 nice_agent_send (
 472   NiceAgent *agent,
 473   guint stream_id,
 474   guint component_id,
 475   guint len,
 476   const gchar *buf);
 477
 478 /**
 479  * nice_agent_get_local_candidates:
 480  * @agent: The #NiceAgent Object
 481  * @stream_id: The ID of the stream
 482  * @component_id: The ID of the component
 483  *
 484  * Retreive from the agent the list of all local candidates
 485  * for a stream's component
 486  *
 487  <note>
 488    <para>
 489      The caller owns the returned GSList as well as the candidates contained
 490      within it.
 491      To get full results, the client should wait for the
 492      #NiceAgent::candidates-gathering-done signal.
 493    </para>
 494  </note>
 495  *
 496  * Returns: a #GSList of #NiceCandidate objects representing
 497  * the local candidates of @agent
 498  **/
 499 GSList *
 500 nice_agent_get_local_candidates (
 501   NiceAgent *agent,
 502   guint stream_id,
 503   guint component_id);
 504
 505
 506 /**
 507  * nice_agent_get_remote_candidates:
 508  * @agent: The #NiceAgent Object
 509  * @stream_id: The ID of the stream
 510  * @component_id: The ID of the component
 511  *
 512  * Get a list of the remote candidates set on a stream's component
 513  *
 514  <note>
 515    <para>
 516      The caller owns the returned GSList but not the candidates
 517      contained within it.
 518    </para>
 519    <para>
 520      The list of remote candidates can change during processing.
 521      The client should register for the #NiceAgent::new-remote-candidate signal
 522      to get notified of new remote candidates.
 523    </para>
 524  </note>
 525  *
 526  * Returns: a #GSList of #NiceCandidates objects representing
 527  * the remote candidates set on the @agent
 528  **/
 529 GSList *
 530 nice_agent_get_remote_candidates (
 531   NiceAgent *agent,
 532   guint stream_id,
 533   guint component_id);
 534
 535 /**
 536  * nice_agent_restart:
 537  * @agent: The #NiceAgent Object
 538  *
 539  * Restarts the session as defined in ICE draft 19. This function
 540  * needs to be called both when initiating (ICE spec section 9.1.1.1.
 541  * "ICE Restarts"), as well as when reacting (spec section 9.2.1.1.
 542  * "Detecting ICE Restart") to a restart.
 543  *
 544  * Returns: %TRUE on success %FALSE on error
 545  **/
 546 gboolean
 547 nice_agent_restart (
 548   NiceAgent *agent);
 549
 550
 551 /**
 552  * nice_agent_attach_recv:
 553  * @agent: The #NiceAgent Object
 554  * @stream_id: The ID of stream
 555  * @component_id: The ID of the component
 556  * @ctx: The Glib Mainloop Context to use for listening on the component
 557  * @func: The callback function to be called when data is received on
 558  * the stream's component
 559  * @data: user data associated with the callback
 560  *
 561  * Attaches the stream's component's sockets to the Glib Mainloop Context in
 562  * order to be notified whenever data becomes available for a component.
 563  *
 564  * Returns: %TRUE on success, %FALSE if the stream or component IDs are invalid.
 565  */
 566 gboolean
 567 nice_agent_attach_recv (
 568   NiceAgent *agent,
 569   guint stream_id,
 570   guint component_id,
 571   GMainContext *ctx,
 572   NiceAgentRecvFunc func,
 573   gpointer data);
 574
 575
 576 /**
 577  * nice_agent_set_selected_pair:
 578  * @agent: The #NiceAgent Object
 579  * @stream_id: The ID of the stream
 580  * @component_id: The ID of the component
 581  * @lfoundation: The local foundation of the candidate to use
 582  * @rfoundation: The remote foundation of the candidate to use
 583  *
 584  * Sets the selected candidate pair for media transmission
 585  * for a given stream's component. Calling this function will
 586  * disable all further ICE processing (connection check,
 587  * state machine updates, etc). Note that keepalives will
 588  * continue to be sent.
 589  *
 590  * Returns: %TRUE on success, %FALSE if the candidate pair cannot be found
 591  */
 592 gboolean
 593 nice_agent_set_selected_pair (
 594   NiceAgent *agent,
 595   guint stream_id,
 596   guint component_id,
 597   const gchar *lfoundation,
 598   const gchar *rfoundation);
 599
 600 /**
 601  * nice_agent_set_selected_remote_candidate:
 602  * @agent: The #NiceAgent Object
 603  * @stream_id: The ID of the stream
 604  * @component_id: The ID of the component
 605  * @candidate: The #NiceCandidate to select
 606  *
 607  * Sets the selected remote candidate for media transmission
 608  * for a given stream's component. This is used to force the selection of
 609  * a specific remote candidate even when connectivity checks are failing
 610  * (e.g. non-ICE compatible candidates).
 611  * Calling this function will disable all further ICE processing
 612  * (connection check, state machine updates, etc). Note that keepalives will
 613  * continue to be sent.
 614  *
 615  * Returns: %TRUE on success, %FALSE on failure
 616  */
 617 gboolean
 618 nice_agent_set_selected_remote_candidate (
 619   NiceAgent *agent,
 620   guint stream_id,
 621   guint component_id,
 622   NiceCandidate *candidate);
 623
 624 G_END_DECLS
 625
 626 #endif /* _AGENT_H */
 627