summaryrefslogtreecommitdiff
path: root/agent/agent.h
blob: 6e233c6e30953a2f5561b1aa4e5a342149128f0a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
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
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
/*
 * This file is part of the Nice GLib ICE library.
 *
 * (C) 2006-2010 Collabora Ltd.
 *  Contact: Youness Alaoui
 * (C) 2006-2010 Nokia Corporation. All rights reserved.
 *  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.
 *   Youness Alaoui, Collabora Ltd.
 *   Kai Vehmanen, Nokia
 *
 * 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.
 */

#ifndef __LIBNICE_AGENT_H__
#define __LIBNICE_AGENT_H__

/**
 * SECTION:agent
 * @short_description:  ICE agent API implementation
 * @see_also: #NiceCandidate, #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.
 *
 * A #NiceAgent must always be used with a #GMainLoop running the #GMainContext
 * passed into nice_agent_new() (or nice_agent_new_reliable()). Without the
 * #GMainContext being iterated, the agent’s timers will not fire, etc.
 *
 * Streams and their components are referenced by integer IDs (with respect to a
 * given #NiceAgent). These IDs are guaranteed to be positive (i.e. non-zero)
 * for valid streams/components.
 *
 * To complete the ICE connectivity checks, the user must either register
 * an I/O callback (with nice_agent_attach_recv()) or call nice_agent_recv_messages()
 * in a loop on a dedicated thread.
 * Technically, #NiceAgent does not poll the streams on its own, since
 * user data could arrive at any time; to receive STUN packets
 * required for establishing ICE connectivity, it is backpiggying
 * on the facility chosen by the user. #NiceAgent will handle all STUN
 * packets internally; they're never actually passed to the I/O callback
 * or returned from nice_agent_recv_messages() and related functions.
 *
 * Each stream can receive data in one of two ways: using
 * nice_agent_attach_recv() or nice_agent_recv_messages() (and the derived
 * #NiceInputStream and #NiceIOStream classes accessible using
 * nice_agent_get_io_stream()). nice_agent_attach_recv() is non-blocking: it
 * takes a user-provided callback function and attaches the stream’s socket to
 * the provided #GMainContext, invoking the callback in that context for every
 * packet received. nice_agent_recv_messages() instead blocks on receiving a
 * packet, and writes it directly into a user-provided buffer. This reduces the
 * number of callback invokations and (potentially) buffer copies required to
 * receive packets. nice_agent_recv_messages() (or #NiceInputStream) is designed
 * to be used in a blocking loop in a separate thread.
 *
 * <example>
 *   <title>Simple example on how to use libnice</title>
 *   <programlisting>
 *   guint stream_id;
 *   gchar buffer[] = "hello world!";
 *   gchar *ufrag = NULL, *pwd = NULL;
 *   gchar *remote_ufrag, *remote_pwd;
 *   GSList *lcands = NULL;
 *
 *   // Create a nice agent, passing in the global default GMainContext.
 *   NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_RFC5245);
 *   spawn_thread_to_run_main_loop (g_main_loop_new (NULL, FALSE));
 *
 *   // Connect the signals
 *   g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
 *                     G_CALLBACK (cb_candidate_gathering_done), NULL);
 *   g_signal_connect (G_OBJECT (agent), "component-state-changed",
 *                     G_CALLBACK (cb_component_state_changed), NULL);
 *   g_signal_connect (G_OBJECT (agent), "new-selected-pair",
 *                     G_CALLBACK (cb_new_selected_pair), NULL);
 *
 *   // Create a new stream with one component and start gathering candidates
 *   stream_id = nice_agent_add_stream (agent, 1);
 *   nice_agent_gather_candidates (agent, stream_id);
 *
 *   // Attach I/O callback the component to ensure that:
 *   // 1) agent gets its STUN packets (not delivered to cb_nice_recv)
 *   // 2) you get your own 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);

 *   nice_agent_get_local_credentials(agent, stream_id, &ufrag, &pwd);
 *
 *   // ... Send local candidates and credentials to the peer
 *
 *   // Set the peer's remote credentials and remote candidates
 *   nice_agent_set_remote_credentials (agent, stream_id, remote_ufrag, remote_pwd);
 *   nice_agent_set_remote_candidates (agent, stream_id, 1, rcands);
 *
 *   // ... Wait until the signal new-selected-pair is fired ...
 *   // Send our message!
 *   nice_agent_send (agent, stream_id, 1, sizeof(buffer), buffer);
 *
 *   // Anything received will be received through the cb_nice_recv callback.
 *   // You must be running a GMainLoop on the global default GMainContext in
 *   // another thread for this to work.
 *
 *   // Destroy the object
 *   g_object_unref(agent);
 *
 *   </programlisting>
 * </example>
 *
 * Refer to the examples in the examples/ subdirectory of the libnice source for
 * more complete examples.
 *
 */


#include <glib-object.h>
#include <gio/gio.h>

/**
 * NiceAgent:
 *
 * The #NiceAgent is the main GObject of the libnice library and represents
 * the ICE agent.
 */
typedef struct _NiceAgent NiceAgent;

#include "address.h"
#include "candidate.h"
#include "debug.h"


G_BEGIN_DECLS

/**
 * NiceInputMessage:
 * @buffers: (array length=n_buffers): unowned array of #GInputVector buffers to
 * store data in for this message
 * @n_buffers: number of #GInputVectors in @buffers, or -1 to indicate @buffers
 * is %NULL-terminated
 * @from: (allow-none): return location to store the address of the peer who
 * transmitted the message, or %NULL
 * @length: total number of valid bytes contiguously stored in @buffers
 *
 * Represents a single message received off the network. For reliable
 * connections, this is essentially just an array of buffers (specifically,
 * @from can be ignored). for non-reliable connections, it represents a single
 * packet as received from the OS.
 *
 * @n_buffers may be -1 to indicate that @buffers is terminated by a
 * #GInputVector with a %NULL buffer pointer.
 *
 * By providing arrays of #NiceInputMessages to functions like
 * nice_agent_recv_messages(), multiple messages may be received with a single
 * call, which is more efficient than making multiple calls in a loop. In this
 * manner, nice_agent_recv_messages() is analogous to recvmmsg(); and
 * #NiceInputMessage to struct mmsghdr.
 *
 * Since: 0.1.5
 */
typedef struct {
  GInputVector *buffers;
  gint n_buffers;  /* may be -1 to indicate @buffers is NULL-terminated */
  NiceAddress *from;  /* return location for address of message sender */
  gsize length;  /* sum of the lengths of @buffers */
} NiceInputMessage;

/**
 * NiceOutputMessage:
 * @buffers: (array length=n_buffers): unowned array of #GOutputVector buffers
 * which contain data to transmit for this message
 * @n_buffers: number of #GOutputVectors in @buffers, or -1 to indicate @buffers
 * is %NULL-terminated
 *
 * Represents a single message to transmit on the network. For
 * reliable connections, this is essentially just an array of
 * buffer. for non-reliable connections, it represents a single packet
 * to send to the OS.
 *
 * @n_buffers may be -1 to indicate that @buffers is terminated by a
 * #GOutputVector with a %NULL buffer pointer.
 *
 * By providing arrays of #NiceOutputMessages to functions like
 * nice_agent_send_messages_nonblocking(), multiple messages may be transmitted
 * with a single call, which is more efficient than making multiple calls in a
 * loop. In this manner, nice_agent_send_messages_nonblocking() is analogous to
 * sendmmsg(); and #NiceOutputMessage to struct mmsghdr.
 *
 * Since: 0.1.5
 */
typedef struct {
  GOutputVector *buffers;
  gint n_buffers;
} NiceOutputMessage;


#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))

typedef struct _NiceAgentClass NiceAgentClass;

struct _NiceAgentClass
{
  GObjectClass parent_class;
};


GType nice_agent_get_type (void);


/**
 * NICE_AGENT_MAX_REMOTE_CANDIDATES:
 *
 * A hard limit for the number of remote candidates. This
 * limit is enforced to protect against malevolent remote
 * clients.
 */
#define NICE_AGENT_MAX_REMOTE_CANDIDATES    25

/**
 * 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
 * @NICE_COMPONENT_STATE_LAST: Dummy state
 *
 * An enum representing the state of a component.
 * <para> See also: #NiceAgent::component-state-changed </para>
 */
typedef enum
{
  NICE_COMPONENT_STATE_DISCONNECTED,
  NICE_COMPONENT_STATE_GATHERING,
  NICE_COMPONENT_STATE_CONNECTING,
  NICE_COMPONENT_STATE_CONNECTED,
  NICE_COMPONENT_STATE_READY,
  NICE_COMPONENT_STATE_FAILED,
  NICE_COMPONENT_STATE_LAST
} NiceComponentState;


/**
 * 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>
 */
typedef enum
{
  NICE_COMPONENT_TYPE_RTP = 1,
  NICE_COMPONENT_TYPE_RTCP = 2
} NiceComponentType;


/**
 * NiceCompatibility:
 * @NICE_COMPATIBILITY_RFC5245: Use compatibility with the RFC5245 ICE-UDP specs
 * and RFC6544 ICE-TCP specs
 * @NICE_COMPATIBILITY_GOOGLE: Use compatibility for Google Talk specs
 * @NICE_COMPATIBILITY_MSN: Use compatibility for MSN Messenger specs
 * @NICE_COMPATIBILITY_WLM2009: Use compatibility with Windows Live Messenger
 * 2009
 * @NICE_COMPATIBILITY_OC2007: Use compatibility with Microsoft Office Communicator 2007
 * @NICE_COMPATIBILITY_OC2007R2: Use compatibility with Microsoft Office Communicator 2007 R2
 * @NICE_COMPATIBILITY_DRAFT19: Use compatibility for ICE Draft 19 specs
 * @NICE_COMPATIBILITY_LAST: Dummy last compatibility mode
 *
 * An enum to specify which compatible specifications the #NiceAgent should use.
 * Use with nice_agent_new()
 *
 * <warning>@NICE_COMPATIBILITY_DRAFT19 is deprecated and should not be used
 * in newly-written code. It is kept for compatibility reasons and
 * represents the same compatibility as @NICE_COMPATIBILITY_RFC5245 </warning>
 <note>
   <para>
   If @NICE_COMPATIBILITY_RFC5245 compatibility mode is used for a non-reliable
   agent, then ICE-UDP will be used with higher priority and ICE-TCP will also
   be used when the UDP connectivity fails. If it is used with a reliable agent,
   then ICE-UDP will be used with the TCP-Over-UDP (#PseudoTcpSocket) if ICE-TCP
   fails and ICE-UDP succeeds.
  </para>
 </note>
 *
 */
typedef enum
{
  NICE_COMPATIBILITY_RFC5245 = 0,
  NICE_COMPATIBILITY_DRAFT19 = NICE_COMPATIBILITY_RFC5245,
  NICE_COMPATIBILITY_GOOGLE,
  NICE_COMPATIBILITY_MSN,
  NICE_COMPATIBILITY_WLM2009,
  NICE_COMPATIBILITY_OC2007,
  NICE_COMPATIBILITY_OC2007R2,
  NICE_COMPATIBILITY_LAST = NICE_COMPATIBILITY_OC2007R2,
} NiceCompatibility;

