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 _AGENT_H
  41 #define _AGENT_H
  42
  43 /**
  44  * SECTION:agent
  45  * @short_description:  ICE agent API implementation
  46  * @see_also: #NiceCandidate
  47  * @see_also: #NiceAddress
  48  * @include: agent.h
  49  * @stability: Stable
  50  *
  51  * The #NiceAgent is your main object when using libnice.
  52  * It is the agent that will take care of everything relating to ICE.
  53  * It will take care of discovering your local candidates and do
  54  *  connectivity checks to create a stream of data between you and your peer.
  55  *
  56  <example>
  57    <title>Simple example on how to use libnice</title>
  58    <programlisting>
  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_RFC5245);
  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 (agent), "component-state-changed",
  70                      G_CALLBACK (cb_component_state_changed), NULL);
  71    g_signal_connect (G_OBJECT (agent), "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 (agent, stream_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_RFC5245: Use compatibility with the RFC5245 ICE 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_DRAFT19: Use compatibility for ICE Draft 19 specs
 217  * @NICE_COMPATIBILITY_LAST: Dummy last compatibility mode
 218  *
 219  * An enum to specify which compatible specifications the #NiceAgent should use.
 220  * Use with nice_agent_new()
 221  *
 222  * <warning>@NICE_COMPATIBILITY_DRAFT19 is deprecated and should not be used
 223  * in newly-written code. It is kept for compatibility reasons and
 224  * represents the same compatibility as @NICE_COMPATIBILITY_RFC5245 </warning>
 225  */
 226 typedef enum
 227 {
 228   NICE_COMPATIBILITY_RFC5245 = 0,
 229   NICE_COMPATIBILITY_GOOGLE,
 230   NICE_COMPATIBILITY_MSN,
 231   NICE_COMPATIBILITY_WLM2009,
 232   NICE_COMPATIBILITY_DRAFT19 = NICE_COMPATIBILITY_RFC5245,
 233   NICE_COMPATIBILITY_LAST = NICE_COMPATIBILITY_WLM2009,
 234 } NiceCompatibility;
 235
 236 /**
 237  * NiceProxyType:
 238  * @NICE_PROXY_TYPE_NONE: Do not use a proxy
 239  * @NICE_PROXY_TYPE_SOCKS5: Use a SOCKS5 proxy
 240  * @NICE_PROXY_TYPE_HTTP: Use an HTTP proxy
 241  * @NICE_PROXY_TYPE_LAST: Dummy last proxy type
 242  *
 243  * An enum to specify which proxy type to use for relaying.
 244  * Note that the proxies will only be used with TCP TURN relaying.
 245  * <para> See also: #NiceAgent:proxy-type </para>
 246  *
 247  * Since: 0.0.4
 248  */
 249 typedef enum
 250 {
 251   NICE_PROXY_TYPE_NONE = 0,
 252   NICE_PROXY_TYPE_SOCKS5,
 253   NICE_PROXY_TYPE_HTTP,
 254   NICE_PROXY_TYPE_LAST = NICE_PROXY_TYPE_HTTP,
 255 } NiceProxyType;
 256
 257
 258 /**
 259  * NiceAgentRecvFunc:
 260  * @agent: The #NiceAgent Object
 261  * @stream_id: The id of the stream
 262  * @component_id: The id of the component of the stream
 263  *        which received the data
 264  * @len: The length of the data
 265  * @buf: The buffer containing the data received
 266  * @user_data: The user data set in nice_agent_attach_recv()
 267  *
 268  * Callback function when data is received on a component
 269  *
 270  */
 271 typedef void (*NiceAgentRecvFunc) (
 272   NiceAgent *agent, guint stream_id, guint component_id, guint len,
 273   gchar *buf, gpointer user_data);
 274
 275
 276 /**
 277  * nice_agent_new:
 278  * @ctx: The Glib Mainloop Context to use for timers
 279  * @compat: The compatibility mode of the agent
 280  *
 281  * Create a new #NiceAgent.
 282  * The returned object must be freed with g_object_unref()
 283  *
 284  * Returns: The new agent GObject
 285  */
 286 NiceAgent *
 287 nice_agent_new (GMainContext *ctx, NiceCompatibility compat);
 288
 289
 290 /**
 291  * nice_agent_new_reliable:
 292  * @ctx: The Glib Mainloop Context to use for timers
 293  * @compat: The compatibility mode of the agent
 294  *
 295  * Create a new #NiceAgent in reliable mode, which uses #PseudoTcpSocket to
 296  * assure reliability of the messages.
 297  * The returned object must be freed with g_object_unref()
 298  * <para> See also: #NiceAgent::reliable-transport-writable </para>
 299  *
 300  * Since: 0.0.11
 301  *
 302  * Returns: The new agent GObject
 303  */
 304 NiceAgent *
 305 nice_agent_new_reliable (GMainContext *ctx, NiceCompatibility compat);
 306
 307 /**
 308  * nice_agent_add_local_address:
 309  * @agent: The #NiceAgent Object
 310  * @addr: The address to listen to
 311  * If the port is 0, then a random port will be chosen by the system
 312  *
 313  * Add a local address from which to derive local host candidates for
 314  * candidate gathering.
 315  * <para>
 316  * Since 0.0.5, if this method is not called, libnice will automatically
 317  * discover the local addresses available
 318  * </para>
 319  *
 320  * See also: nice_agent_gather_candidates()
 321  * Returns: %TRUE on success, %FALSE on fatal (memory allocation) errors
 322  */
 323 gboolean
 324 nice_agent_add_local_address (NiceAgent *agent, NiceAddress *addr);
 325
 326
 327 /**
 328  * nice_agent_add_stream:
 329  * @agent: The #NiceAgent Object
 330  * @n_components: The number of components to add to the stream
 331  *
 332  * Adds a data stream to @agent containing @n_components components.
 333  *
 334  * Returns: The ID of the new stream, 0 on failure
 335  **/
 336 guint
 337 nice_agent_add_stream (
 338   NiceAgent *agent,
 339   guint n_components);
 340
 341 /**
 342  * nice_agent_remove_stream:
 343  * @agent: The #NiceAgent Object
 344  * @stream_id: The ID of the stream to remove
 345  *
 346  * Remove and free a previously created data stream from @agent
 347  *
 348  **/
 349 void
 350 nice_agent_remove_stream (
 351   NiceAgent *agent,
 352   guint stream_id);
 353
 354 /**
 355  * nice_agent_set_relay_info:
 356  * @agent: The #NiceAgent Object
 357  * @stream_id: The ID of the stream
 358  * @component_id: The ID of the component
 359  * @server_ip: The IP address of the TURN server
 360  * @server_port: The port of the TURN server
 361  * @username: The TURN username to use for the allocate
 362  * @password: The TURN password to use for the allocate
 363  * @type: The type of relay to use
 364  *
 365  * Sets the settings for using a relay server during the candidate discovery.
 366  *
 367  * Returns: %TRUE if the TURN settings were accepted.
 368  * %FALSE if the address was invalid.
 369  */
 370 gboolean nice_agent_set_relay_info(
 371     NiceAgent *agent,
 372     guint stream_id,
 373     guint component_id,
 374     const gchar *server_ip,
 375     guint server_port,
 376     const gchar *username,
 377     const gchar *password,
 378     NiceRelayType type);
 379
 380 /**
 381  * nice_agent_gather_candidates:
 382  * @agent: The #NiceAgent Object
 383  * @stream_id: The id of the stream to start
 384  *
 385  * Start the candidate gathering process.
 386  * Once done, #NiceAgent::candidate-gathering-done is called for the stream
 387  *
 388  * See also: nice_agent_add_local_address()
 389  <note>
 390    <para>
 391     Local addresses can be previously set with nice_agent_add_local_address()
 392   </para>
 393   <para>
 394     Since 0.0.5, If no local address was previously added, then the nice agent
 395     will automatically detect the local address using
 396     nice_interfaces_get_local_ips()
 397    </para>
 398  </note>
 399  */
 400 void
 401 nice_agent_gather_candidates (
 402   NiceAgent *agent,
 403   guint stream_id);
 404
 405 /**
 406  * nice_agent_set_remote_credentials:
 407  * @agent: The #NiceAgent Object
 408  * @stream_id: The ID of the stream
 409  * @ufrag: NULL-terminated string containing an ICE username fragment
 410  *    (length must be between 22 and 256 chars)
 411  * @pwd: NULL-terminated string containing an ICE password
 412  *    (length must be between 4 and 256 chars)
 413  *
 414  * Sets the remote credentials for stream @stream_id.
 415  *
 416  <note>
 417    <para>
 418      Stream credentials do not override per-candidate credentials if set
 419    </para>
 420  </note>
 421  *
 422  * Returns: %TRUE on success, %FALSE on error.
 423  */
 424 gboolean
 425 nice_agent_set_remote_credentials (
 426   NiceAgent *agent,
 427   guint stream_id,
 428   const gchar *ufrag, const gchar *pwd);
 429
 430
 431
 432 /**
 433  * nice_agent_get_local_credentials:
 434  * @agent: The #NiceAgent Object
 435  * @stream_id: The ID of the stream
 436  * @ufrag: a pointer to a NULL-terminated string containing
 437  * an ICE username fragment [OUT].
 438  * This string must be freed with g_free()
 439  * @pwd: a pointer to a NULL-terminated string containing an ICE
 440  * password [OUT]
 441  * This string must be freed with g_free()
 442  *
 443  * Gets the local credentials for stream @stream_id.
 444  *
 445  * Returns: %TRUE on success, %FALSE on error.
 446  */
 447 gboolean
 448 nice_agent_get_local_credentials (
 449   NiceAgent *agent,
 450   guint stream_id,
 451   gchar **ufrag, gchar **pwd);
 452
 453 /**
 454  * nice_agent_set_remote_candidates:
 455  * @agent: The #NiceAgent Object
 456  * @stream_id: The ID of the stream the candidates are for
 457  * @component_id: The ID of the component the candidates are for
 458  * @candidates: a #GList of #NiceCandidate items describing each candidate to add
 459  *
 460  * Sets, adds or updates the remote candidates for a component of a stream.
 461  *
 462  <note>
 463    <para>
 464     NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit
 465     for remote candidates.
 466    </para>
 467    <para>
 468    You must first call nice_agent_gather_candidates() and wait for the
 469    #NiceAgent::candidate-gathering-done signale before
 470    calling nice_agent_set_remote_candidates()
 471    </para>
 472  </note>
 473  *
 474  * Returns: The number of candidates added, negative on errors (memory allocation
 475  * or if the local candidates are not done gathering yet)
 476  **/
 477 int
 478 nice_agent_set_remote_candidates (
 479   NiceAgent *agent,
 480   guint stream_id,
 481   guint component_id,
 482   const GSList *candidates);
 483
 484
 485 /**
 486  * nice_agent_send:
 487  * @agent: The #NiceAgent Object
 488  * @stream_id: The ID of the stream to send to
 489  * @component_id: The ID of the component to send to
 490  * @len: The length of the buffer to send
 491  * @buf: The buffer of data to send
 492  *
 493  * Sends a data payload over a stream's component.
 494  *
 495  <note>
 496    <para>
 497      Component state MUST be NICE_COMPONENT_STATE_READY, or as a special case,
 498      in any state if component was in READY state before and was then restarted
 499    </para>
 500  </note>
 501  *
 502  * Returns: The number of bytes sent, or negative error code
 503  */
 504 gint
 505 nice_agent_send (
 506   NiceAgent *agent,
 507   guint stream_id,
 508   guint component_id,
 509   guint len,
 510   const gchar *buf);
 511
 512 /**
 513  * nice_agent_get_local_candidates:
 514  * @agent: The #NiceAgent Object
 515  * @stream_id: The ID of the stream
 516  * @component_id: The ID of the component
 517  *
 518  * Retreive from the agent the list of all local candidates
 519  * for a stream's component
 520  *
 521  <note>
 522    <para>
 523      The caller owns the returned GSList as well as the candidates contained
 524      within it.
 525      To get full results, the client should wait for the
 526      #NiceAgent::candidate-gathering-done signal.
 527    </para>
 528  </note>
 529  *
 530  * Returns: a #GSList of #NiceCandidate objects representing
 531  * the local candidates of @agent
 532  **/
 533 GSList *
 534 nice_agent_get_local_candidates (
 535   NiceAgent *agent,
 536   guint stream_id,
 537   guint component_id);
 538
 539
 540 /**
 541  * nice_agent_get_remote_candidates:
 542  * @agent: The #NiceAgent Object
 543  * @stream_id: The ID of the stream
 544  * @component_id: The ID of the component
 545  *
 546  * Get a list of the remote candidates set on a stream's component
 547  *
 548  <note>
 549    <para>
 550      The caller owns the returned GSList but not the candidates
 551      contained within it.
 552    </para>
 553    <para>
 554      The list of remote candidates can change during processing.
 555      The client should register for the #NiceAgent::new-remote-candidate signal
 556      to get notified of new remote candidates.
 557    </para>
 558  </note>
 559  *
 560  * Returns: a #GSList of #NiceCandidates objects representing
 561  * the remote candidates set on the @agent
 562  **/
 563 GSList *
 564 nice_agent_get_remote_candidates (
 565   NiceAgent *agent,
 566   guint stream_id,
 567   guint component_id);
 568
 569 /**
 570  * nice_agent_restart:
 571  * @agent: The #NiceAgent Object
 572  *
 573  * Restarts the session as defined in ICE draft 19. This function
 574  * needs to be called both when initiating (ICE spec section 9.1.1.1.
 575  * "ICE Restarts"), as well as when reacting (spec section 9.2.1.1.
 576  * "Detecting ICE Restart") to a restart.
 577  *
 578  * Returns: %TRUE on success %FALSE on error
 579  **/
 580 gboolean
 581 nice_agent_restart (
 582   NiceAgent *agent);
 583
 584
 585 /**
 586  * nice_agent_attach_recv:
 587  * @agent: The #NiceAgent Object
 588  * @stream_id: The ID of stream
 589  * @component_id: The ID of the component
 590  * @ctx: The Glib Mainloop Context to use for listening on the component
 591  * @func: The callback function to be called when data is received on
 592  * the stream's component
 593  * @data: user data associated with the callback
 594  *
 595  * Attaches the stream's component's sockets to the Glib Mainloop Context in
 596  * order to be notified whenever data becomes available for a component.
 597  *
 598  * Returns: %TRUE on success, %FALSE if the stream or component IDs are invalid.
 599  */
 600 gboolean
 601 nice_agent_attach_recv (
 602   NiceAgent *agent,
 603   guint stream_id,
 604   guint component_id,
 605   GMainContext *ctx,
 606   NiceAgentRecvFunc func,
 607   gpointer data);
 608
 609
 610 /**
 611  * nice_agent_set_selected_pair:
 612  * @agent: The #NiceAgent Object
 613  * @stream_id: The ID of the stream
 614  * @component_id: The ID of the component
 615  * @lfoundation: The local foundation of the candidate to use
 616  * @rfoundation: The remote foundation of the candidate to use
 617  *
 618  * Sets the selected candidate pair for media transmission
 619  * for a given stream's component. Calling this function will
 620  * disable all further ICE processing (connection check,
 621  * state machine updates, etc). Note that keepalives will
 622  * continue to be sent.
 623  *
 624  * Returns: %TRUE on success, %FALSE if the candidate pair cannot be found
 625  */
 626 gboolean
 627 nice_agent_set_selected_pair (
 628   NiceAgent *agent,
 629   guint stream_id,
 630   guint component_id,
 631   const gchar *lfoundation,
 632   const gchar *rfoundation);
 633
 634 /**
 635  * nice_agent_set_selected_remote_candidate:
 636  * @agent: The #NiceAgent Object
 637  * @stream_id: The ID of the stream
 638  * @component_id: The ID of the component
 639  * @candidate: The #NiceCandidate to select
 640  *
 641  * Sets the selected remote candidate for media transmission
 642  * for a given stream's component. This is used to force the selection of
 643  * a specific remote candidate even when connectivity checks are failing
 644  * (e.g. non-ICE compatible candidates).
 645  * Calling this function will disable all further ICE processing
 646  * (connection check, state machine updates, etc). Note that keepalives will
 647  * continue to be sent.
 648  *
 649  * Returns: %TRUE on success, %FALSE on failure
 650  */
 651 gboolean
 652 nice_agent_set_selected_remote_candidate (
 653   NiceAgent *agent,
 654   guint stream_id,
 655   guint component_id,
 656   NiceCandidate *candidate);
 657
 658
 659 /**
 660  * nice_agent_set_stream_tos:
 661  * @agent: The #NiceAgent Object
 662  * @stream_id: The ID of the stream
 663  * @tos: The ToS to set
 664  *
 665  * Sets the IP_TOS and/or IPV6_TCLASS field on the stream's sockets' options
 666  *
 667  * Since: 0.0.9
 668  */
 669 void nice_agent_set_stream_tos (
 670   NiceAgent *agent,
 671   guint stream_id,
 672   gint tos);
 673
 674
 675
 676 /**
 677  * nice_agent_set_software:
 678  * @agent: The #NiceAgent Object
 679  * @software: The value of the SOFTWARE attribute to add.
 680  *
 681  * This function will set the value of the SOFTWARE attribute to be added to
 682  * STUN requests, responses and error responses sent during connectivity checks.
 683  * <para>
 684  * The SOFTWARE attribute will only be added in the #NICE_COMPATIBILITY_RFC5245
 685  * and #NICE_COMPATIBILITY_WLM2009 compatibility modes.
 686  *
 687  * </para>
 688  * <note>
 689      <para>
 690        The @software argument will be appended with the libnice version before
 691        being sent.
 692      </para>
 693      <para>
 694        The @software argument must be in UTF-8 encoding and only the first
 695        128 characters will be sent.
 696      </para>
 697    </note>
 698  *
 699  * Since: 0.0.10
 700  *
 701  */
 702 void nice_agent_set_software (NiceAgent *agent, const gchar *software);
 703
 704 G_END_DECLS
 705
 706 #endif /* _AGENT_H */
 707