nua: updated documentation.

darcs-hash:20061115171720-65a35-3a6abb1753922d7ffb6f41ee59aa19cdae9df65a.gz

libsofia-sip-ua/nua/Doxyfile

@@ -32,4 +32,4 @@ ALIASES		    += END_NUA_EVENT="@par  "
 
 VERBATIM_HEADERS     = NO
 
-@INCLUDE             = ../sip/sip.doxyaliases
\ No newline at end of file
+@INCLUDE             = ../sip/sip.doxyaliases

libsofia-sip-ua/nua/nua.docs

@@ -571,22 +571,32 @@ void app_r_invite(int           status,
 } /* app_r_invite */
 @endcode
 
-The app_i_state() function is called by callback function when call has
-been successfully set up and the media has been activated.
+The nua_i_state event is sent (and app_i_state() function called by callback
+function) when the call state changes (see @ref nua_uac_call_model
+"client-side call model").
 
 @code
-void app_i_active(int           status,
-                  char const   *phrase,
-                  nua_t        *nua,
-                  nua_magic_t  *magic,
-                  nua_handle_t *nh,
-                  nua_hmagic_t *hmagic,
-                  sip_t const  *sip,
-                  tagi_t        tags[])
+void app_i_state(int           status,
+		 char const   *phrase,
+		 nua_t        *nua,
+		 nua_magic_t  *magic,
+		 nua_handle_t *nh,
+		 nua_hmagic_t *hmagic,
+		 sip_t const  *sip,
+		 tagi_t        tags[])
 {
-  printf("call active\n");
+  nua_callstate_t state = nua_callstate_init;
 
-} /* app_i_active */
+  tl_gets(tags,
+          NUTAG_CALLSTATE_REF(state),
+          NUTAG__REF(state),
+
+  
+    state = (nua_callstate_t)t->t_value;
+
+  printf("call %s\n", nua_callstate_name(state));
+
+} /* app_i_state */
 @endcode
 
 @subsection nua_receiveacall Receive a call
@@ -607,12 +617,12 @@ void app_i_invite(int           status,
 {
   printf("incoming call\n");
 
-  nua_respond(nh, 200, "OK", TAG_END());
+  nua_respond(nh, 200, "OK", SOA_USER_SDP(magic->sdp), TAG_END());
 
 } /* app_i_invite */
 @endcode
 
-The app_i_active() function is called by the callback function when call has
+The app_i_state() function is called by the callback function when call has
 been successfully set up and the media has been activated.
 
 @code

libsofia-sip-ua/nua/nua_message.c

@@ -69,7 +69,7 @@
  * @par Events:
  *    #nua_r_message
  *
- * @sa nua_i_message, @RFC3428
+ * @sa #nua_i_message, @RFC3428
  */
 
 static int process_response_to_message(nua_handle_t *nh,

libsofia-sip-ua/nua/nua_session.c

@@ -427,10 +427,11 @@ int respond_with_retry_after(nua_handle_t *nh, nta_incoming_t *irq,
  * @par
  * The INVITE request message created by nua_invite() operation is saved as
  * a template for automatic re-INVITE requests sent by the session timer
- * ("timer") feature. Please note that the template message is not used when
- * ACK, PRACK, UPDATE or INFO requests are created (however, these requests
- * will include dialog-specific headers like @To, @From, and @CallID as well
- * as preference headers @Allow, @Supported, @UserAgent, @Organization).
+ * ("timer") feature (see NUTAG_SESSION_TIMER() for more details). Please
+ * note that the template message is not used when ACK, PRACK, UPDATE or
+ * INFO requests are created (however, these requests will include
+ * dialog-specific headers like @To, @From, and @CallID as well as
+ * preference headers @Allow, @Supported, @UserAgent, @Organization).
  *
  * @par SDP Handling
  * The initial nua_invite() creates a @ref soa_session_t "soa media session"
@@ -3285,7 +3286,7 @@ static int process_response_to_bye(nua_handle_t *nh,
  * @param sip    pointer to BYE request
  * @param tags   empty
  *
- * @sa @ref nua_call_model, #nua_i_state, nua_bye(), nua_r_bye(), #nua_r_cancel
+ * @sa @ref nua_call_model, #nua_i_state, nua_bye(), nua_bye(), #nua_r_cancel
  *
  * @END_NUA_EVENT
  */
@@ -3421,16 +3422,20 @@ static void signal_call_state_change(nua_handle_t *nh,
  *
  * @brief Call state has changed.
  *
- * This event will be sent whenever the call state changes. In addition to
- * basic changes of session status indicated with enum ::nua_callstate, the
- * @RFC3264 SDP Offer/Answer negotiation status is also included. The
- * negotiation status includes the local SDP (in SOATAG_LOCAL_SDP()) sent
- * and flags indicating whether the local SDP was an offer or answer
- * (NUTAG_OFFER_SENT(), NUTAG_ANSWER_SENT()). Likewise, the received remote
- * SDP is included in tag SOATAG_REMOTE_SDP() and flags indicating whether
- * the remote SDP was an offer or an answer in tags NUTAG_OFFER_RECV() or
- * NUTAG_ANSWER_RECV(). SOATAG_ACTIVE_AUDIO() and SOATAG_ACTIVE_VIDEO() are
- * informational tags used to indicate what is the status of these media.
+ * This event will be sent whenever the call state changes. 
+ *
+ * In addition to basic changes of session status indicated with enum
+ * ::nua_callstate, the @RFC3264 SDP Offer/Answer negotiation status is also
+ * included if it is enabled (by default or with NUTAG_MEDIA_ENABLE(1)). The
+ * received remote SDP is included in tag SOATAG_REMOTE_SDP(). The tags
+ * NUTAG_OFFER_RECV() or NUTAG_ANSWER_RECV() indicate whether the remote SDP
+ * was an offer or an answer. The SDP negotiation result is included in the
+ * tags SOATAG_LOCAL_SDP() and SOATAG_LOCAL_SDP_STR() and tags
+ * NUTAG_OFFER_SENT() or NUTAG_ANSWER_SENT() indicate whether the local SDP
+ * was an offer or answer.
+ *
+ * SOATAG_ACTIVE_AUDIO() and SOATAG_ACTIVE_VIDEO() are informational tags
+ * used to indicate what is the status of audio or video.
  *
  * Note that #nua_i_state also covers call establisment events
  * (#nua_i_active) and termination (#nua_i_terminated).
@@ -3834,7 +3839,7 @@ static int respond_to_options(nua_server_request_t *sr, tagi_t const *tags);
  * @param sip    incoming OPTIONS request
  * @param tags   empty
  *
- * @sa nua_respond(), nua_options(), nua_r_options(), @RFC3261 section 11.2
+ * @sa nua_respond(), nua_options(), #nua_r_options, @RFC3261 section 11.2
  *
  * @END_NUA_EVENT
  */

libsofia-sip-ua/nua/sofia-sip/nua.h

@@ -85,7 +85,7 @@ typedef enum nua_event_e {
   /* Indications */
   nua_i_error,			/**< Error indication */
 
-  nua_i_invite,			/**< Incoming call */
+  nua_i_invite,			/**< Incoming call INVITE */
   nua_i_cancel,			/**< Incoming INVITE has been cancelled */
   nua_i_ack,			/**< Final response to INVITE has been ACKed */
   nua_i_fork,			/**< Outgoing call has been forked */
@@ -95,24 +95,25 @@ typedef enum nua_event_e {
 
   nua_i_outbound,		/**< Status from outbound processing */
 
-  nua_i_bye,			/**< Incoming call hangup */
-  nua_i_options,		/**< Incoming options */
-  nua_i_refer,			/**< Incoming call transfer */
+  nua_i_bye,			/**< Incoming BYE call hangup */
+  nua_i_options,		/**< Incoming OPTIONS */
+  nua_i_refer,			/**< Incoming REFER call transfer */
   nua_i_publish,		/**< Incoming PUBLISH */
   nua_i_prack,			/**< Incoming PRACK */
   nua_i_info,			/**< Incoming session INFO */
   nua_i_update,			/**< Incoming session UPDATE */
   nua_i_message,		/**< Incoming MESSAGE */
   nua_i_chat,			/**< Incoming chat MESSAGE  */
-  nua_i_subscribe,		/**< Incoming subscription */
+  nua_i_subscribe,		/**< Incoming SUBSCRIBE  */
   nua_i_subscription,		/**< Incoming subscription to be authorized */
-  nua_i_notify,			/**< Incoming event */
+  nua_i_notify,			/**< Incoming event NOTIFY */
   nua_i_method,			/**< Incoming, unknown method */
 
   nua_i_media_error,		/**< Offer-answer error indication */
 
   /* Responses */
-  nua_r_set_params,		/**< Answer to nua_set_params() */
+  nua_r_set_params,		/**< Answer to nua_set_params() or 
+				 * nua_get_hparams(). */
   nua_r_get_params,		/**< Answer to nua_get_params() or 
 				 * nua_get_hparams(). */
   nua_r_shutdown,		/**< Answer to nua_shutdown() */
@@ -140,8 +141,9 @@ typedef enum nua_event_e {
   nua_r_notify,			/**< Answer to outgoing NOTIFY */
   nua_r_method,			/**< Answer to unknown outgoing method */
  
+  nua_r_authenticate,		/**< Answer to nua_authenticate() */
+
   /* Internal events: nua hides them from application */
-  nua_r_authenticate,
   nua_r_redirect,
   nua_r_destroy,
   nua_r_respond,
@@ -318,7 +320,7 @@ SOFIAPUBFUN void nua_bye(nua_handle_t *, tag_type_t, tag_value_t, ...);
 
 /** Cancel an INVITE operation */
 SOFIAPUBFUN void nua_cancel(nua_handle_t *, tag_type_t, tag_value_t, ...);
- 
+
 /** Authenticate an operation. */
 SOFIAPUBFUN void nua_authenticate(nua_handle_t *, tag_type_t, tag_value_t, ...);
 

libsofia-sip-ua/nua/sofia-sip/nua_tag.h

@@ -201,6 +201,8 @@ SOFIAPUBVAR tag_typedef_t nutag_method_ref;
  * @par Values
  *    @c 0   Do not allow any subscriptions \n
  *
+ * @sa nua_notifier(), nua_authorize()
+ *
  * Corresponding tag taking reference parameter is 
  * NUTAG_MAX_SUBSCRIPTIONS_REF()
  */
@@ -430,8 +432,46 @@ SOFIAPUBVAR tag_typedef_t nutag_invite_timer_ref;
 
 /**Default session timer in seconds.
  *
- * Set default session timer in seconds when using session timer extension.
- * Re-INVITE will be sent in given intervals.
+ * Set default session timer in seconds when using session timer extension. 
+ * The value given here is the proposed session expiration time in seconds.
+ * Note that the session timer extension is ponly used 
+ *
+ * @par Sending INVITE and UPDATE Requests 
+ *
+ * If NUTAG_SESSION_TIMER() is used with non-zero value, the value is
+ * used in the @SessionExpires header included in the INVITE or UPDATE
+ * requests. The intermediate proxies or the ultimate destination can lower
+ * the interval in @SessionExpires header. If the value is too low, they can
+ * reject the request with the status code <i>422 Session Timer Too
+ * Small</i>. When Re-INVITE will be sent in given intervals. In that case,
+ * @b nua retries the request automatically.
+ * 
+ * @par Returning Response to the INVITE and UPDATE Requests 
+ *
+ * The NUTAG_SESSION_TIMER() value is also used when sending the final
+ * response to the INVITE or UPDATE requests. If the NUTAG_SESSION_TIMER()
+ * value is 0 or the value in the @SessionExpires header of the requeast is
+ * lower than the value in NUTAG_SESSION_TIMER(), the value from the
+ * incoming @SessionExpires header is used. However, if the value in
+ * @SessionExpires is lower than the minimal acceptable session expiration
+ * interval specified with the tag NUTAG_MIN_SE() the request is
+ * automatically rejected with <i>422 Session Timer Too Small</i>.
+ *
+ * @par When to Use NUTAG_SESSION_TIMER()?
+ *
+ * The session time extension is enabled ("timer" feature tag is included in
+ * @Supported header) but not activated by default (no @SessionExpires
+ * header is included in the requests or responses by default). Using
+ * non-zero value with NUTAG_SESSION_TIMER() activates it. When the
+ * extension is activated, @nua refreshes the call state by sending periodic
+ * re-INVITE or UPDATE requests unless the remote end indicated that it will
+ * take care of refreshes.
+ *
+ * The session timer extension is mainly useful for proxies or back-to-back
+ * user agents that keep call state. The call state is "soft" meaning that
+ * if no call-related SIP messages are processed for certain time the state
+ * will be destroyed. An ordinary user-agent can also make use of session
+ * timer if it cannot get any activity feedback from RTP or other media.
  *
  * @par Used with
  *    nua_invite(), nua_update(), nua_respond() \n
@@ -450,7 +490,9 @@ SOFIAPUBVAR tag_typedef_t nutag_invite_timer_ref;
  *
  * Corresponding tag taking reference parameter is NUTAG_SESSION_TIMER_REF()
  *
- * @sa NUTAG_MIN_SE(), NUTAG_SESSION_REFRESHER(),
+ * @sa NUTAG_SUPPORTED(), NUTAG_MIN_SE(), NUTAG_SESSION_REFRESHER(),
+ * nua_invite(), #nua_r_invite, #nua_i_invite, nua_update(), #nua_r_update,
+ * #nua_i_update, 
  * NUTAG_UPDATE_REFRESH(), @RFC4028, @SessionExpires, @MinSE
  */
 #define NUTAG_SESSION_TIMER(x)  nutag_session_timer, tag_uint_v((x))
@@ -1553,7 +1595,7 @@ SOFIAPUBVAR tag_typedef_t nutag_refer_event_ref;
  *
  * Corresponding tag taking reference parameter is NUTAG_REFER_PAUSE_REF()
  *
- * @todo Not implemented.
+ * @deprecated Not implemented.
  */
 #define NUTAG_REFER_PAUSE(x)   nutag_refer_pause, tag_bool_v(x)
 SOFIAPUBVAR tag_typedef_t nutag_refer_pause;
@@ -1623,6 +1665,44 @@ SOFIAPUBVAR tag_typedef_t nutag_allow;
 #define NUTAG_ALLOW_REF(x) nutag_allow_ref, tag_str_vr(&(x))
 SOFIAPUBVAR tag_typedef_t nutag_allow_ref;
 
+
+/** Indicate that a method (or methods) are handled by application.
+ *
+ * This tag is used to add a new method to the already existing set of
+ * methods handled by application, or clear the set. If you want to
+ * determine the set explicitly, include NUTAG_APPL_METHOD() twice,
+ * first with NULL and then with your supported set.
+ *
+ * The default set of application methods now include INVITE, REGISTER,
+ * PUBLISH and SUBSCRIBE.
+ *
+ * If the request method is in the set of methods handled by application,
+ * the nua stack does not automatically respond to the incoming request nor
+ * it will automatically send such a request. Note if the application adds
+ * the PRACK and UPDATE requests to the set of application methods it must
+ * also take care for sending the PRACK and UPDATE requests during the call
+ * setup when necessary.
+ *
+ * @par Used with
+ *    nua_set_params() \n
+ *    nua_set_hparams() \n
+ *    any handle-specific nua call
+ *
+ * @par Parameter type
+ *    char const *
+ *
+ * @par Values
+ *    Valid method name, or comma-separated list of them.
+ *
+ * Corresponding tag taking reference parameter is NUTAG_APPL_METHOD_REF()
+ */
+#define NUTAG_APPL_METHOD(x)     nutag_appl_method, tag_str_v(x)
+SOFIAPUBVAR tag_typedef_t nutag_appl_method;
+
+#define NUTAG_APPL_METHOD_REF(x) nutag_appl_method_ref, tag_str_vr(&(x))
+SOFIAPUBVAR tag_typedef_t nutag_appl_method_ref;
+
+
 /** Support a feature.
  *
  * This tag is used to add a new feature to the existing set of supported
@@ -1897,7 +1977,10 @@ SOFIAPUBVAR tag_typedef_t nutag_service_route_enable;
           nutag_service_route_enable_ref, tag_bool_vr(&(x))
 SOFIAPUBVAR tag_typedef_t nutag_service_route_enable_ref;
 
-/** Enable local media (MSS)
+/** Enable built-in media session handling
+ *
+ * The built-in media session object @soa takes care of most details
+ * of offer-answer negotiation. 
  *
  * @par Used with
  *    nua_create()

libsofia-sip-ua/nua/test_init.c

@@ -78,7 +78,7 @@ int test_nua_init(struct context *ctx,
   ctx->root = su_root_create(NULL);
   TEST_1(ctx->root);
 
-  /* Disable threading by command line switch? */
+  /* Disable threading by command line switch -s */
   su_root_threading(ctx->root, ctx->threading);
 
   if (start_proxy && !o_proxy) {

libsofia-sip-ua/nua/test_refer.c

@@ -530,7 +530,7 @@ int test_refer0(struct context *ctx, int refer_with_id, char const *tests)
   TEST(e->data->e_status, 200);
   TEST_1(e = e->next); TEST_E(e->data->e_event, nua_i_state);
   TEST(callstate(e->data->e_tags), nua_callstate_terminated); /* TERMINATED */
-  TEST_1(!e->next);
+  assert(!e->next); TEST_1(!e->next);
   free_events_in_list(ctx, c->events);
 
   if (print_headings)