Commit 718bd720 authored by Ilya Konstantinov's avatar Ilya Konstantinov Committed by Olivier Crête

agent: Improve nice_agent_attach_recv and nice_agent_recv* docs

Explain that either having an I/O callback or calling nice_agent_recv*
is essential for ICE connection check to succeed.

https://bugs.freedesktop.org/show_bug.cgi?id=89849
parent 3ad56081
......@@ -54,13 +54,22 @@
*
* 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 and, if
* nice_agent_attach_recv() is used, packets will not be received.
* #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
......@@ -98,7 +107,9 @@
* stream_id = nice_agent_add_stream (agent, 1);
* nice_agent_gather_candidates (agent, stream_id);
*
* // Attach to the component to receive the data
* // 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);
*
......@@ -881,11 +892,14 @@ nice_agent_restart_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
* 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.
* 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.
......@@ -955,6 +969,11 @@ nice_agent_recv (
* 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
......@@ -1051,6 +1070,11 @@ nice_agent_recv_nonblocking (
* 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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment