agent: Document interaction between closing and removing streams

GIOStream and nice_agent_remove_stream() interact slightly subtly when
closing down the stream.

See: https://bugzilla.gnome.org/show_bug.cgi?id=735754

diff --git a/agent/agent.h b/agent/agent.h
index 60b8990..da59b45 100644 (file)
--- a/agent/agent.h
+++ b/agent/agent.h
@@ -442,7 +442,10 @@ nice_agent_add_stream (
  * @agent: The #NiceAgent Object
  * @stream_id: The ID of the stream to remove
  *
- * Remove and free a previously created data stream from @agent
+ * 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

diff --git a/agent/iostream.c b/agent/iostream.c
index a3a5df3..f22ee45 100644 (file)
--- a/agent/iostream.c
+++ b/agent/iostream.c
@@ -53,7 +53,8 @@
  * If g_io_stream_close() is called on a #NiceIOStream, the I/O stream and
  * underlying #NiceAgent stream will be closed in both directions, but the
  * underlying stream will not be removed. Use nice_agent_remove_stream() to do
- * that.
+ * that, but only do so after g_io_stream_close() has completed, or the stream
+ * will return broken pipe errors.
  *
  * Since: 0.1.5
  */