agent.h 22.5 KB
Newer Older
1
2
3
/*
 * This file is part of the Nice GLib ICE library.
 *
4
5
6
 * (C) 2006-2010 Collabora Ltd.
 *  Contact: Youness Alaoui
 * (C) 2006-2010 Nokia Corporation. All rights reserved.
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 *  Contact: Kai Vehmanen
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with
 * the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is the Nice GLib ICE library.
 *
 * The Initial Developers of the Original Code are Collabora Ltd and Nokia
 * Corporation. All Rights Reserved.
 *
 * Contributors:
 *   Dafydd Harries, Collabora Ltd.
26
 *   Youness Alaoui, Collabora Ltd.
27
 *   Kai Vehmanen, Nokia
28
29
30
31
32
33
34
35
36
37
38
 *
 * Alternatively, the contents of this file may be used under the terms of the
 * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
 * case the provisions of LGPL are applicable instead of those above. If you
 * wish to allow use of your version of this file only under the terms of the
 * LGPL and not to allow others to use your version of this file under the
 * MPL, indicate your decision by deleting the provisions above and replace
 * them with the notice and other provisions required by the LGPL. If you do
 * not delete the provisions above, a recipient may use your version of this
 * file under either the MPL or the LGPL.
 */
Dafydd Harries's avatar
Dafydd Harries committed
39
40
41
42

#ifndef _AGENT_H
#define _AGENT_H

43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
/**
 * SECTION:agent
 * @short_description:  ICE agent API implementation
 * @see_also: #NiceCandidate
 * @see_also: #NiceAddress
 * @include: agent.h
 * @stability: Stable
 *
 * The #NiceAgent is your main object when using libnice.
 * It is the agent that will take care of everything relating to ICE.
 * It will take care of discovering your local candidates and do
 *  connectivity checks to create a stream of data between you and your peer.
 *
 <example>
   <title>Simple example on how to use libnice</title>
   <programlisting>
   guint stream_id;
   gchar buffer[] = "hello world!";
   GSList *lcands = NULL;

   // Create a nice agent
64
   NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_RFC5245);
65
66
67
68

   // Connect the signals
   g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
                     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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
                     G_CALLBACK (cb_new_selected_pair), NULL);

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

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

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

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

   // ... Wait until the signal new-selected-pair is fired ...
   // Send our message!
90
   nice_agent_send (agent, stream_id, 1, sizeof(buffer), buffer);
91
92
93
94
95
96
97
98
99
100
101

   // Anything received will be received through the cb_nice_recv callback

   // Destroy the object
   g_object_unref(agent);

   </programlisting>
 </example>
 */


Dafydd Harries's avatar
Dafydd Harries committed
102
#include <glib-object.h>
103

104
105
106
107
108
109
/**
 * NiceAgent:
 *
 * The #NiceAgent is the main GObject of the libnice library and represents
 * the ICE agent.
 */
110
111
typedef struct _NiceAgent NiceAgent;

112
#include "address.h"
Dafydd Harries's avatar
Dafydd Harries committed
113
#include "candidate.h"
114
#include "debug.h"
115

116

Dafydd Harries's avatar
Dafydd Harries committed
117
G_BEGIN_DECLS
118

Dafydd Harries's avatar
Dafydd Harries committed
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
#define NICE_TYPE_AGENT nice_agent_get_type()

#define NICE_AGENT(obj) \
  (G_TYPE_CHECK_INSTANCE_CAST ((obj), \
  NICE_TYPE_AGENT, NiceAgent))

#define NICE_AGENT_CLASS(klass) \
  (G_TYPE_CHECK_CLASS_CAST ((klass), \
  NICE_TYPE_AGENT, NiceAgentClass))

#define NICE_IS_AGENT(obj) \
  (G_TYPE_CHECK_INSTANCE_TYPE ((obj), \
  NICE_TYPE_AGENT))

#define NICE_IS_AGENT_CLASS(klass) \
  (G_TYPE_CHECK_CLASS_TYPE ((klass), \
  NICE_TYPE_AGENT))

#define NICE_AGENT_GET_CLASS(obj) \
  (G_TYPE_INSTANCE_GET_CLASS ((obj), \
  NICE_TYPE_AGENT, NiceAgentClass))