/**
 * 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.
 * <para> See also: #NiceAgent:proxy-type </para>
 *
 * Since: 0.0.4
 */
typedef enum
{
  NICE_PROXY_TYPE_NONE = 0,
  NICE_PROXY_TYPE_SOCKS5,
  NICE_PROXY_TYPE_HTTP,
  NICE_PROXY_TYPE_LAST = NICE_PROXY_TYPE_HTTP,
} NiceProxyType;

/**
 * NiceNominationMode:
 * @NICE_NOMINATION_MODE_AGGRESSIVE: Aggressive nomination mode
 * @NICE_NOMINATION_MODE_REGULAR: Regular nomination mode
 *
 * An enum to specity the kind of nomination mode to use by
 * the agent, as described in RFC 5245. Two modes exists,
 * regular and aggressive. They differ by the way the controlling
 * agent chooses to put the USE-CANDIDATE attribute in its STUN
 * messages. The aggressive mode is supposed to nominate a pair
 * faster, than the regular mode, potentially causing the nominated
 * pair to change until the connection check completes.
 *
 * Since: UNRELEASED
 */
typedef enum
{
  NICE_NOMINATION_MODE_REGULAR = 0,
  NICE_NOMINATION_MODE_AGGRESSIVE,
} NiceNominationMode;

/**
 * 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
 *
 */
typedef void (*NiceAgentRecvFunc) (
  NiceAgent *agent, guint stream_id, guint component_id, guint len,
  gchar *buf, gpointer user_data);


/**
 * nice_agent_new:
 * @ctx: The Glib Mainloop Context to use for timers
 * @compat: The compatibility mode of the agent
 *
 * Create a new #NiceAgent.
 * The returned object must be freed with g_object_unref()
 *
 * Returns: The new agent GObject
 */
NiceAgent *
nice_agent_new (GMainContext *ctx, NiceCompatibility compat);


/**
 * 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. If the connectivity is established
 * through ICE-UDP, then a #PseudoTcpSocket will be transparently used to
 * ensure reliability of the messages.
 * The returned object must be freed with g_object_unref()
 * <para> See also: #NiceAgent::reliable-transport-writable </para>
 *
 * Since: 0.0.11
 *
 * Returns: The new agent GObject
 */
NiceAgent *
nice_agent_new_reliable (GMainContext *ctx, NiceCompatibility compat);

/**
 * nice_agent_new_full:
 * @ctx: The Glib Mainloop Context to use for timers
 * @compat: The compatibility mode of the agent
 * @reliable: The reliability mode of the agent
 * @nomination: The nomination mode of the agent
 *
 * Create a new #NiceAgent with parameters that must be be defined at
 * construction time.
 * The returned object must be freed with g_object_unref()
 * <para> See also: #NiceNominationMode </para>
 *
 * Since: UNRELEASED
 *
 * Returns: The new agent GObject
 */
NiceAgent *
nice_agent_new_full (GMainContext *ctx,
  NiceCompatibility compat,
  gboolean reliable,
  NiceNominationMode nomination);

/**
 * 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
 *
 * 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>
 *
 * See also: nice_agent_gather_candidates()
 * Returns: %TRUE on success, %FALSE on fatal (memory allocation) errors
 */
gboolean
nice_agent_add_local_address (NiceAgent *agent, NiceAddress *addr);

/**
 * 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. The
 * returned stream ID is guaranteed to be positive on success.
 *
 * Returns: The ID of the new stream, 0 on failure
 **/
guint
nice_agent_add_stream (
  NiceAgent *agent,
  guint n_components);

/**
 * 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. If any I/O
 * streams have been created using nice_agent_get_io_stream(), they should be
 * closed completely using g_io_stream_close() before this is called, or they
 * will get broken pipe errors.
 *
 **/
void
nice_agent_remove_stream (
  NiceAgent *agent,
  guint stream_id);


/**
 * 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);

/**
 * 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.
 * This may be called multiple times to add multiple relay servers to the
 * discovery process; one TCP and one UDP, for example.
 *
 * Returns: %TRUE if the TURN settings were accepted.
 * %FALSE if the address was invalid.
 */
gboolean nice_agent_set_relay_info(
    NiceAgent *agent,
    guint stream_id,
    guint component_id,
    const gchar *server_ip,
    guint server_port,
    const gchar *username,
    const gchar *password,
    NiceRelayType type);

/**
 * nice_agent_gather_candidates:
 * @agent: The #NiceAgent object
 * @stream_id: The ID of the stream to start
 *
 * Allocate and start listening on local candidate ports and start the remote
 * candidate gathering process.
 * Once done, #NiceAgent::candidate-gathering-done is called for the stream.
 * As soon as this function is called, #NiceAgent::new-candidate signals may be
 * emitted, even before this function returns.
 *
 * nice_agent_get_local_candidates() will only return non-empty results after
 * calling this function.
 *
 * <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; %TRUE otherwise
 *
 <note>
   <para>
    Local addresses can be previously set with nice_agent_add_local_address()
  </para>
  <para>
    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()
   </para>
 </note>
 */
gboolean
nice_agent_gather_candidates (
  NiceAgent *agent,
  guint stream_id);

