Commit 55e53a9c authored by Philip Withnall's avatar Philip Withnall Committed by Olivier Crête

agent: Move gtk-doc comments from agent.c to agent.h for new API

I completely disagree with this, and believe the C file is a much better
place for them, as then they’re:
 • easier to read while hacking on the functions, and
 • easier to modify once finished hacking on the functions.

I think the argument for putting them in the header files (so that the
documentation is available by the function declarations) is weak, as the
generated gtk-doc manual should be installed on the system alongside the
header files in any case.
parent 905aa839
......@@ -3074,53 +3074,6 @@ done:
return n_valid_messages;
}
/**
* 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.
*
* 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), or -1 on error
*
* Since: 0.1.5
*/
NICEAPI_EXPORT gint
nice_agent_recv_messages (NiceAgent *agent, guint stream_id, guint component_id,
NiceInputMessage *messages, guint n_messages, GCancellable *cancellable,
......@@ -3130,25 +3083,6 @@ nice_agent_recv_messages (NiceAgent *agent, guint stream_id, guint component_id,
component_id, TRUE, messages, n_messages, cancellable, error);
}
/**
* 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), or -1 on error
*
* Since: 0.1.5
*/
NICEAPI_EXPORT gssize
nice_agent_recv (NiceAgent *agent, guint stream_id, guint component_id,
guint8 *buf, gsize buf_len, GCancellable *cancellable, GError **error)
......@@ -3166,45 +3100,6 @@ nice_agent_recv (NiceAgent *agent, guint stream_id, guint component_id,
return local_messages.length;
}
/**
* 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.
*
* 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), or -1 on error
*
* Since: 0.1.5
*/
NICEAPI_EXPORT gint
nice_agent_recv_messages_nonblocking (NiceAgent *agent, guint stream_id,
guint component_id, NiceInputMessage *messages, guint n_messages,
......@@ -3214,25 +3109,6 @@ nice_agent_recv_messages_nonblocking (NiceAgent *agent, guint stream_id,
component_id, FALSE, messages, n_messages, cancellable, 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), or -1 on error
*
* Since: 0.1.5
*/
NICEAPI_EXPORT gssize
nice_agent_recv_nonblocking (NiceAgent *agent, guint stream_id,
guint component_id, guint8 *buf, gsize buf_len, GCancellable *cancellable,
......
......@@ -625,6 +625,43 @@ nice_agent_send (
guint len,
const gchar *buf);
/**
* nice_agent_send_full:
* @agent: a #NiceAgent
* @stream_id: the ID of the stream to send to
* @component_id: the ID of the component to send to
* @buf: (array length=buf_len): data to transmit, of at least @buf_len bytes in
* size
* @buf_len: length of valid data in @buf, in bytes
* @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 the data in @buf 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 bytes written to the socket will be returned (which
* will always be @buf_len when in non-reliable mode, and may be less than
* @buf_len when in reliable mode).
*
* 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 bytes sent (guaranteed to be greater than 0), or -1 on
* error
*
* Since: 0.1.5
*/
gssize
nice_agent_send_full (
NiceAgent *agent,
......@@ -741,6 +778,25 @@ nice_agent_attach_recv (
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), or -1 on error
*
* Since: 0.1.5
*/
gssize
nice_agent_recv (
NiceAgent *agent,
......@@ -751,6 +807,53 @@ nice_agent_recv (
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.
*
* 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), or -1 on error
*
* Since: 0.1.5
*/
gint
nice_agent_recv_messages (
NiceAgent *agent,
......@@ -761,6 +864,25 @@ nice_agent_recv_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), or -1 on error
*
* Since: 0.1.5
*/
gssize
nice_agent_recv_nonblocking (
NiceAgent *agent,
......@@ -771,6 +893,45 @@ nice_agent_recv_nonblocking (
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.
*
* 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), or -1 on error
*
* Since: 0.1.5
*/
gint
nice_agent_recv_messages_nonblocking (
NiceAgent *agent,
......
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