Youness Alaoui's avatar
Youness Alaoui committed
141
142
143
144
145
146
147
148
149
150
151
152
153
154
typedef struct _NiceAgentClass NiceAgentClass;

struct _NiceAgentClass
{
  GObjectClass parent_class;
};


GType nice_agent_get_type (void);


/**
 * NICE_AGENT_MAX_REMOTE_CANDIDATES:
 *
155
 * A hard limit for the number of remote candidates. This
Youness Alaoui's avatar
Youness Alaoui committed
156
 * limit is enforced to protect against malevolent remote
157
158
159
160
 * clients.
 */
#define NICE_AGENT_MAX_REMOTE_CANDIDATES    25

Youness Alaoui's avatar
Youness Alaoui committed
161
162
163
164
165
166
167
168
169
170
/**
 * NiceComponentState:
 * @NICE_COMPONENT_STATE_DISCONNECTED: No activity scheduled
 * @NICE_COMPONENT_STATE_GATHERING: Gathering local candidates
 * @NICE_COMPONENT_STATE_CONNECTING: Establishing connectivity
 * @NICE_COMPONENT_STATE_CONNECTED: At least one working candidate pair
 * @NICE_COMPONENT_STATE_READY: ICE concluded, candidate pair selection
 * is now final
 * @NICE_COMPONENT_STATE_FAILED: Connectivity checks have been completed,
 * but connectivity was not established
171
 * @NICE_COMPONENT_STATE_LAST: Dummy state
Youness Alaoui's avatar
Youness Alaoui committed
172
173
 *
 * An enum representing the state of a component.
174
 * <para> See also: #NiceAgent::component-state-changed </para>
Youness Alaoui's avatar
Youness Alaoui committed
175
 */
176
177
typedef enum
{
Youness Alaoui's avatar
Youness Alaoui committed
178
179
180
181
182
183
  NICE_COMPONENT_STATE_DISCONNECTED,
  NICE_COMPONENT_STATE_GATHERING,
  NICE_COMPONENT_STATE_CONNECTING,
  NICE_COMPONENT_STATE_CONNECTED,
  NICE_COMPONENT_STATE_READY,
  NICE_COMPONENT_STATE_FAILED,
Youness Alaoui's avatar
Youness Alaoui committed
184
  NICE_COMPONENT_STATE_LAST
185
186
} NiceComponentState;

Youness Alaoui's avatar
Youness Alaoui committed
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201

/**
 * NiceComponentType:
 * @NICE_COMPONENT_TYPE_RTP: RTP Component type
 * @NICE_COMPONENT_TYPE_RTCP: RTCP Component type
 *
 * Convenience enum representing the type of a component for use as the
 * component_id for RTP/RTCP usages.
 <example>
   <title>Example of use.</title>
   <programlisting>
   nice_agent_send (agent, stream_id, NICE_COMPONENT_TYPE_RTP, len, buf);
   </programlisting>
  </example>
 */
202
203
204
205
206
207
typedef enum
{
  NICE_COMPONENT_TYPE_RTP = 1,
  NICE_COMPONENT_TYPE_RTCP = 2
} NiceComponentType;

208

Youness Alaoui's avatar
Youness Alaoui committed
209
210
/**
 * NiceCompatibility:
211
 * @NICE_COMPATIBILITY_RFC5245: Use compatibility with the RFC5245 ICE specs
Youness Alaoui's avatar
Youness Alaoui committed
212
213
 * @NICE_COMPATIBILITY_GOOGLE: Use compatibility for Google Talk specs
 * @NICE_COMPATIBILITY_MSN: Use compatibility for MSN Messenger specs
Youness Alaoui's avatar
Youness Alaoui committed
214
215
 * @NICE_COMPATIBILITY_WLM2009: Use compatibility with Windows Live Messenger
 * 2009
Jakub Adam's avatar
Jakub Adam committed
216
 * @NICE_COMPATIBILITY_OC2007: Use compatibility with Microsoft Office Communicator 2007
Jakub Adam's avatar
Jakub Adam committed
217
 * @NICE_COMPATIBILITY_OC2007R2: Use compatibility with Microsoft Office Communicator 2007 R2
218
 * @NICE_COMPATIBILITY_DRAFT19: Use compatibility for ICE Draft 19 specs
219
 * @NICE_COMPATIBILITY_LAST: Dummy last compatibility mode
Youness Alaoui's avatar
Youness Alaoui committed
220
221
222
 *
 * An enum to specify which compatible specifications the #NiceAgent should use.
 * Use with nice_agent_new()
223
224
225
226
 *
 * <warning>@NICE_COMPATIBILITY_DRAFT19 is deprecated and should not be used
 * in newly-written code. It is kept for compatibility reasons and
 * represents the same compatibility as @NICE_COMPATIBILITY_RFC5245 </warning>
Youness Alaoui's avatar
Youness Alaoui committed
227
 */
228
229
typedef enum
{
230
  NICE_COMPATIBILITY_RFC5245 = 0,
231
232
  NICE_COMPATIBILITY_GOOGLE,
  NICE_COMPATIBILITY_MSN,
233
  NICE_COMPATIBILITY_WLM2009,
Jakub Adam's avatar
Jakub Adam committed
234
  NICE_COMPATIBILITY_OC2007,
Jakub Adam's avatar
Jakub Adam committed
235
  NICE_COMPATIBILITY_OC2007R2,
236
  NICE_COMPATIBILITY_DRAFT19 = NICE_COMPATIBILITY_RFC5245,
Jakub Adam's avatar
Jakub Adam committed
237
  NICE_COMPATIBILITY_LAST = NICE_COMPATIBILITY_OC2007R2,
238
239
} NiceCompatibility;

240
241
242
243
244
245
246
247
248
/**
 * NiceProxyType:
 * @NICE_PROXY_TYPE_NONE: Do not use a proxy
 * @NICE_PROXY_TYPE_SOCKS5: Use a SOCKS5 proxy
 * @NICE_PROXY_TYPE_HTTP: Use an HTTP proxy
 * @NICE_PROXY_TYPE_LAST: Dummy last proxy type
 *
 * An enum to specify which proxy type to use for relaying.
 * Note that the proxies will only be used with TCP TURN relaying.
249
 * <para> See also: #NiceAgent:proxy-type </para>
250
251
 *
 * Since: 0.0.4
252
253
254
255
256
257
258
259
260
261
 */
typedef enum
{
  NICE_PROXY_TYPE_NONE = 0,
  NICE_PROXY_TYPE_SOCKS5,
  NICE_PROXY_TYPE_HTTP,
  NICE_PROXY_TYPE_LAST = NICE_PROXY_TYPE_HTTP,
} NiceProxyType;


Youness Alaoui's avatar
Youness Alaoui committed
262
263
264
265
266
267
268
269
270
271
272
273
274
/**
 * NiceAgentRecvFunc:
 * @agent: The #NiceAgent Object
 * @stream_id: The id of the stream
 * @component_id: The id of the component of the stream
 *        which received the data
 * @len: The length of the data
 * @buf: The buffer containing the data received
 * @user_data: The user data set in nice_agent_attach_recv()
 *
 * Callback function when data is received on a component
 *
 */
275
276
277
278
typedef void (*NiceAgentRecvFunc) (
  NiceAgent *agent, guint stream_id, guint component_id, guint len,
  gchar *buf, gpointer user_data);

Dafydd Harries's avatar
Dafydd Harries committed
279

Youness Alaoui's avatar
Youness Alaoui committed
280
281
282
283
284
285
/**
 * nice_agent_new:
 * @ctx: The Glib Mainloop Context to use for timers
 * @compat: The compatibility mode of the agent
 *
 * Create a new #NiceAgent.
286
 * The returned object must be freed with g_object_unref()
Youness Alaoui's avatar
Youness Alaoui committed
287
 *
288
 * Returns: The new agent GObject
Youness Alaoui's avatar
Youness Alaoui committed
289
 */
290
NiceAgent *
291
nice_agent_new (GMainContext *ctx, NiceCompatibility compat);
292

293
294
295
296
297
298
299
300
301

/**
 * nice_agent_new_reliable:
 * @ctx: The Glib Mainloop Context to use for timers
 * @compat: The compatibility mode of the agent
 *
 * Create a new #NiceAgent in reliable mode, which uses #PseudoTcpSocket to
 * assure reliability of the messages.
 * The returned object must be freed with g_object_unref()
302
 * <para> See also: #NiceAgent::reliable-transport-writable </para>
303
 *
304
305
 * Since: 0.0.11
 *
306
307
308
309
310
 * Returns: The new agent GObject
 */
NiceAgent *
nice_agent_new_reliable (GMainContext *ctx, NiceCompatibility compat);

Youness Alaoui's avatar
Youness Alaoui committed
311
312
313
314
315
316
/**
 * nice_agent_add_local_address:
 * @agent: The #NiceAgent Object
 * @addr: The address to listen to
 * If the port is 0, then a random port will be chosen by the system
 *
317
318
319
320
321
322
 * Add a local address from which to derive local host candidates for
 * candidate gathering.
 * <para>
 * Since 0.0.5, if this method is not called, libnice will automatically
 * discover the local addresses available
 * </para>
Youness Alaoui's avatar
Youness Alaoui committed
323
 *
324
 * See also: nice_agent_gather_candidates()
Youness Alaoui's avatar
Youness Alaoui committed
325
326
 * Returns: %TRUE on success, %FALSE on fatal (memory allocation) errors
 */
327
gboolean
328
nice_agent_add_local_address (NiceAgent *agent, NiceAddress *addr);
329

Youness Alaoui's avatar
Youness Alaoui committed
330
331
332
333
334
335
336
337
338
339

/**
 * nice_agent_add_stream:
 * @agent: The #NiceAgent Object
 * @n_components: The number of components to add to the stream
 *
 * Adds a data stream to @agent containing @n_components components.
 *
 * Returns: The ID of the new stream, 0 on failure
 **/
Dafydd Harries's avatar
Dafydd Harries committed
340
guint
341
342
nice_agent_add_stream (
  NiceAgent *agent,
343
  guint n_components);
344

Youness Alaoui's avatar
Youness Alaoui committed
345
346
347
348
349
350
351
352
/**
 * nice_agent_remove_stream:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream to remove
 *
 * Remove and free a previously created data stream from @agent
 *
 **/
Dafydd Harries's avatar
Dafydd Harries committed
353
354
355
356
357
void
nice_agent_remove_stream (
  NiceAgent *agent,
  guint stream_id);

358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384

/**
 * nice_agent_set_port_range:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 * @min_port: The minimum port to use
 * @max_port: The maximum port to use
 *
 * Sets a preferred port range for allocating host candidates.
 * <para>
 * If a local host candidate cannot be created on that port
 * range, then the nice_agent_gather_candidates() call will fail.
 * </para>
 * <para>
 * This MUST be called before nice_agent_gather_candidates()
 * </para>
 *
 */
void
nice_agent_set_port_range (
    NiceAgent *agent,
    guint stream_id,
    guint component_id,
    guint min_port,
    guint max_port);

Youness Alaoui's avatar
Youness Alaoui committed
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
/**
 * nice_agent_set_relay_info:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 * @server_ip: The IP address of the TURN server
 * @server_port: The port of the TURN server
 * @username: The TURN username to use for the allocate
 * @password: The TURN password to use for the allocate
 * @type: The type of relay to use
 *
 * Sets the settings for using a relay server during the candidate discovery.
 *
 * Returns: %TRUE if the TURN settings were accepted.
 * %FALSE if the address was invalid.
 */
401
gboolean nice_agent_set_relay_info(
402
403
404
405
406
407
    NiceAgent *agent,
    guint stream_id,
    guint component_id,
    const gchar *server_ip,
    guint server_port,
    const gchar *username,
408
409
    const gchar *password,
    NiceRelayType type);
410

Youness Alaoui's avatar
Youness Alaoui committed
411
412
413
414
415
416
417
418
/**
 * nice_agent_gather_candidates:
 * @agent: The #NiceAgent Object
 * @stream_id: The id of the stream to start
 *
 * Start the candidate gathering process.
 * Once done, #NiceAgent::candidate-gathering-done is called for the stream
 *
419
420
421
422
423
 * <para>See also: nice_agent_add_local_address()</para>
 * <para>See also: nice_agent_set_port_range()</para>
 *
 * Returns: %FALSE if the stream id is invalid or if a host candidate couldn't be allocated
 * on the requested interfaces/ports.
424
 *
Youness Alaoui's avatar
Youness Alaoui committed
425
426
 <note>
   <para>
427
428
429
    Local addresses can be previously set with nice_agent_add_local_address()
  </para>
  <para>
430
431
432
    Since 0.0.5, If no local address was previously added, then the nice agent
    will automatically detect the local address using
    nice_interfaces_get_local_ips()
Youness Alaoui's avatar
Youness Alaoui committed
433
434
435
   </para>
 </note>
 */