/**
 * nice_agent_set_remote_credentials:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @ufrag: nul-terminated string containing an ICE username fragment
 *    (length must be between 22 and 256 chars)
 * @pwd: nul-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>
   <para>
     Due to the native of peer-reflexive candidates, any agent using a per-stream
     credentials (RFC5245, WLM2009, OC2007R2 and DRAFT19) instead of
     per-candidate credentials (GOOGLE, MSN, OC2007), must
     use the nice_agent_set_remote_credentials() API instead of setting the
     username and password on the candidates.
   </para>
 </note>
 *
 * Returns: %TRUE on success, %FALSE on error.
 */
gboolean
nice_agent_set_remote_credentials (
  NiceAgent *agent,
  guint stream_id,
  const gchar *ufrag, const gchar *pwd);


/**
 * nice_agent_set_local_credentials:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @ufrag: nul-terminated string containing an ICE username fragment
 *    (length must be between 22 and 256 chars)
 * @pwd: nul-terminated string containing an ICE password
 *    (length must be between 4 and 256 chars)
 *
 * Sets the local credentials for stream @stream_id.
 *
 <note>
   <para>
     This is only effective before ICE negotiation has started.
   </para>
 </note>
 *
 * Since 0.1.11
 * Returns: %TRUE on success, %FALSE on error.
 */
gboolean
nice_agent_set_local_credentials (
  NiceAgent *agent,
  guint stream_id,
  const gchar *ufrag,
  const gchar *pwd);


/**
 * nice_agent_get_local_credentials:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @ufrag: (out callee-allocates): return location for a nul-terminated string
 * containing an ICE username fragment; must be freed with g_free()
 * @pwd: (out callee-allocates): return location for a nul-terminated string
 * containing an ICE password; must be freed with g_free()
 *
 * Gets the local credentials for stream @stream_id. This may be called any time
 * after creating a stream using nice_agent_add_stream().
 *
 * An error will be returned if this is called for a non-existent stream, or if
 * either of @ufrag or @pwd are %NULL.
 *
 * Returns: %TRUE on success, %FALSE on error.
 */
gboolean
nice_agent_get_local_credentials (
  NiceAgent *agent,
  guint stream_id,
  gchar **ufrag, gchar **pwd);

/**
 * 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
 * @candidates: (element-type NiceCandidate) (transfer none): a #GSList of
 * #NiceCandidate items describing each candidate to add
 *
 * Sets, adds or updates the remote candidates for a component of a stream.
 *
 <note>
   <para>
    NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit
    for remote candidates.
   </para>
   <para>
   You must first call nice_agent_gather_candidates() and wait for the
   #NiceAgent::candidate-gathering-done signale before
   calling nice_agent_set_remote_candidates()
   </para>
   <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>
 </note>
 *
 * Returns: The number of candidates added, negative on errors (memory
 * allocation error or invalid component)
 **/
int
nice_agent_set_remote_candidates (
  NiceAgent *agent,
  guint stream_id,
  guint component_id,
  const GSList *candidates);


/**
 * 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>
   <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>
 *
 * Returns: The number of bytes sent, or negative error code
 */
gint
nice_agent_send (
  NiceAgent *agent,
  guint stream_id,
  guint component_id,
  guint len,
  const gchar *buf);

/**
 * nice_agent_send_messages_nonblocking:
 * @agent: a #NiceAgent
 * @stream_id: the ID of the stream to send to
 * @component_id: the ID of the component to send to
 * @messages: (array length=n_messages): array of messages to send, of at least
 * @n_messages entries in length
 * @n_messages: number of entries in @messages
 * @cancellable: (allow-none): a #GCancellable to cancel the operation from
 * another thread, or %NULL
 * @error: (allow-none): return location for a #GError, or %NULL
 *
 * Sends multiple messages on the socket identified by the given
 * stream/component pair. Transmission is non-blocking, so a
 * %G_IO_ERROR_WOULD_BLOCK error may be returned if the send buffer is full.
 *
 * As with nice_agent_send(), the given component must be in
 * %NICE_COMPONENT_STATE_READY or, as a special case, in any state if it was
 * previously ready and was then restarted.
 *
 * On success, the number of messages written to the socket will be returned,
 * which may be less than @n_messages if transmission would have blocked
 * part-way through. Zero will be returned if @n_messages is zero, or if
 * transmission would have blocked on the first message.
 *
 * In reliable mode, it is instead recommended to use
 * nice_agent_send().  The return value can be less than @n_messages
 * or 0 even if it is still possible to send a partial message. In
 * this case, "nice-agent-writable" will never be triggered, so the
 * application would have to use nice_agent_sent() to fill the buffer or have
 * to retry sending at a later point.
 *
 * On failure, -1 will be returned and @error will be set. If the #NiceAgent is
 * reliable and the socket is not yet connected, %G_IO_ERROR_BROKEN_PIPE will be
 * returned; if the write buffer is full, %G_IO_ERROR_WOULD_BLOCK will be
 * returned. In both cases, wait for the #NiceAgent::reliable-transport-writable
 * signal before trying again. If the given @stream_id or @component_id are
 * invalid or not yet connected, %G_IO_ERROR_BROKEN_PIPE will be returned.
 * %G_IO_ERROR_FAILED will be returned for other errors.
 *
 * Returns: the number of messages sent (may be zero), or -1 on error
 *
 * Since: 0.1.5
 */
gint
nice_agent_send_messages_nonblocking (
    NiceAgent *agent,
    guint stream_id,
    guint component_id,
    const NiceOutputMessage *messages,
    guint n_messages,
    GCancellable *cancellable,
    GError **error);

/**
 * nice_agent_get_local_candidates:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 *
 * Retrieve from the agent the list of all local candidates
 * for a stream's component
 *
 <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
     #NiceAgent::candidate-gathering-done signal.
   </para>
 </note>
 *
 * Returns: (element-type NiceCandidate) (transfer full): a #GSList of
 * #NiceCandidate objects representing the local candidates of @agent
 **/
GSList *
nice_agent_get_local_candidates (
  NiceAgent *agent,
  guint stream_id,
  guint component_id);


/**
 * 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>
     The caller owns the returned GSList as well as the candidates contained
     within it.
   </para>
   <para>
     The list of remote candidates can change during processing.
     The client should register for the #NiceAgent::new-remote-candidate signal
     to get notified of new remote candidates.
   </para>
 </note>
 *
 * Returns: (element-type NiceCandidate) (transfer full): a #GSList of
 * #NiceCandidates objects representing the remote candidates set on the @agent
 **/
GSList *
nice_agent_get_remote_candidates (
  NiceAgent *agent,
  guint stream_id,
  guint component_id);

/**
 * 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
nice_agent_restart (
  NiceAgent *agent);

/**
 * nice_agent_restart_stream:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 *
 * Restarts a single stream as defined in RFC 5245. This function
 * needs to be called both when initiating (ICE spec section 9.1.1.1.
 * "ICE Restarts"), as well as when reacting (spec section 9.2.1.1.
 * "Detecting ICE Restart") to a restart.
 *
 * Unlike nice_agent_restart(), this applies to a single stream. It also
 * does not generate a new tie breaker.
 *
 * Returns: %TRUE on success %FALSE on error
 *
 * Since: 0.1.6
 **/
gboolean
nice_agent_restart_stream (
    NiceAgent *agent,
    guint stream_id);


/**
 * nice_agent_attach_recv: (skip)
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of stream
 * @component_id: The ID of the component
 * @ctx: The Glib Mainloop Context to use for listening on the component
 * @func: The callback function to be called when data is received on
 * the stream's component (will not be called for STUN messages that
 * should be handled by #NiceAgent itself)
 * @data: user data associated with the callback
 *
 * Attaches the stream's component's sockets to the Glib Mainloop Context in
 * order to be notified whenever data becomes available for a component,
 * and to enable #NiceAgent to receive STUN messages (during the
 * establishment of ICE connectivity).
 *
 * This must not be used in combination with nice_agent_recv_messages() (or
 * #NiceIOStream or #NiceInputStream) on the same stream/component pair.
 *
 * Calling nice_agent_attach_recv() with a %NULL @func will detach any existing
 * callback and cause reception to be paused for the given stream/component
 * pair. You must iterate the previously specified #GMainContext sufficiently to
 * ensure all pending I/O callbacks have been received before calling this
 * function to unset @func, otherwise data loss of received packets may occur.
 *
 * Returns: %TRUE on success, %FALSE if the stream or component IDs are invalid.
 */
gboolean
nice_agent_attach_recv (
  NiceAgent *agent,
  guint stream_id,
  guint component_id,
  GMainContext *ctx,
  NiceAgentRecvFunc func,
  gpointer data);

/**
 * nice_agent_recv:
 * @agent: a #NiceAgent
 * @stream_id: the ID of the stream to receive on
 * @component_id: the ID of the component to receive on
 * @buf: (array length=buf_len) (out caller-allocates): caller-allocated buffer
 * to write the received data into, of length at least @buf_len
 * @buf_len: length of @buf
 * @cancellable: (allow-none): a #GCancellable to allow the operation to be
 * cancelled from another thread, or %NULL
 * @error: (allow-none): return location for a #GError, or %NULL
 *
 * A single-message version of nice_agent_recv_messages().
 *
 * Returns: the number of bytes written to @buf on success (guaranteed to be
 * greater than 0 unless @buf_len is 0), 0 if in reliable mode and the remote
 * peer closed the stream, or -1 on error
 *
 * Since: 0.1.5
 */
gssize
nice_agent_recv (
    NiceAgent *agent,
    guint stream_id,
    guint component_id,
    guint8 *buf,
    gsize buf_len,
    GCancellable *cancellable,
    GError **error);

/**
 * nice_agent_recv_messages:
 * @agent: a #NiceAgent
 * @stream_id: the ID of the stream to receive on
 * @component_id: the ID of the component to receive on
 * @messages: (array length=n_messages) (out caller-allocates): caller-allocated
 * array of #NiceInputMessages to write the received messages into, of length at
 * least @n_messages
 * @n_messages: number of entries in @messages
 * @cancellable: (allow-none): a #GCancellable to allow the operation to be
 * cancelled from another thread, or %NULL
 * @error: (allow-none): return location for a #GError, or %NULL
 *
 * Block on receiving data from the given stream/component combination on
 * @agent, returning only once exactly @n_messages messages have been received
 * and written into @messages, the stream is closed by the other end or by
 * calling nice_agent_remove_stream(), or @cancellable is cancelled.
 *
 * Any STUN packets received will not be added to @messages; instead,
 * they'll be passed for processing to #NiceAgent itself. Since #NiceAgent
 * does not poll for messages on its own, it's therefore essential to keep
 * calling this function for ICE connection establishment to work.
 *
 * In the non-error case, in reliable mode, this will block until all buffers in
 * all @n_messages have been filled with received data (i.e. @messages is
 * treated as a large, flat array of buffers). In non-reliable mode, it will
 * block until @n_messages messages have been received, each of which does not
 * have to fill all the buffers in its #NiceInputMessage. In the non-reliable
 * case, each #NiceInputMessage must have enough buffers to contain an entire
 * message (65536 bytes), or any excess data may be silently dropped.
 *
 * For each received message, #NiceInputMessage::length will be set to the
 * number of valid bytes stored in the message’s buffers. The bytes are stored
 * sequentially in the buffers; there are no gaps apart from at the end of the
 * buffer array (in non-reliable mode). If non-%NULL on input,
 * #NiceInputMessage::from will have the address of the sending peer stored in
 * it. The base addresses, sizes, and number of buffers in each message will not
 * be modified in any case.
 *
 * This must not be used in combination with nice_agent_attach_recv() on the
 * same stream/component pair.
 *
 * If the stream/component pair doesn’t exist, or if a suitable candidate socket
 * hasn’t yet been selected for it, a %G_IO_ERROR_BROKEN_PIPE error will be
 * returned. A %G_IO_ERROR_CANCELLED error will be returned if the operation was
 * cancelled. %G_IO_ERROR_FAILED will be returned for other errors.
 *
 * Returns: the number of valid messages written to @messages on success
 * (guaranteed to be greater than 0 unless @n_messages is 0), 0 if the remote
 * peer closed the stream, or -1 on error
 *
 * Since: 0.1.5
 */
