[svn-commits] mnicholson: branch irroot/t38gateway-trunk r324622 - /team/irroot/t38gateway-...

[SVN commits to the Digium repositories]

Author: mnicholson
Date: Thu Jun 23 11:24:41 2011
New Revision: 324622

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=324622
Log:
added documentation for fax_session_reserve(), fax_session_new(), and fax_session_release()

Modified:
    team/irroot/t38gateway-trunk/res/res_fax.c

Modified: team/irroot/t38gateway-trunk/res/res_fax.c
URL: http://svnview.digium.com/svn/asterisk/team/irroot/t38gateway-trunk/res/res_fax.c?view=diff&rev=324622&r1=324621&r2=324622
==============================================================================
--- team/irroot/t38gateway-trunk/res/res_fax.c (original)
+++ team/irroot/t38gateway-trunk/res/res_fax.c Thu Jun 23 11:24:41 2011
@@ -740,6 +740,19 @@
 	}
 }
 
+/*! \brief Release a session token.
+ * \param s a session returned from fax_session_reserve()
+ * \param token a token generated from fax_session_reserve()
+ *
+ * This function releases the given token and marks the given session as no
+ * longer reserved. It is safe to call on a session that is not actually
+ * reserved and with a NULL token. This is so that sessions returned by
+ * technologies that do not support reserved sessions don't require extra logic
+ * to handle.
+ *
+ * \note This function DOES NOT release the given fax session, only the given
+ * token.
+ */
 static void fax_session_release(struct ast_fax_session *s, struct ast_fax_tech_token *token)
 {
 	if (token) {
@@ -786,6 +799,19 @@
 	ast_free(s->chan_uniqueid);
 }
 
+/*! \brief Reserve a fax session.
+ * \param details the fax session details
+ * \param token a pointer to a place to store a token to be passed to fax_session_new() later
+ *
+ * This function reserves a fax session for use later. If the selected fax
+ * technology does not support reserving sessions a session will still be
+ * returned but token will not be set.
+ *
+ * \note The reference returned by this function does not get consumed by
+ * fax_session_new() and must always be dereferenced separately.
+ *
+ * \return NULL or an uninitialized and possibly reserved session
+ */
 static struct ast_fax_session *fax_session_reserve(struct ast_fax_session_details *details, struct ast_fax_tech_token **token)
 {
 	struct ast_fax_session *s;
@@ -836,7 +862,22 @@
 	return s;
 }
 
-/*! \brief create a FAX session */
+/*! \brief create a FAX session
+ *
+ * \param details details for the session
+ * \param chan the channel the session will run on
+ * \param reserved a reserved session to base this session on (can be NULL)
+ * \param token the token for a reserved session (can be NULL)
+ *
+ * Create a new fax session based on the given details structure.
+ *
+ * \note The given token is always consumed (by tech->new_session() or by
+ * fax_session_release() in the event of a failure). The given reference to a
+ * reserved session is never consumed and must be dereferenced separately from
+ * the reference returned by this function.
+ *
+ * \return NULL or a reference to a new fax session
+ */
 static struct ast_fax_session *fax_session_new(struct ast_fax_session_details *details, struct ast_channel *chan, struct ast_fax_session *reserved, struct ast_fax_tech_token *token)
 {
 	struct ast_fax_session *s = NULL;
@@ -845,6 +886,12 @@
 	if (reserved) {
 		s = reserved;
 		ao2_ref(reserved, +1);
+
+		/* NOTE: we don't consume the reference to the reserved
+		 * session. The session returned from fax_session_new() is a
+		 * new reference and must be derefed in addition to the
+		 * reserved session.
+		 */
 
 		if (s->state == AST_FAX_STATE_RESERVED) {
 			ast_atomic_fetchadd_int(&faxregistry.reserved_sessions, -1);