436
gboolean
437
438
439
440
nice_agent_gather_candidates (
  NiceAgent *agent,
  guint stream_id);

Youness Alaoui's avatar
Youness Alaoui committed
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
/**
 * nice_agent_set_remote_credentials:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @ufrag: NULL-terminated string containing an ICE username fragment
 *    (length must be between 22 and 256 chars)
 * @pwd: NULL-terminated string containing an ICE password
 *    (length must be between 4 and 256 chars)
 *
 * Sets the remote credentials for stream @stream_id.
 *
 <note>
   <para>
     Stream credentials do not override per-candidate credentials if set
   </para>
 </note>
 *
 * Returns: %TRUE on success, %FALSE on error.
 */
460
461
462
463
464
465
gboolean
nice_agent_set_remote_credentials (
  NiceAgent *agent,
  guint stream_id,
  const gchar *ufrag, const gchar *pwd);

Youness Alaoui's avatar
Youness Alaoui committed
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482


/**
 * nice_agent_get_local_credentials:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @ufrag: a pointer to a NULL-terminated string containing
 * an ICE username fragment [OUT].
 * This string must be freed with g_free()
 * @pwd: a pointer to a NULL-terminated string containing an ICE
 * password [OUT]
 * This string must be freed with g_free()
 *
 * Gets the local credentials for stream @stream_id.
 *
 * Returns: %TRUE on success, %FALSE on error.
 */
483
484
485
486
gboolean
nice_agent_get_local_credentials (
  NiceAgent *agent,
  guint stream_id,
487
  gchar **ufrag, gchar **pwd);
488

Youness Alaoui's avatar
Youness Alaoui committed
489
490
491
492
493
/**
 * nice_agent_set_remote_candidates:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream the candidates are for
 * @component_id: The ID of the component the candidates are for
494
 * @candidates: a #GSList of #NiceCandidate items describing each candidate to add
Youness Alaoui's avatar
Youness Alaoui committed
495
 *
Youness Alaoui's avatar
Youness Alaoui committed
496
 * Sets, adds or updates the remote candidates for a component of a stream.
Youness Alaoui's avatar
Youness Alaoui committed
497
498
499
 *
 <note>
   <para>
500
    NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit
Youness Alaoui's avatar
Youness Alaoui committed
501
502
503
    for remote candidates.
   </para>
   <para>
Youness Alaoui's avatar
fix doc    
Youness Alaoui committed
504
505
   You must first call nice_agent_gather_candidates() and wait for the
   #NiceAgent::candidate-gathering-done signale before
Youness Alaoui's avatar
Youness Alaoui committed
506
   calling nice_agent_set_remote_candidates()
Youness Alaoui's avatar
Youness Alaoui committed
507
   </para>
508
509
510
511
512
513
   <para>
    Since 0.1.3, there is no need to wait for the candidate-gathering-done signal.
    Remote candidates can be set even while gathering local candidates.
    Newly discovered local candidates will automatically be paired with
    existing remote candidates.
   </para>
Youness Alaoui's avatar
Youness Alaoui committed
514
515
 </note>
 *
Youness Alaoui's avatar
Youness Alaoui committed
516
517
 * Returns: The number of candidates added, negative on errors (memory allocation
 * or if the local candidates are not done gathering yet)
Youness Alaoui's avatar
Youness Alaoui committed
518
 **/
519
int
520
521
522
523
nice_agent_set_remote_candidates (
  NiceAgent *agent,
  guint stream_id,
  guint component_id,
524
  const GSList *candidates);
525

Youness Alaoui's avatar
Youness Alaoui committed
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541

/**
 * nice_agent_send:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream to send to
 * @component_id: The ID of the component to send to
 * @len: The length of the buffer to send
 * @buf: The buffer of data to send
 *
 * Sends a data payload over a stream's component.
 *
 <note>
   <para>
     Component state MUST be NICE_COMPONENT_STATE_READY, or as a special case,
     in any state if component was in READY state before and was then restarted
   </para>
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
   <para>
   In reliable mode, the -1 error value means either that you are not yet
   connected or that the send buffer is full (equivalent to EWOULDBLOCK).
   In both cases, you simply need to wait for the
   #NiceAgent::reliable-transport-writable signal to be fired before resending
   the data.
   </para>
   <para>
   In non-reliable mode, it will virtually never happen with UDP sockets, but
   it might happen if the active candidate is a TURN-TCP connection that got
   disconnected.
   </para>
   <para>
   In both reliable and non-reliable mode, a -1 error code could also mean that
   the stream_id and/or component_id are invalid.
   </para>
</note>
Youness Alaoui's avatar
Youness Alaoui committed
559
560
561
 *
 * Returns: The number of bytes sent, or negative error code
 */
562
gint
Dafydd Harries's avatar
Dafydd Harries committed
563
564
565
566
567
nice_agent_send (
  NiceAgent *agent,
  guint stream_id,
  guint component_id,
  guint len,
568
  const gchar *buf);
Dafydd Harries's avatar
Dafydd Harries committed
569

Youness Alaoui's avatar
Youness Alaoui committed
570
571
572
573
574
575
/**
 * nice_agent_get_local_candidates:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 *
576
577
 * Retreive from the agent the list of all local candidates
 * for a stream's component
Youness Alaoui's avatar
Youness Alaoui committed
578
579
580
581
582
583
 *
 <note>
   <para>
     The caller owns the returned GSList as well as the candidates contained
     within it.
     To get full results, the client should wait for the
584
     #NiceAgent::candidate-gathering-done signal.
Youness Alaoui's avatar
Youness Alaoui committed
585
586
587
588
589
590
   </para>
 </note>
 *
 * Returns: a #GSList of #NiceCandidate objects representing
 * the local candidates of @agent
 **/
591
GSList *
592
nice_agent_get_local_candidates (
593
594
595
  NiceAgent *agent,
  guint stream_id,
  guint component_id);
Dafydd Harries's avatar
Dafydd Harries committed
596

Youness Alaoui's avatar
Youness Alaoui committed
597
598
599
600
601
602
603
604
605
606
607

/**
 * nice_agent_get_remote_candidates:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 *
 * Get a list of the remote candidates set on a stream's component
 *
 <note>
   <para>
608
609
     The caller owns the returned GSList but not the candidates
     contained within it.
Youness Alaoui's avatar
Youness Alaoui committed
610
611
612
   </para>
   <para>
     The list of remote candidates can change during processing.
613
614
     The client should register for the #NiceAgent::new-remote-candidate signal
     to get notified of new remote candidates.
Youness Alaoui's avatar
Youness Alaoui committed
615
616
617
618
619
620
   </para>
 </note>
 *
 * Returns: a #GSList of #NiceCandidates objects representing
 * the remote candidates set on the @agent
 **/
621
622
623
624
625
626
GSList *
nice_agent_get_remote_candidates (
  NiceAgent *agent,
  guint stream_id,
  guint component_id);

Youness Alaoui's avatar
Youness Alaoui committed
627
628
629
630
631
632
633
634
635
636
637
638
/**
 * nice_agent_restart:
 * @agent: The #NiceAgent Object
 *
 * Restarts the session as defined in ICE draft 19. This function
 * needs to be called both when initiating (ICE spec section 9.1.1.1.
 * "ICE Restarts"), as well as when reacting (spec section 9.2.1.1.
 * "Detecting ICE Restart") to a restart.
 *
 * Returns: %TRUE on success %FALSE on error
 **/
gboolean
639
640
641
nice_agent_restart (
  NiceAgent *agent);

Youness Alaoui's avatar
Youness Alaoui committed
642
643
644
645
646
647
648

/**
 * nice_agent_attach_recv:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of stream
 * @component_id: The ID of the component
 * @ctx: The Glib Mainloop Context to use for listening on the component
649
650
 * @func: The callback function to be called when data is received on
 * the stream's component
Youness Alaoui's avatar
Youness Alaoui committed
651
652
 * @data: user data associated with the callback
 *
653
654
 * Attaches the stream's component's sockets to the Glib Mainloop Context in
 * order to be notified whenever data becomes available for a component.
Youness Alaoui's avatar
Youness Alaoui committed
655
656
657
 *
 * Returns: %TRUE on success, %FALSE if the stream or component IDs are invalid.
 */