gint
nice_agent_recv_messages (
    NiceAgent *agent,
    guint stream_id,
    guint component_id,
    NiceInputMessage *messages,
    guint n_messages,
    GCancellable *cancellable,
    GError **error);

/**
 * nice_agent_recv_nonblocking:
 * @agent: a #NiceAgent
 * @stream_id: the ID of the stream to receive on
 * @component_id: the ID of the component to receive on
 * @buf: (array length=buf_len) (out caller-allocates): caller-allocated buffer
 * to write the received data into, of length at least @buf_len
 * @buf_len: length of @buf
 * @cancellable: (allow-none): a #GCancellable to allow the operation to be
 * cancelled from another thread, or %NULL
 * @error: (allow-none): return location for a #GError, or %NULL
 *
 * A single-message version of nice_agent_recv_messages_nonblocking().
 *
 * Returns: the number of bytes received into @buf on success (guaranteed to be
 * greater than 0 unless @buf_len is 0), 0 if in reliable mode and the remote
 * peer closed the stream, or -1 on error
 *
 * Since: 0.1.5
 */
gssize
nice_agent_recv_nonblocking (
    NiceAgent *agent,
    guint stream_id,
    guint component_id,
    guint8 *buf,
    gsize buf_len,
    GCancellable *cancellable,
    GError **error);

/**
 * nice_agent_recv_messages_nonblocking:
 * @agent: a #NiceAgent
 * @stream_id: the ID of the stream to receive on
 * @component_id: the ID of the component to receive on
 * @messages: (array length=n_messages) (out caller-allocates): caller-allocated
 * array of #NiceInputMessages to write the received messages into, of length at
 * least @n_messages
 * @n_messages: number of entries in @messages
 * @cancellable: (allow-none): a #GCancellable to allow the operation to be
 * cancelled from another thread, or %NULL
 * @error: (allow-none): return location for a #GError, or %NULL
 *
 * Try to receive data from the given stream/component combination on @agent,
 * without blocking. If receiving data would block, -1 is returned and
 * %G_IO_ERROR_WOULD_BLOCK is set in @error. If any other error occurs, -1 is
 * returned and @error is set accordingly. Otherwise, 0 is returned if (and only
 * if) @n_messages is 0. In all other cases, the number of valid messages stored
 * in @messages is returned, and will be greater than 0.
 *
 * This function behaves similarly to nice_agent_recv_messages(), except that it
 * will not block on filling (in reliable mode) or receiving (in non-reliable
 * mode) exactly @n_messages messages. In reliable mode, it will receive bytes
 * into @messages until it would block; in non-reliable mode, it will receive
 * messages until it would block.
 *
 * Any STUN packets received will not be added to @messages; instead,
 * they'll be passed for processing to #NiceAgent itself. Since #NiceAgent
 * does not poll for messages on its own, it's therefore essential to keep
 * calling this function for ICE connection establishment to work.
 *
 * As this function is non-blocking, @cancellable is included only for parity
 * with nice_agent_recv_messages(). If @cancellable is cancelled before this
 * function is called, a %G_IO_ERROR_CANCELLED error will be returned
 * immediately.
 *
 * This must not be used in combination with nice_agent_attach_recv() on the
 * same stream/component pair.
 *
 * Returns: the number of valid messages written to @messages on success
 * (guaranteed to be greater than 0 unless @n_messages is 0), 0 if in reliable
 * mode and the remote peer closed the stream, or -1 on error
 *
 * Since: 0.1.5
 */
gint
nice_agent_recv_messages_nonblocking (
    NiceAgent *agent,
    guint stream_id,
    guint component_id,
    NiceInputMessage *messages,
    guint n_messages,
    GCancellable *cancellable,
    GError **error);

/**
 * 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
nice_agent_set_selected_pair (
  NiceAgent *agent,
  guint stream_id,
  guint component_id,
  const gchar *lfoundation,
  const gchar *rfoundation);

/**
 * 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);

/**
 * nice_agent_get_selected_socket:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 *
 * Retreive the local socket associated with the selected candidate pair
 * for media transmission for a given stream's component.
 *
 * This is useful for adding ICE support to legacy applications that already
 * have a protocol that maintains a connection. If the socket is duplicated
 * before unrefing the agent, the application can take over and continue to use
 * it. New applications are encouraged to use the built in libnice stream
 * handling instead and let libnice handle the connection maintenance.
 *
 * Users of this method are encouraged to not use a TURN relay or any kind
 * of proxy, as in this case, the socket will not be available to the
 * application because the packets are encapsulated.
 *
 * Returns: (transfer full) (nullable): pointer to the #GSocket, or %NULL if
 * there is no selected candidate or if the selected candidate is a relayed
 * candidate.
 *
 * Since: 0.1.5
 */
