| agent.h | | agent.h | |
|---|
| | | | |
| skipping to change at line 40 | | skipping to change at line 40 | |
|---|
| * the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which | | * 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 yo
u | | * case the provisions of LGPL are applicable instead of those above. If yo
u | |
| * wish to allow use of your version of this file only under the terms of t
he | | * wish to allow use of your version of this file only under the terms of t
he | |
| * LGPL and not to allow others to use your version of this file under 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 | | * MPL, indicate your decision by deleting the provisions above and replace | |
| * them with the notice and other provisions required by the LGPL. If you d
o | | * them with the notice and other provisions required by the LGPL. If you d
o | |
| * not delete the provisions above, a recipient may use your version of thi
s | | * not delete the provisions above, a recipient may use your version of thi
s | |
| * file under either the MPL or the LGPL. | | * file under either the MPL or the LGPL. | |
| */ | | */ | |
| | | | |
|
| #ifndef _AGENT_H | | #ifndef __LIBNICE_AGENT_H__ | |
| #define _AGENT_H | | #define __LIBNICE_AGENT_H__ | |
| | | | |
| /** | | /** | |
| * SECTION:agent | | * SECTION:agent | |
| * @short_description: ICE agent API implementation | | * @short_description: ICE agent API implementation | |
| * @see_also: #NiceCandidate, #NiceAddress | | * @see_also: #NiceCandidate, #NiceAddress | |
| * @include: agent.h | | * @include: agent.h | |
| * @stability: Stable | | * @stability: Stable | |
| * | | * | |
| * The #NiceAgent is your main object when using libnice. | | * The #NiceAgent is your main object when using libnice. | |
| * It is the agent that will take care of everything relating to ICE. | | * It is the agent that will take care of everything relating to ICE. | |
| * It will take care of discovering your local candidates and do | | * It will take care of discovering your local candidates and do | |
| * connectivity checks to create a stream of data between you and your pee
r. | | * connectivity checks to create a stream of data between you and your pee
r. | |
| * | | * | |
| * A #NiceAgent must always be used with a #GMainLoop running the #GMainCon
text | | * A #NiceAgent must always be used with a #GMainLoop running the #GMainCon
text | |
| * passed into nice_agent_new() (or nice_agent_new_reliable()). Without the | | * passed into nice_agent_new() (or nice_agent_new_reliable()). Without the | |
|
| * #GMainContext being iterated, the agent’s timers will not fire and, if | | * #GMainContext being iterated, the agent’s timers will not fire, etc. | |
| * nice_agent_attach_recv() is used, packets will not be received. | | | |
| * | | * | |
| * Streams and their components are referenced by integer IDs (with respect
to a | | * 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-zer
o) | | * given #NiceAgent). These IDs are guaranteed to be positive (i.e. non-zer
o) | |
| * for valid streams/components. | | * 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 | | * Each stream can receive data in one of two ways: using | |
| * nice_agent_attach_recv() or nice_agent_recv_messages() (and the derived | | * nice_agent_attach_recv() or nice_agent_recv_messages() (and the derived | |
| * #NiceInputStream and #NiceIOStream classes accessible using | | * #NiceInputStream and #NiceIOStream classes accessible using | |
| * nice_agent_get_io_stream()). nice_agent_attach_recv() is non-blocking: i
t | | * nice_agent_get_io_stream()). nice_agent_attach_recv() is non-blocking: i
t | |
| * takes a user-provided callback function and attaches the stream’s sock
et to | | * takes a user-provided callback function and attaches the stream’s sock
et to | |
| * the provided #GMainContext, invoking the callback in that context for ev
ery | | * the provided #GMainContext, invoking the callback in that context for ev
ery | |
| * packet received. nice_agent_recv_messages() instead blocks on receiving
a | | * packet received. nice_agent_recv_messages() instead blocks on receiving
a | |
| * packet, and writes it directly into a user-provided buffer. This reduces
the | | * packet, and writes it directly into a user-provided buffer. This reduces
the | |
| * number of callback invokations and (potentially) buffer copies required
to | | * number of callback invokations and (potentially) buffer copies required
to | |
| * receive packets. nice_agent_recv_messages() (or #NiceInputStream) is des
igned | | * receive packets. nice_agent_recv_messages() (or #NiceInputStream) is des
igned | |
| | | | |
| skipping to change at line 101 | | skipping to change at line 110 | |
|---|
| * G_CALLBACK (cb_candidate_gathering_done), NULL); | | * G_CALLBACK (cb_candidate_gathering_done), NULL); | |
| * g_signal_connect (G_OBJECT (agent), "component-state-changed", | | * g_signal_connect (G_OBJECT (agent), "component-state-changed", | |
| * G_CALLBACK (cb_component_state_changed), NULL); | | * G_CALLBACK (cb_component_state_changed), NULL); | |
| * g_signal_connect (G_OBJECT (agent), "new-selected-pair", | | * g_signal_connect (G_OBJECT (agent), "new-selected-pair", | |
| * G_CALLBACK (cb_new_selected_pair), NULL); | | * G_CALLBACK (cb_new_selected_pair), NULL); | |
| * | | * | |
| * // Create a new stream with one component and start gathering candidat
es | | * // Create a new stream with one component and start gathering candidat
es | |
| * stream_id = nice_agent_add_stream (agent, 1); | | * stream_id = nice_agent_add_stream (agent, 1); | |
| * nice_agent_gather_candidates (agent, stream_id); | | * 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, | | * nice_agent_attach_recv (agent, stream_id, 1, NULL, | |
| * cb_nice_recv, NULL); | | * cb_nice_recv, NULL); | |
| * | | * | |
| * // ... Wait until the signal candidate-gathering-done is fired ... | | * // ... Wait until the signal candidate-gathering-done is fired ... | |
| * lcands = nice_agent_get_local_candidates(agent, stream_id, 1); | | * lcands = nice_agent_get_local_candidates(agent, stream_id, 1); | |
| | | | |
| * nice_agent_get_local_credentials(agent, stream_id, &ufrag, &pwd); | | * nice_agent_get_local_credentials(agent, stream_id, &ufrag, &pwd); | |
| * | | * | |
| * // ... Send local candidates and credentials to the peer | | * // ... Send local candidates and credentials to the peer | |
| * | | * | |
| | | | |
| skipping to change at line 554 | | skipping to change at line 565 | |
|---|
| */ | | */ | |
| gboolean | | gboolean | |
| nice_agent_gather_candidates ( | | nice_agent_gather_candidates ( | |
| NiceAgent *agent, | | NiceAgent *agent, | |
| guint stream_id); | | guint stream_id); | |
| | | | |
| /** | | /** | |
| * nice_agent_set_remote_credentials: | | * nice_agent_set_remote_credentials: | |
| * @agent: The #NiceAgent Object | | * @agent: The #NiceAgent Object | |
| * @stream_id: The ID of the stream | | * @stream_id: The ID of the stream | |
|
| * @ufrag: NULL-terminated string containing an ICE username fragment | | * @ufrag: nul-terminated string containing an ICE username fragment | |
| * (length must be between 22 and 256 chars) | | * (length must be between 22 and 256 chars) | |
|
| * @pwd: NULL-terminated string containing an ICE password | | * @pwd: nul-terminated string containing an ICE password | |
| * (length must be between 4 and 256 chars) | | * (length must be between 4 and 256 chars) | |
| * | | * | |
| * Sets the remote credentials for stream @stream_id. | | * Sets the remote credentials for stream @stream_id. | |
| * | | * | |
| <note> | | <note> | |
| <para> | | <para> | |
| Stream credentials do not override per-candidate credentials if set | | Stream credentials do not override per-candidate credentials if set | |
| </para> | | </para> | |
| <para> | | <para> | |
| Due to the native of peer-reflexive candidates, any agent using a per-
stream | | Due to the native of peer-reflexive candidates, any agent using a per-
stream | |
| | | | |
| skipping to change at line 583 | | skipping to change at line 594 | |
|---|
| * | | * | |
| * Returns: %TRUE on success, %FALSE on error. | | * Returns: %TRUE on success, %FALSE on error. | |
| */ | | */ | |
| gboolean | | gboolean | |
| nice_agent_set_remote_credentials ( | | nice_agent_set_remote_credentials ( | |
| NiceAgent *agent, | | NiceAgent *agent, | |
| guint stream_id, | | guint stream_id, | |
| const gchar *ufrag, const gchar *pwd); | | 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: | | * nice_agent_get_local_credentials: | |
| * @agent: The #NiceAgent Object | | * @agent: The #NiceAgent Object | |
| * @stream_id: The ID of the stream | | * @stream_id: The ID of the stream | |
| * @ufrag: (out callee-allocates): return location for a nul-terminated str
ing | | * @ufrag: (out callee-allocates): return location for a nul-terminated str
ing | |
| * containing an ICE username fragment; must be freed with g_free() | | * containing an ICE username fragment; must be freed with g_free() | |
| * @pwd: (out callee-allocates): return location for a nul-terminated strin
g | | * @pwd: (out callee-allocates): return location for a nul-terminated strin
g | |
| * containing an ICE password; must be freed with g_free() | | * containing an ICE password; must be freed with g_free() | |
| * | | * | |
| * Gets the local credentials for stream @stream_id. This may be called any
time | | * Gets the local credentials for stream @stream_id. This may be called any
time | |
| * after creating a stream using nice_agent_add_stream(). | | * after creating a stream using nice_agent_add_stream(). | |
| | | | |
| skipping to change at line 840 | | skipping to change at line 878 | |
|---|
| NiceAgent *agent, | | NiceAgent *agent, | |
| guint stream_id); | | guint stream_id); | |
| | | | |
| /** | | /** | |
| * nice_agent_attach_recv: (skip) | | * nice_agent_attach_recv: (skip) | |
| * @agent: The #NiceAgent Object | | * @agent: The #NiceAgent Object | |
| * @stream_id: The ID of stream | | * @stream_id: The ID of stream | |
| * @component_id: The ID of the component | | * @component_id: The ID of the component | |
| * @ctx: The Glib Mainloop Context to use for listening on 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 | | * @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 | | * @data: user data associated with the callback | |
| * | | * | |
| * Attaches the stream's component's sockets to the Glib Mainloop Context i
n | | * Attaches the stream's component's sockets to the Glib Mainloop Context i
n | |
|
| * 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 | | * This must not be used in combination with nice_agent_recv_messages() (or | |
| * #NiceIOStream or #NiceInputStream) on the same stream/component pair. | | * #NiceIOStream or #NiceInputStream) on the same stream/component pair. | |
| * | | * | |
| * Calling nice_agent_attach_recv() with a %NULL @func will detach any exis
ting | | * Calling nice_agent_attach_recv() with a %NULL @func will detach any exis
ting | |
| * callback and cause reception to be paused for the given stream/component | | * callback and cause reception to be paused for the given stream/component | |
| * pair. You must iterate the previously specified #GMainContext sufficient
ly to | | * pair. You must iterate the previously specified #GMainContext sufficient
ly to | |
| * ensure all pending I/O callbacks have been received before calling this | | * ensure all pending I/O callbacks have been received before calling this | |
| * function to unset @func, otherwise data loss of received packets may occ
ur. | | * function to unset @func, otherwise data loss of received packets may occ
ur. | |
| * | | * | |
| | | | |
| skipping to change at line 914 | | skipping to change at line 955 | |
|---|
| * @n_messages: number of entries in @messages | | * @n_messages: number of entries in @messages | |
| * @cancellable: (allow-none): a #GCancellable to allow the operation to be | | * @cancellable: (allow-none): a #GCancellable to allow the operation to be | |
| * cancelled from another thread, or %NULL | | * cancelled from another thread, or %NULL | |
| * @error: (allow-none): return location for a #GError, or %NULL | | * @error: (allow-none): return location for a #GError, or %NULL | |
| * | | * | |
| * Block on receiving data from the given stream/component combination on | | * Block on receiving data from the given stream/component combination on | |
| * @agent, returning only once exactly @n_messages messages have been recei
ved | | * @agent, returning only once exactly @n_messages messages have been recei
ved | |
| * and written into @messages, the stream is closed by the other end or by | | * and written into @messages, the stream is closed by the other end or by | |
| * calling nice_agent_remove_stream(), or @cancellable is cancelled. | | * 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 buffe
rs in | | * In the non-error case, in reliable mode, this will block until all buffe
rs in | |
| * all @n_messages have been filled with received data (i.e. @messages is | | * 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 wil
l | | * treated as a large, flat array of buffers). In non-reliable mode, it wil
l | |
| * block until @n_messages messages have been received, each of which does
not | | * 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-reliab
le | | * have to fill all the buffers in its #NiceInputMessage. In the non-reliab
le | |
| * case, each #NiceInputMessage must have enough buffers to contain an enti
re | | * case, each #NiceInputMessage must have enough buffers to contain an enti
re | |
| * message (65536 bytes), or any excess data may be silently dropped. | | * message (65536 bytes), or any excess data may be silently dropped. | |
| * | | * | |
| * For each received message, #NiceInputMessage::length will be set to the | | * For each received message, #NiceInputMessage::length will be set to the | |
| * number of valid bytes stored in the message’s buffers. The bytes are s
tored | | * number of valid bytes stored in the message’s buffers. The bytes are s
tored | |
| | | | |
| skipping to change at line 1010 | | skipping to change at line 1056 | |
|---|
| * returned and @error is set accordingly. Otherwise, 0 is returned if (and
only | | * 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 s
tored | | * if) @n_messages is 0. In all other cases, the number of valid messages s
tored | |
| * in @messages is returned, and will be greater than 0. | | * in @messages is returned, and will be greater than 0. | |
| * | | * | |
| * This function behaves similarly to nice_agent_recv_messages(), except th
at it | | * This function behaves similarly to nice_agent_recv_messages(), except th
at it | |
| * will not block on filling (in reliable mode) or receiving (in non-reliab
le | | * will not block on filling (in reliable mode) or receiving (in non-reliab
le | |
| * mode) exactly @n_messages messages. In reliable mode, it will receive by
tes | | * mode) exactly @n_messages messages. In reliable mode, it will receive by
tes | |
| * into @messages until it would block; in non-reliable mode, it will recei
ve | | * into @messages until it would block; in non-reliable mode, it will recei
ve | |
| * messages until it would block. | | * 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 pari
ty | | * As this function is non-blocking, @cancellable is included only for pari
ty | |
| * with nice_agent_recv_messages(). If @cancellable is cancelled before thi
s | | * with nice_agent_recv_messages(). If @cancellable is cancelled before thi
s | |
| * function is called, a %G_IO_ERROR_CANCELLED error will be returned | | * function is called, a %G_IO_ERROR_CANCELLED error will be returned | |
| * immediately. | | * immediately. | |
| * | | * | |
| * This must not be used in combination with nice_agent_attach_recv() on th
e | | * This must not be used in combination with nice_agent_attach_recv() on th
e | |
| * same stream/component pair. | | * same stream/component pair. | |
| * | | * | |
| * Returns: the number of valid messages written to @messages on success | | * 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 relia
ble | | * (guaranteed to be greater than 0 unless @n_messages is 0), 0 if in relia
ble | |
| | | | |
| skipping to change at line 1185 | | skipping to change at line 1236 | |
|---|
| void nice_agent_set_software ( | | void nice_agent_set_software ( | |
| NiceAgent *agent, | | NiceAgent *agent, | |
| const gchar *software); | | const gchar *software); | |
| | | | |
| /** | | /** | |
| * nice_agent_set_stream_name: | | * nice_agent_set_stream_name: | |
| * @agent: The #NiceAgent Object | | * @agent: The #NiceAgent Object | |
| * @stream_id: The ID of the stream to change | | * @stream_id: The ID of the stream to change | |
| * @name: The new name of the stream or %NULL | | * @name: The new name of the stream or %NULL | |
| * | | * | |
|
| * This function will assign a unique name to a stream. | | * This function will assign a media type to a stream. The only values | |
| * This is only useful when parsing and generating an SDP of the candidates | | * 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_generate_local_sdp()</para> | |
| * <para>See also: nice_agent_parse_remote_sdp()</para> | | * <para>See also: nice_agent_parse_remote_sdp()</para> | |
| * <para>See also: nice_agent_get_stream_name()</para> | | * <para>See also: nice_agent_get_stream_name()</para> | |
| * | | * | |
| * Returns: %TRUE if the name has been set. %FALSE in case of error | | * Returns: %TRUE if the name has been set. %FALSE in case of error | |
| * (invalid stream or duplicate name). | | * (invalid stream or duplicate name). | |
| * Since: 0.1.4 | | * Since: 0.1.4 | |
| */ | | */ | |
| gboolean nice_agent_set_stream_name ( | | gboolean nice_agent_set_stream_name ( | |
| | | | |
| skipping to change at line 1510 | | skipping to change at line 1565 | |
|---|
| * | | * | |
| * Since: 0.1.8 | | * Since: 0.1.8 | |
| */ | | */ | |
| NiceComponentState | | NiceComponentState | |
| nice_agent_get_component_state (NiceAgent *agent, | | nice_agent_get_component_state (NiceAgent *agent, | |
| guint stream_id, | | guint stream_id, | |
| guint component_id); | | guint component_id); | |
| | | | |
| G_END_DECLS | | G_END_DECLS | |
| | | | |
|
| #endif /* _AGENT_H */ | | #endif /* __LIBNICE_AGENT_H__ */ | |
| | | | |
| End of changes. 13 change blocks. |
|---|
| 12 lines changed or deleted | | 67 lines changed or added | |
|---|
|