← Back to branch summary

~ubuntu-branches/debian/stretch/libnice/stretch

« back to all changes in this revision

Viewing changes to agent/agent.h

  • Committer: Package Import Robot
  • Author(s): Simon McVittie
  • Date: 2014-05-14 12:00:13 UTC
  • mfrom: (1.2.9) (5.1.13 sid)
  • Revision ID: package-import@ubuntu.com-20140514120013-fi5mh9bexrjnwnd8
Tags: 0.1.7-1
http://bugs.debian.org/743232
http://bugs.debian.org/743233
* New upstream release 0.1.6, 0.1.7
  - fixes various compiler warnings that were mistakenly fatal in 0.1.5
    (Closes: #743232, #743233)
  - update symbols file for new API
* Explicitly disable -Werror, even if we package a non-release in future
* Don't run tests during the build. We were ignoring failures already,
  and they sometimes hang until the buildd terminates them.
  Upstream (Olivier Crête) says they are stable enough to be useful
  for developers, but not for integration testing.

Show diffs side-by-side

added added

removed removed

Lines of Context:
agent/agent.h
53
53
 * It will take care of discovering your local candidates and do
54
54
 *  connectivity checks to create a stream of data between you and your peer.
55
55
 *
 
56
 * Streams and their components are referenced by integer IDs (with respect to a
 
57
 * given #NiceAgent). These IDs are guaranteed to be positive (i.e. non-zero)
 
58
 * for valid streams/components.
 
59
 *
 
60
 * Each stream can receive data in one of two ways: using
 
61
 * nice_agent_attach_recv() or nice_agent_recv_messages() (and the derived
 
62
 * #NiceInputStream and #NiceIOStream classes accessible using
 
63
 * nice_agent_get_io_stream()). nice_agent_attach_recv() is non-blocking: it
 
64
 * takes a user-provided callback function and attaches the stream’s socket to
 
65
 * the provided #GMainContext, invoking the callback in that context for every
 
66
 * packet received. nice_agent_recv_messages() instead blocks on receiving a
 
67
 * packet, and writes it directly into a user-provided buffer. This reduces the
 
68
 * number of callback invokations and (potentially) buffer copies required to
 
69
 * receive packets. nice_agent_recv_messages() (or #NiceInputStream) is designed
 
70
 * to be used in a blocking loop in a separate thread.
 
71
 *
56
72
 <example>
57
73
   <title>Simple example on how to use libnice</title>
58
74
   <programlisting>
104
120
 
105
121
 
106
122
#include <glib-object.h>
 
123
#include <gio/gio.h>
107
124
 
108
125
/**
109
126
 * NiceAgent:
120
137
 
121
138
G_BEGIN_DECLS
122
139
 
 
140
/**
 
141
 * NiceInputMessage:
 
142
 * @buffers: (array length=n_buffers): unowned array of #GInputVector buffers to
 
143
 * store data in for this message
 
144
 * @n_buffers: number of #GInputVectors in @buffers, or -1 to indicate @buffers
 
145
 * is %NULL-terminated
 
146
 * @from: (allow-none): return location to store the address of the peer who
 
147
 * transmitted the message, or %NULL
 
148
 * @length: total number of valid bytes contiguously stored in @buffers
 
149
 *
 
150
 * Represents a single message received off the network. For reliable
 
151
 * connections, this is essentially just an array of buffers (specifically,
 
152
 * @from can be ignored). for non-reliable connections, it represents a single
 
153
 * packet as received from the OS.
 
154
 *
 
155
 * @n_buffers may be -1 to indicate that @buffers is terminated by a
 
156
 * #GInputVector with a %NULL buffer pointer.
 
157
 *
 
158
 * By providing arrays of #NiceInputMessages to functions like
 
159
 * nice_agent_recv_messages(), multiple messages may be received with a single
 
160
 * call, which is more efficient than making multiple calls in a loop. In this
 
161
 * manner, nice_agent_recv_messages() is analogous to recvmmsg(); and
 
162
 * #NiceInputMessage to struct mmsghdr.
 
163
 *
 
164
 * Since: 0.1.5
 
165
 */
 
166
typedef struct {
 
167
  GInputVector *buffers;
 
168
  gint n_buffers;  /* may be -1 to indicate @buffers is NULL-terminated */
 
169
  NiceAddress *from;  /* return location for address of message sender */
 
170
  gsize length;  /* sum of the lengths of @buffers */
 
171
} NiceInputMessage;
 
172
 
 
173
/**
 
174
 * NiceOutputMessage:
 
175
 * @buffers: (array length=n_buffers): unowned array of #GOutputVector buffers
 
176
 * which contain data to transmit for this message
 
177
 * @n_buffers: number of #GOutputVectors in @buffers, or -1 to indicate @buffers
 
178
 * is %NULL-terminated
 
179
 *
 
180
 * Represents a single message to transmit on the network. For
 
181
 * reliable connections, this is essentially just an array of
 
182
 * buffer. for non-reliable connections, it represents a single packet
 
183
 * to send to the OS.
 
184
 *
 
185
 * @n_buffers may be -1 to indicate that @buffers is terminated by a
 
186
 * #GOutputVector with a %NULL buffer pointer.
 
187
 *
 
188
 * By providing arrays of #NiceOutputMessages to functions like
 
189
 * nice_agent_send_messages_nonblocking(), multiple messages may be transmitted
 
190
 * with a single call, which is more efficient than making multiple calls in a
 
191
 * loop. In this manner, nice_agent_send_messages_nonblocking() is analogous to
 
192
 * sendmmsg(); and #NiceOutputMessage to struct mmsghdr.
 
193
 *
 
194
 * Since: 0.1.5
 
195
 */
 
196
typedef struct {
 
197
  GOutputVector *buffers;
 
198
  gint n_buffers;
 
199
} NiceOutputMessage;
 
200
 
 
201
 
123
202
#define NICE_TYPE_AGENT nice_agent_get_type()
124
203
 
125
204
#define NICE_AGENT(obj) \
337
416
 * @agent: The #NiceAgent Object
338
417
 * @n_components: The number of components to add to the stream
339
418
 *
340
 
 * Adds a data stream to @agent containing @n_components components.
 
419
 * Adds a data stream to @agent containing @n_components components. The
 
420
 * returned stream ID is guaranteed to be positive on success.
341
421
 *
342
422
 * Returns: The ID of the new stream, 0 on failure
343
423
 **/
398
478
 * @type: The type of relay to use
399
479
 *
400
480
 * Sets the settings for using a relay server during the candidate discovery.
 
481
 * This may be called multiple times to add multiple relay servers to the
 
482
 * discovery process; one TCP and one UDP, for example.
401
483
 *
402
484
 * Returns: %TRUE if the TURN settings were accepted.
403
485
 * %FALSE if the address was invalid.
414
496
 
415
497
/**
416
498
 * nice_agent_gather_candidates:
417
 
 * @agent: The #NiceAgent Object
418
 
 * @stream_id: The id of the stream to start
419
 
 *
420
 
 * Start the candidate gathering process.
421
 
 * Once done, #NiceAgent::candidate-gathering-done is called for the stream
 
499
 * @agent: The #NiceAgent object
 
500
 * @stream_id: The ID of the stream to start
 
501
 *
 
502
 * Allocate and start listening on local candidate ports and start the remote
 
503
 * candidate gathering process.
 
504
 * Once done, #NiceAgent::candidate-gathering-done is called for the stream.
 
505
 * As soon as this function is called, #NiceAgent::new-candidate signals may be
 
506
 * emitted, even before this function returns.
 
507
 *
 
508
 * nice_agent_get_local_candidates() will only return non-empty results after
 
509
 * calling this function.
422
510
 *
423
511
 * <para>See also: nice_agent_add_local_address()</para>
424
512
 * <para>See also: nice_agent_set_port_range()</para>
425
513
 *
426
 
 * Returns: %FALSE if the stream id is invalid or if a host candidate couldn't be allocated
427
 
 * on the requested interfaces/ports.
 
514
 * Returns: %FALSE if the stream ID is invalid or if a host candidate couldn't
 
515
 * be allocated on the requested interfaces/ports; %TRUE otherwise
428
516
 *
429
517
 <note>
430
518
   <para>
473
561
 * nice_agent_get_local_credentials:
474
562
 * @agent: The #NiceAgent Object
475
563
 * @stream_id: The ID of the stream
476
 
 * @ufrag: a pointer to a NULL-terminated string containing
477
 
 * an ICE username fragment [OUT].
478
 
 * This string must be freed with g_free()
479
 
 * @pwd: a pointer to a NULL-terminated string containing an ICE
480
 
 * password [OUT]
481
 
 * This string must be freed with g_free()
482
 
 *
483
 
 * Gets the local credentials for stream @stream_id.
 
564
 * @ufrag: (out callee-allocates): return location for a nul-terminated string
 
565
 * containing an ICE username fragment; must be freed with g_free()
 
566
 * @pwd: (out callee-allocates): return location for a nul-terminated string
 
567
 * containing an ICE password; must be freed with g_free()
 
568
 *
 
569
 * Gets the local credentials for stream @stream_id. This may be called any time
 
570
 * after creating a stream using nice_agent_add_stream().
 
571
 *
 
572
 * An error will be returned if this is called for a non-existent stream, or if
 
573
 * either of @ufrag or @pwd are %NULL.
484
574
 *
485
575
 * Returns: %TRUE on success, %FALSE on error.
486
576
 */
572
662
  const gchar *buf);
573
663
 
574
664
/**
 
665
 * nice_agent_send_messages_nonblocking:
 
666
 * @agent: a #NiceAgent
 
667
 * @stream_id: the ID of the stream to send to
 
668
 * @component_id: the ID of the component to send to
 
669
 * @messages: (array length=n_messages): array of messages to send, of at least
 
670
 * @n_messages entries in length
 
671
 * @n_messages: number of entries in @messages
 
672
 * @cancellable: (allow-none): a #GCancellable to cancel the operation from
 
673
 * another thread, or %NULL
 
674
 * @error: (allow-none): return location for a #GError, or %NULL
 
675
 *
 
676
 * Sends multiple messages on the socket identified by the given
 
677
 * stream/component pair. Transmission is non-blocking, so a
 
678
 * %G_IO_ERROR_WOULD_BLOCK error may be returned if the send buffer is full.
 
679
 *
 
680
 * As with nice_agent_send(), the given component must be in
 
681
 * %NICE_COMPONENT_STATE_READY or, as a special case, in any state if it was
 
682
 * previously ready and was then restarted.
 
683
 *
 
684
 * On success, the number of messages written to the socket will be returned,
 
685
 * which may be less than @n_messages if transmission would have blocked
 
686
 * part-way through. Zero will be returned if @n_messages is zero, or if
 
687
 * transmission would have blocked on the first message.
 
688
 *
 
689
 * In reliable mode, it is instead recommended to use
 
690
 * nice_agent_send().  The return value can be less than @n_messages
 
691
 * or 0 even if it is still possible to send a partial message. In
 
692
 * this case, "nice-agent-writable" will never be triggered, so the
 
693
 * application would have to use nice_agent_sent() to fill the buffer or have
 
694
 * to retry sending at a later point.
 
695
 *
 
696
 * On failure, -1 will be returned and @error will be set. If the #NiceAgent is
 
697
 * reliable and the socket is not yet connected, %G_IO_ERROR_BROKEN_PIPE will be
 
698
 * returned; if the write buffer is full, %G_IO_ERROR_WOULD_BLOCK will be
 
699
 * returned. In both cases, wait for the #NiceAgent::reliable-transport-writable
 
700
 * signal before trying again. If the given @stream_id or @component_id are
 
701
 * invalid or not yet connected, %G_IO_ERROR_BROKEN_PIPE will be returned.
 
702
 * %G_IO_ERROR_FAILED will be returned for other errors.
 
703
 *
 
704
 * Returns: the number of messages sent (may be zero), or -1 on error
 
705
 *
 
706
 * Since: 0.1.5
 
707
 */
 
708
gint
 
709
nice_agent_send_messages_nonblocking (
 
710
    NiceAgent *agent,
 
711
    guint stream_id,
 
712
    guint component_id,
 
713
    const NiceOutputMessage *messages,
 
714
    guint n_messages,
 
715
    GCancellable *cancellable,
 
716
    GError **error);
 
717
 
 
718
/**
575
719
 * nice_agent_get_local_candidates:
576
720
 * @agent: The #NiceAgent Object
577
721
 * @stream_id: The ID of the stream
609
753
 *
610
754
 <note>
611
755
   <para>
612
 
     The caller owns the returned GSList but not the candidates
613
 
     contained within it.
 
756
     The caller owns the returned GSList as well as the candidates contained
 
757
     within it.
614
758
   </para>
615
759
   <para>
616
760
     The list of remote candidates can change during processing.
643
787
nice_agent_restart (
644
788
  NiceAgent *agent);
645
789
 
 
790
/**
 
791
 * nice_agent_restart_stream:
 
792
 * @agent: The #NiceAgent Object
 
793
 * @stream_id: The ID of the stream
 
794
 *
 
795
 * Restarts a single stream as defined in RFC 5245. This function
 
796
 * needs to be called both when initiating (ICE spec section 9.1.1.1.
 
797
 * "ICE Restarts"), as well as when reacting (spec section 9.2.1.1.
 
798
 * "Detecting ICE Restart") to a restart.
 
799
 *
 
800
 * Unlike nice_agent_restart(), this applies to a single stream. It also
 
801
 * does not generate a new tie breaker.
 
802
 *
 
803
 * Returns: %TRUE on success %FALSE on error
 
804
 *
 
805
 * Since: 0.1.6
 
806
 **/
 
807
gboolean
 
808
nice_agent_restart_stream (
 
809
    NiceAgent *agent,
 
810
    guint stream_id);
 
811
 
646
812
 
647
813
/**
648
814
 * nice_agent_attach_recv:
657
823
 * Attaches the stream's component's sockets to the Glib Mainloop Context in
658
824
 * order to be notified whenever data becomes available for a component.
659
825
 *
 
826
 * This must not be used in combination with nice_agent_recv_messages() (or
 
827
 * #NiceIOStream or #NiceInputStream) on the same stream/component pair.
 
828
 *
 
829
 * Calling nice_agent_attach_recv() with a %NULL @func will detach any existing
 
830
 * callback and cause reception to be paused for the given stream/component
 
831
 * pair. You must iterate the previously specified #GMainContext sufficiently to
 
832
 * ensure all pending I/O callbacks have been received before calling this
 
833
 * function to unset @func, otherwise data loss of received packets may occur.
 
834
 *
660
835
 * Returns: %TRUE on success, %FALSE if the stream or component IDs are invalid.
661
836
 */
662
837
gboolean
668
843
  NiceAgentRecvFunc func,
669
844
  gpointer data);
670
845
 
 
846
/**
 
847
 * nice_agent_recv:
 
848
 * @agent: a #NiceAgent
 
849
 * @stream_id: the ID of the stream to receive on
 
850
 * @component_id: the ID of the component to receive on
 
851
 * @buf: (array length=buf_len) (out caller-allocates): caller-allocated buffer
 
852
 * to write the received data into, of length at least @buf_len
 
853
 * @buf_len: length of @buf
 
854
 * @cancellable: (allow-none): a #GCancellable to allow the operation to be
 
855
 * cancelled from another thread, or %NULL
 
856
 * @error: (allow-none): return location for a #GError, or %NULL
 
857
 *
 
858
 * A single-message version of nice_agent_recv_messages().
 
859
 *
 
860
 * Returns: the number of bytes written to @buf on success (guaranteed to be
 
861
 * greater than 0 unless @buf_len is 0), or -1 on error
 
862
 *
 
863
 * Since: 0.1.5
 
864
 */
 
865
gssize
 
866
nice_agent_recv (
 
867
    NiceAgent *agent,
 
868
    guint stream_id,
 
869
    guint component_id,
 
870
    guint8 *buf,
 
871
    gsize buf_len,
 
872
    GCancellable *cancellable,
 
873
    GError **error);
 
874
 
 
875
/**
 
876
 * nice_agent_recv_messages:
 
877
 * @agent: a #NiceAgent
 
878
 * @stream_id: the ID of the stream to receive on
 
879
 * @component_id: the ID of the component to receive on
 
880
 * @messages: (array length=n_messages) (out caller-allocates): caller-allocated
 
881
 * array of #NiceInputMessages to write the received messages into, of length at
 
882
 * least @n_messages
 
883
 * @n_messages: number of entries in @messages
 
884
 * @cancellable: (allow-none): a #GCancellable to allow the operation to be
 
885
 * cancelled from another thread, or %NULL
 
886
 * @error: (allow-none): return location for a #GError, or %NULL
 
887
 *
 
888
 * Block on receiving data from the given stream/component combination on
 
889
 * @agent, returning only once exactly @n_messages messages have been received
 
890
 * and written into @messages, the stream is closed by the other end or by
 
891
 * calling nice_agent_remove_stream(), or @cancellable is cancelled.
 
892
 *
 
893
 * In the non-error case, in reliable mode, this will block until all buffers in
 
894
 * all @n_messages have been filled with received data (i.e. @messages is
 
895
 * treated as a large, flat array of buffers). In non-reliable mode, it will
 
896
 * block until @n_messages messages have been received, each of which does not
 
897
 * have to fill all the buffers in its #NiceInputMessage. In the non-reliable
 
898
 * case, each #NiceInputMessage must have enough buffers to contain an entire
 
899
 * message (65536 bytes), or any excess data may be silently dropped.
 
900
 *
 
901
 * For each received message, #NiceInputMessage::length will be set to the
 
902
 * number of valid bytes stored in the message’s buffers. The bytes are stored
 
903
 * sequentially in the buffers; there are no gaps apart from at the end of the
 
904
 * buffer array (in non-reliable mode). If non-%NULL on input,
 
905
 * #NiceInputMessage::from will have the address of the sending peer stored in
 
906
 * it. The base addresses, sizes, and number of buffers in each message will not
 
907
 * be modified in any case.
 
908
 *
 
909
 * This must not be used in combination with nice_agent_attach_recv() on the
 
910
 * same stream/component pair.
 
911
 *
 
912
 * If the stream/component pair doesn’t exist, or if a suitable candidate socket
 
913
 * hasn’t yet been selected for it, a %G_IO_ERROR_BROKEN_PIPE error will be
 
914
 * returned. A %G_IO_ERROR_CANCELLED error will be returned if the operation was
 
915
 * cancelled. %G_IO_ERROR_FAILED will be returned for other errors.
 
916
 *
 
917
 * Returns: the number of valid messages written to @messages on success
 
918
 * (guaranteed to be greater than 0 unless @n_messages is 0), or -1 on error
 
919
 *
 
920
 * Since: 0.1.5
 
921
 */
 
922
gint
 
923
nice_agent_recv_messages (
 
924
    NiceAgent *agent,
 
925
    guint stream_id,
 
926
    guint component_id,
 
927
    NiceInputMessage *messages,
 
928
    guint n_messages,
 
929
    GCancellable *cancellable,
 
930
    GError **error);
 
931
 
 
932
/**
 
933
 * nice_agent_recv_nonblocking:
 
934
 * @agent: a #NiceAgent
 
935
 * @stream_id: the ID of the stream to receive on
 
936
 * @component_id: the ID of the component to receive on
 
937
 * @buf: (array length=buf_len) (out caller-allocates): caller-allocated buffer
 
938
 * to write the received data into, of length at least @buf_len
 
939
 * @buf_len: length of @buf
 
940
 * @cancellable: (allow-none): a #GCancellable to allow the operation to be
 
941
 * cancelled from another thread, or %NULL
 
942
 * @error: (allow-none): return location for a #GError, or %NULL
 
943
 *
 
944
 * A single-message version of nice_agent_recv_messages_nonblocking().
 
945
 *
 
946
 * Returns: the number of bytes received into @buf on success (guaranteed to be
 
947
 * greater than 0 unless @buf_len is 0), or -1 on error
 
948
 *
 
949
 * Since: 0.1.5
 
950
 */
 
951
gssize
 
952
nice_agent_recv_nonblocking (
 
953
    NiceAgent *agent,
 
954
    guint stream_id,
 
955
    guint component_id,
 
956
    guint8 *buf,
 
957
    gsize buf_len,
 
958
    GCancellable *cancellable,
 
959
    GError **error);
 
960
 
 
961
/**
 
962
 * nice_agent_recv_messages_nonblocking:
 
963
 * @agent: a #NiceAgent
 
964
 * @stream_id: the ID of the stream to receive on
 
965
 * @component_id: the ID of the component to receive on
 
966
 * @messages: (array length=n_messages) (out caller-allocates): caller-allocated
 
967
 * array of #NiceInputMessages to write the received messages into, of length at
 
968
 * least @n_messages
 
969
 * @n_messages: number of entries in @messages
 
970
 * @cancellable: (allow-none): a #GCancellable to allow the operation to be
 
971
 * cancelled from another thread, or %NULL
 
972
 * @error: (allow-none): return location for a #GError, or %NULL
 
973
 *
 
974
 * Try to receive data from the given stream/component combination on @agent,
 
975
 * without blocking. If receiving data would block, -1 is returned and
 
976
 * %G_IO_ERROR_WOULD_BLOCK is set in @error. If any other error occurs, -1 is
 
977
 * returned and @error is set accordingly. Otherwise, 0 is returned if (and only
 
978
 * if) @n_messages is 0. In all other cases, the number of valid messages stored
 
979
 * in @messages is returned, and will be greater than 0.
 
980
 *
 
981
 * This function behaves similarly to nice_agent_recv_messages(), except that it
 
982
 * will not block on filling (in reliable mode) or receiving (in non-reliable
 
983
 * mode) exactly @n_messages messages. In reliable mode, it will receive bytes
 
984
 * into @messages until it would block; in non-reliable mode, it will receive
 
985
 * messages until it would block.
 
986
 *
 
987
 * As this function is non-blocking, @cancellable is included only for parity
 
988
 * with nice_agent_recv_messages(). If @cancellable is cancelled before this
 
989
 * function is called, a %G_IO_ERROR_CANCELLED error will be returned
 
990
 * immediately.
 
991
 *
 
992
 * This must not be used in combination with nice_agent_attach_recv() on the
 
993
 * same stream/component pair.
 
994
 *
 
995
 * Returns: the number of valid messages written to @messages on success
 
996
 * (guaranteed to be greater than 0 unless @n_messages is 0), or -1 on error
 
997
 *
 
998
 * Since: 0.1.5
 
999
 */
 
1000
gint
 
1001
nice_agent_recv_messages_nonblocking (
 
1002
    NiceAgent *agent,
 
1003
    guint stream_id,
 
1004
    guint component_id,
 
1005
    NiceInputMessage *messages,
 
1006
    guint n_messages,
 
1007
    GCancellable *cancellable,
 
1008
    GError **error);
671
1009
 
672
1010
/**
673
1011
 * nice_agent_set_selected_pair:
715
1053
  NiceCandidate **remote);
716
1054
 
717
1055
/**
 
1056
 * nice_agent_get_selected_socket:
 
1057
 * @agent: The #NiceAgent Object
 
1058
 * @stream_id: The ID of the stream
 
1059
 * @component_id: The ID of the component
 
1060
 *
 
1061
 * Retreive the local socket associated with the selected candidate pair
 
1062
 * for media transmission for a given stream's component.
 
1063
 *
 
1064
 * This is useful for adding ICE support to legacy applications that already
 
1065
 * have a protocol that maintains a connection. If the socket is duplicated
 
1066
 * before unrefing the agent, the application can take over and continue to use
 
1067
 * it. New applications are encouraged to use the built in libnice stream
 
1068
 * handling instead and let libnice handle the connection maintenance.
 
1069
 *
 
1070
 * Users of this method are encouraged to not use a TURN relay or any kind
 
1071
 * of proxy, as in this case, the socket will not be available to the
 
1072
 * application because the packets are encapsulated.
 
1073
 *
 
1074
 * Returns: (transfer full) pointer to the #GSocket, or NULL if there is no
 
1075
 * selected candidate or if the selected candidate is a relayed candidate.
 
1076
 *
 
1077
 * Since: 0.1.5
 
1078
 */
 
1079
GSocket *
 
1080
nice_agent_get_selected_socket (
 
1081
  NiceAgent *agent,
 
1082
  guint stream_id,
 
1083
  guint component_id);
 
1084
 
 
1085
/**
718
1086
 * nice_agent_set_selected_remote_candidate:
719
1087
 * @agent: The #NiceAgent Object
720
1088
 * @stream_id: The ID of the stream
1041
1409
    guint stream_id,
1042
1410
    const gchar *sdp);
1043
1411
 
 
1412
/**
 
1413
 * nice_agent_get_io_stream:
 
1414
 * @agent: A #NiceAgent
 
1415
 * @stream_id: The ID of the stream to wrap
 
1416
 * @component_id: The ID of the component to wrap
 
1417
 *
 
1418
 * Gets a #GIOStream wrapper around the given stream and component in
 
1419
 * @agent. The I/O stream will be valid for as long as @stream_id is valid.
 
1420
 * The #GInputStream and #GOutputStream implement #GPollableInputStream and
 
1421
 * #GPollableOutputStream.
 
1422
 *
 
1423
 * This function may only be called on reliable #NiceAgents. It is a
 
1424
 * programming error to try and create an I/O stream wrapper for an
 
1425
 * unreliable stream.
 
1426
 *
 
1427
 * Returns: (transfer full): A #GIOStream.
 
1428
 *
 
1429
 * Since: 0.1.5
 
1430
 */
 
1431
GIOStream *
 
1432
nice_agent_get_io_stream (
 
1433
    NiceAgent *agent,
 
1434
    guint stream_id,
 
1435
    guint component_id);
 
1436
 
 
1437
/**
 
1438
 * nice_component_state_to_string:
 
1439
 * @state: a #NiceComponentState
 
1440
 *
 
1441
 * Returns a string representation of the state, generally to use in debug
 
1442
 * messages.
 
1443
 *
 
1444
 * Returns: (transfer none): a string representation of @state
 
1445
 * Since: 0.1.6
 
1446
 */
 
1447
const gchar *
 
1448
nice_component_state_to_string (NiceComponentState state);
 
1449
 
 
1450
/**
 
1451
 * nice_agent_forget_relays:
 
1452
 * @agent: The #NiceAgent Object
 
1453
 * @stream_id: The ID of the stream
 
1454
 * @component_id: The ID of the component
 
1455
 *
 
1456
 * Forget all the relay servers previously added using
 
1457
 * nice_agent_set_relay_info(). Currently connected streams will keep
 
1458
 * using the relay as long as they have not been restarted and haven't
 
1459
 * succesfully negotiated a different path.
 
1460
 *
 
1461
 * Returns: %FALSE if the component could not be found, %TRUE otherwise
 
1462
 *
 
1463
 * Since: 0.1.6
 
1464
 */
 
1465
gboolean
 
1466
nice_agent_forget_relays (NiceAgent *agent,
 
1467
    guint stream_id,
 
1468
    guint component_id);
 
1469
 
1044
1470
G_END_DECLS
1045
1471
 
1046
1472
#endif /* _AGENT_H */