GSocket *
nice_agent_get_selected_socket (
  NiceAgent *agent,
  guint stream_id,
  guint component_id);

/**
 * 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).
 * 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 on failure
 */
gboolean
nice_agent_set_selected_remote_candidate (
  NiceAgent *agent,
  guint stream_id,
  guint component_id,
  NiceCandidate *candidate);


/**
 * nice_agent_set_stream_tos:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @tos: The ToS to set
 *
 * Sets the IP_TOS and/or IPV6_TCLASS field on the stream's sockets' options
 *
 * Since: 0.0.9
 */
void nice_agent_set_stream_tos (
  NiceAgent *agent,
  guint stream_id,
  gint tos);



/**
 * 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>
 * The SOFTWARE attribute will only be added in the #NICE_COMPATIBILITY_RFC5245
 * and #NICE_COMPATIBILITY_WLM2009 compatibility modes.
 *
 * </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>
 *
 * Since: 0.0.10
 *
 */
void nice_agent_set_software (
    NiceAgent *agent,
    const gchar *software);

/**
 * nice_agent_set_stream_name:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream to change
 * @name: The new name of the stream or %NULL
 *
 * This function will assign a media type to a stream. The only values
 * that can be used to produce a valid SDP are: "audio", "video",
 * "text", "application", "image" and "message".
 *
 * This is only useful when parsing and generating an SDP of the
 * candidates.
 *
 * <para>See also: nice_agent_generate_local_sdp()</para>
 * <para>See also: nice_agent_parse_remote_sdp()</para>
 * <para>See also: nice_agent_get_stream_name()</para>
 *
 * Returns: %TRUE if the name has been set. %FALSE in case of error
 * (invalid stream or duplicate name).
 * Since: 0.1.4
 */
gboolean nice_agent_set_stream_name (
    NiceAgent *agent,
    guint stream_id,
    const gchar *name);

/**
 * nice_agent_get_stream_name:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream to change
 *
 * This function will return the name assigned to a stream.

 * <para>See also: nice_agent_set_stream_name()</para>
 *
 * Returns: The name of the stream. The name is only valid while the stream
 * exists or until it changes through a call to nice_agent_set_stream_name().
 *
 *
 * Since: 0.1.4
 */
const gchar *nice_agent_get_stream_name (
    NiceAgent *agent,
    guint stream_id);

/**
 * nice_agent_get_default_local_candidate:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 *
 * This helper function will return the recommended default candidate to be
 * used for non-ICE compatible clients. This will usually be the candidate
 * with the lowest priority, since it will be the longest path but the one with
 * the most chances of success.
 * <note>
     <para>
     This function is only useful in order to manually generate the
     local SDP
     </para>
 * </note>
 *
 * Returns: The candidate to be used as the default candidate, or %NULL in case
 * of error. Must be freed with nice_candidate_free() once done.
 *
 */
NiceCandidate *
nice_agent_get_default_local_candidate (
    NiceAgent *agent,
    guint stream_id,
    guint component_id);

/**
 * nice_agent_generate_local_sdp:
 * @agent: The #NiceAgent Object
 *
 * Generate an SDP string containing the local candidates and credentials for
 * all streams and components in the agent.
 *
 <note>
   <para>
     The SDP will not contain any codec lines and the 'm' line will not list
     any payload types.
   </para>
   <para>
    It is highly recommended to set names on the streams prior to calling this
    function. Unnamed streams will show up as '-' in the 'm' line, but the SDP
    will not be parseable with nice_agent_parse_remote_sdp() if a stream is
    unnamed.
   </para>
   <para>
     The default candidate in the SDP will be selected based on the lowest
     priority candidate for the first component.
   </para>
 </note>
 *
 * <para>See also: nice_agent_set_stream_name() </para>
 * <para>See also: nice_agent_parse_remote_sdp() </para>
 * <para>See also: nice_agent_generate_local_stream_sdp() </para>
 * <para>See also: nice_agent_generate_local_candidate_sdp() </para>
 * <para>See also: nice_agent_get_default_local_candidate() </para>
 *
 * Returns: A string representing the local SDP. Must be freed with g_free()
 * once done.
 *
 * Since: 0.1.4
 **/
gchar *
nice_agent_generate_local_sdp (
  NiceAgent *agent);

/**
 * nice_agent_generate_local_stream_sdp:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @include_non_ice: Whether or not to include non ICE specific lines
 * (m=, c= and a=rtcp: lines)
 *
 * Generate an SDP string containing the local candidates and credentials
 * for a stream.
 *
 <note>
   <para>
     The SDP will not contain any codec lines and the 'm' line will not list
     any payload types.
   </para>
   <para>
    It is highly recommended to set the name of the stream prior to calling this
    function. Unnamed streams will show up as '-' in the 'm' line.
   </para>
   <para>
     The default candidate in the SDP will be selected based on the lowest
     priority candidate.
   </para>
 </note>
 *
 * <para>See also: nice_agent_set_stream_name() </para>
 * <para>See also: nice_agent_parse_remote_stream_sdp() </para>
 * <para>See also: nice_agent_generate_local_sdp() </para>
 * <para>See also: nice_agent_generate_local_candidate_sdp() </para>
 * <para>See also: nice_agent_get_default_local_candidate() </para>
 *
 * Returns: A string representing the local SDP for the stream. Must be freed
 * with g_free() once done.
 *
 * Since: 0.1.4
 **/
gchar *
nice_agent_generate_local_stream_sdp (
    NiceAgent *agent,
    guint stream_id,
    gboolean include_non_ice);