658
gboolean
659
nice_agent_attach_recv (
660
  NiceAgent *agent,
661
662
  guint stream_id,
  guint component_id,
663
664
665
666
  GMainContext *ctx,
  NiceAgentRecvFunc func,
  gpointer data);

Youness Alaoui's avatar
Youness Alaoui committed
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684

/**
 * nice_agent_set_selected_pair:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 * @lfoundation: The local foundation of the candidate to use
 * @rfoundation: The remote foundation of the candidate to use
 *
 * Sets the selected candidate pair for media transmission
 * for a given stream's component. Calling this function will
 * disable all further ICE processing (connection check,
 * state machine updates, etc). Note that keepalives will
 * continue to be sent.
 *
 * Returns: %TRUE on success, %FALSE if the candidate pair cannot be found
 */
gboolean
685
686
687
688
689
690
691
nice_agent_set_selected_pair (
  NiceAgent *agent,
  guint stream_id,
  guint component_id,
  const gchar *lfoundation,
  const gchar *rfoundation);

692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
/**
 * nice_agent_get_selected_pair:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 * @local: The local selected candidate
 * @remote: The remote selected candidate
 *
 * Retreive the selected candidate pair for media transmission
 * for a given stream's component.
 *
 * Returns: %TRUE on success, %FALSE if there is no selected candidate pair
 */
gboolean
nice_agent_get_selected_pair (
  NiceAgent *agent,
  guint stream_id,
  guint component_id,
  NiceCandidate **local,
  NiceCandidate **remote);

Youness Alaoui's avatar
Youness Alaoui committed
713
714
715
716
717
718
719
720
721
722
723
/**
 * nice_agent_set_selected_remote_candidate:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 * @candidate: The #NiceCandidate to select
 *
 * Sets the selected remote candidate for media transmission
 * for a given stream's component. This is used to force the selection of
 * a specific remote candidate even when connectivity checks are failing
 * (e.g. non-ICE compatible candidates).
724
725
 * Calling this function will disable all further ICE processing
 * (connection check, state machine updates, etc). Note that keepalives will
Youness Alaoui's avatar
Youness Alaoui committed
726
727
728
729
 * continue to be sent.
 *
 * Returns: %TRUE on success, %FALSE on failure
 */
730
731
732
733
734
735
736
gboolean
nice_agent_set_selected_remote_candidate (
  NiceAgent *agent,
  guint stream_id,
  guint component_id,
  NiceCandidate *candidate);

Youness Alaoui's avatar
Youness Alaoui committed
737

738
739
740
741
742
743
/**
 * nice_agent_set_stream_tos:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @tos: The ToS to set
 *
Youness Alaoui's avatar
Youness Alaoui committed
744
 * Sets the IP_TOS and/or IPV6_TCLASS field on the stream's sockets' options
745
 *
746
 * Since: 0.0.9
747
748
 */
void nice_agent_set_stream_tos (
Youness Alaoui's avatar
Youness Alaoui committed
749
750
751
752
753
  NiceAgent *agent,
  guint stream_id,
  gint tos);


754
755
756
757
758
759
760
761
762

/**
 * nice_agent_set_software:
 * @agent: The #NiceAgent Object
 * @software: The value of the SOFTWARE attribute to add.
 *
 * This function will set the value of the SOFTWARE attribute to be added to
 * STUN requests, responses and error responses sent during connectivity checks.
 * <para>
763
 * The SOFTWARE attribute will only be added in the #NICE_COMPATIBILITY_RFC5245
764
 * and #NICE_COMPATIBILITY_WLM2009 compatibility modes.
765
 *
766
767
768
769
770
771
772
773
774
775
776
777
 * </para>
 * <note>
     <para>
       The @software argument will be appended with the libnice version before
       being sent.
     </para>
     <para>
       The @software argument must be in UTF-8 encoding and only the first
       128 characters will be sent.
     </para>
   </note>
 *
778
779
 * Since: 0.0.10
 *
780
 */
781
void nice_agent_set_software (NiceAgent *agent, const gchar *software);
782

Dafydd Harries's avatar
Dafydd Harries committed
783
784
G_END_DECLS

Dafydd Harries's avatar
Dafydd Harries committed
785
786
#endif /* _AGENT_H */