/**
 * nice_agent_generate_local_candidate_sdp:
 * @agent: The #NiceAgent Object
 * @candidate: The candidate to generate
 *
 * Generate an SDP string representing a local candidate.
 *
 * <para>See also: nice_agent_parse_remote_candidate_sdp() </para>
 * <para>See also: nice_agent_generate_local_sdp() </para>
 * <para>See also: nice_agent_generate_local_stream_sdp() </para>
 *
 * Returns: A string representing the SDP for the candidate. Must be freed
 * with g_free() once done.
 *
 * Since: 0.1.4
 **/
gchar *
nice_agent_generate_local_candidate_sdp (
    NiceAgent *agent,
    NiceCandidate *candidate);

/**
 * nice_agent_parse_remote_sdp:
 * @agent: The #NiceAgent Object
 * @sdp: The remote SDP to parse
 *
 * Parse an SDP string and extracts candidates and credentials from it and sets
 * them on the agent.
 *
 <note>
   <para>
    This function will return an error if a stream has not been assigned a name
    with nice_agent_set_stream_name() as it becomes troublesome to assign the
    streams from the agent to the streams in the SDP.
   </para>
 </note>
 *
 *
 * <para>See also: nice_agent_set_stream_name() </para>
 * <para>See also: nice_agent_generate_local_sdp() </para>
 * <para>See also: nice_agent_parse_remote_stream_sdp() </para>
 * <para>See also: nice_agent_parse_remote_candidate_sdp() </para>
 *
 * Returns: The number of candidates added, negative on errors
 *
 * Since: 0.1.4
 **/
int
nice_agent_parse_remote_sdp (
    NiceAgent *agent,
    const gchar *sdp);


/**
 * nice_agent_parse_remote_stream_sdp:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream to parse
 * @sdp: The remote SDP to parse
 * @ufrag: Pointer to store the ice ufrag if non %NULL. Must be freed with
 * g_free() after use
 * @pwd: Pointer to store the ice password if non %NULL. Must be freed with
 * g_free() after use
 *
 * Parse an SDP string representing a single stream and extracts candidates
 * and credentials from it.
 *
 * <para>See also: nice_agent_generate_local_stream_sdp() </para>
 * <para>See also: nice_agent_parse_remote_sdp() </para>
 * <para>See also: nice_agent_parse_remote_candidate_sdp() </para>
 *
 * Returns: (element-type NiceCandidate) (transfer full): A #GSList of
 * candidates parsed from the SDP, or %NULL in case of errors
 *
 * Since: 0.1.4
 **/
GSList *
nice_agent_parse_remote_stream_sdp (
    NiceAgent *agent,
    guint stream_id,
    const gchar *sdp,
    gchar **ufrag,
    gchar **pwd);


/**
 * nice_agent_parse_remote_candidate_sdp:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream the candidate belongs to
 * @sdp: The remote SDP to parse
 *
 * Parse an SDP string and extracts the candidate from it.
 *
 * <para>See also: nice_agent_generate_local_candidate_sdp() </para>
 * <para>See also: nice_agent_parse_remote_sdp() </para>
 * <para>See also: nice_agent_parse_remote_stream_sdp() </para>
 *
 * Returns: The parsed candidate or %NULL if there was an error.
 *
 * Since: 0.1.4
 **/
NiceCandidate *
nice_agent_parse_remote_candidate_sdp (
    NiceAgent *agent,
    guint stream_id,
    const gchar *sdp);

/**
 * nice_agent_get_io_stream:
 * @agent: A #NiceAgent
 * @stream_id: The ID of the stream to wrap
 * @component_id: The ID of the component to wrap
 *
 * Gets a #GIOStream wrapper around the given stream and component in
 * @agent. The I/O stream will be valid for as long as @stream_id is valid.
 * The #GInputStream and #GOutputStream implement #GPollableInputStream and
 * #GPollableOutputStream.
 *
 * This function may only be called on reliable #NiceAgents. It is a
 * programming error to try and create an I/O stream wrapper for an
 * unreliable stream.
 *
 * Returns: (transfer full): A #GIOStream.
 *
 * Since: 0.1.5
 */
GIOStream *
nice_agent_get_io_stream (
    NiceAgent *agent,
    guint stream_id,
    guint component_id);

/**
 * nice_component_state_to_string:
 * @state: a #NiceComponentState
 *
 * Returns a string representation of the state, generally to use in debug
 * messages.
 *
 * Returns: (transfer none): a string representation of @state
 * Since: 0.1.6
 */
const gchar *
nice_component_state_to_string (NiceComponentState state);

/**
 * nice_agent_forget_relays:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 *
 * Forget all the relay servers previously added using
 * nice_agent_set_relay_info(). Currently connected streams will keep
 * using the relay as long as they have not been restarted and haven't
 * succesfully negotiated a different path.
 *
 * Returns: %FALSE if the component could not be found, %TRUE otherwise
 *
 * Since: 0.1.6
 */
gboolean
nice_agent_forget_relays (NiceAgent *agent,
    guint stream_id,
    guint component_id);

/**
 * nice_agent_get_component_state:
 * @agent: The #NiceAgent Object
 * @stream_id: The ID of the stream
 * @component_id: The ID of the component
 *
 * Retrieves the current state of a component.
 *
 * Returns: the #NiceComponentState of the component and
 * %NICE_COMPONENT_STATE_FAILED if the component was invalid.
 *
 * Since: 0.1.8
 */
NiceComponentState
nice_agent_get_component_state (NiceAgent *agent,
    guint stream_id,
    guint component_id);

G_END_DECLS

#endif /* __LIBNICE_AGENT_H__ */