nua: updated documentation. Moved documentation entries towards implementation.

darcs-hash:20061025081244-65a35-9a77e1c68163fba2f5d2a26823d502236adcfd17.gz

libsofia-sip-ua/nua/nua.c

@@ -176,7 +176,7 @@ nua_t *nua_create(su_root_t *root,
  *
  * Ongoing calls are released, registrations unregistered, and 
  * subscriptions terminated.  If the stack cannot terminate within 
- * 30 seconds, it sends the nua_r_shutdown event with status 500.
+ * 30 seconds, it sends the #nua_r_shutdown event with status 500.
  *
  * @param nua         Pointer to @nua stack object
  *
@@ -290,6 +290,10 @@ nua_handle_t *nua_default(nua_t *nua)
  *     the handle. They include @ContentLength, @CSeq, @RSeq, @RAck, and
  *     @Timestamp.
  *
+ * @par
+ *     nua_handle() accepts all the tags accepted by nua_set_hparams(), too.
+ *
+ *
  * @par Events:
  *     none
  *
@@ -495,8 +499,8 @@ int nua_handle_has_active_call(nua_handle_t const *nh)
  *
  * Please note that this status is not affected by remote end putting 
  * this end on hold. Remote end can put each media separately on hold 
- * and status is reflected on #SOATAG_ACTIVE_AUDIO, #SOATAG_ACTIVE_VIDEO 
- * and #SOATAG_ACTIVE_CHAT tag values in nua_i_active event.
+ * and status is reflected on SOATAG_ACTIVE_AUDIO(), SOATAG_ACTIVE_VIDEO() 
+ * and SOATAG_ACTIVE_CHAT() tag values in #nua_i_state event.
  *
  * @param nh          Pointer to operation handle
  *
@@ -674,6 +678,8 @@ void nua_options(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
  *    nothing
  *
  * @par Related Tags:
+ *    NUTAG_URL() \n
+ *    Tags of nua_set_hparams() \n
  *    Tags in <sip_tag.h>
  *
  * @par Events:
@@ -687,8 +693,8 @@ void nua_message(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
 /** Send a chat message. 
  *
  * A chat channel can be established during call setup using "message" media. 
- * An active chat channel is indicated using nua_i_active event containing 
- * #SOATAG_ACTIVE_CHAT tag. Chat messages can be sent using this channel with 
+ * An active chat channel is indicated using #nua_i_state event containing 
+ * SOATAG_ACTIVE_CHAT() tag. Chat messages can be sent using this channel with 
  * nua_chat() function. Currently this is implemented using SIP MESSAGE 
  * requests but in future MSRP (message session protocol) will replace it.
 *
@@ -699,11 +705,11 @@ void nua_message(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
  *    nothing
  *
  * @par Related Tags:
- *    #SIPTAG_CONTENT_TYPE \n
- *    #SIPTAG_PAYLOAD      \n
- *    #SIPTAG_FROM         \n
- *    #SIPTAG_TO           \n
- *    use of other SIP tags' is deprecated
+ *    SIPTAG_CONTENT_TYPE() \n
+ *    SIPTAG_PAYLOAD()      \n
+ *    SIPTAG_FROM()         \n
+ *    SIPTAG_TO()           \n
+ *    Use of other SIP tags is deprecated
  *
  * @par Events:
  *    #nua_r_chat
@@ -713,52 +719,13 @@ void nua_chat(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
   NUA_SIGNAL(nh, nua_r_chat, tag, value);
 }
 
-/** Subscribe a SIP event. 
- *
- * Subscribe a SIP event using the SIP SUBSCRIBE request. If the 
- * SUBSCRBE is successful a subscription state is established and 
- * the subscription is refreshed regularly. The refresh requests will
- * generate #nua_r_subscribe events.
- *
- * @param nh              Pointer to operation handle
- * @param tag, value, ... List of tagged parameters
- *
- * @return 
- *    nothing
- *
- * @par Related Tags:
- *    NUTAG_URL()
- *    Tags in <sip_tag.h>
- *
- * @par Events:
- *    #nua_r_subscribe \n
- *    #nua_i_notify
- */
+/* Documented with nua_stack_subscribe() */
 void nua_subscribe(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
 {
   NUA_SIGNAL(nh, nua_r_subscribe, tag, value);
 }
 
-/** Unsubscribe an event. 
- *
- * Unsubscribe an active or pending subscription with SUBSCRIBE request 
- * containing Expires: header with value 0. The dialog associated with 
- * subscription will be destroyed if there is no other subscriptions or 
- * call using this dialog.
- *
- * @param nh              Pointer to operation handle
- * @param tag, value, ... List of tagged parameters
- *
- * @return 
- *    nothing
- *
- * @par Related Tags:
- *    #SIPTAG_EVENT \n
- *    Tags in <sip_tag.h> except #SIPTAG_EXPIRES or #SIPTAG_EXPIRES_STR
- *
- * @par Events:
- *    #nua_r_unsubscribe 
- */
+/* Documented with nua_stack_subscribe() */
 void nua_unsubscribe(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
 {
   NUA_SIGNAL(nh, nua_r_unsubscribe, tag, value);
@@ -788,10 +755,10 @@ void nua_notify(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
  *
  * @par Related Tags:
  *    NUTAG_URL() \n
- *    #SIPTAG_EVENT or #SIPTAG_EVENT_STR \n
- *    #SIPTAG_CONTENT_TYPE or #SIPTAG_CONTENT_TYPE_STR \n
- *    #SIPTAG_PAYLOAD or #SIPTAG_PAYLOAD_STR \n
- *    #SIPTAG_ACCEPT or #SIPTAG_ACCEPT_STR \n
+ *    SIPTAG_EVENT() or SIPTAG_EVENT_STR() \n
+ *    SIPTAG_CONTENT_TYPE() or SIPTAG_CONTENT_TYPE_STR() \n
+ *    SIPTAG_PAYLOAD() or SIPTAG_PAYLOAD_STR() \n
+ *    SIPTAG_ACCEPT() or SIPTAG_ACCEPT_STR() \n
  *
  * @par Events:
  *    #nua_r_notify
@@ -813,10 +780,10 @@ void nua_notifier(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
  *    nothing
  *
  * @par Related Tags:
- *    #SIPTAG_EVENT \n
- *    #SIPTAG_CONTENT_TYPE \n
- *    #SIPTAG_PAYLOAD \n
- *    #NEATAG_REASON
+ *    SIPTAG_EVENT() \n
+ *    SIPTAG_CONTENT_TYPE() \n
+ *    SIPTAG_PAYLOAD() \n
+ *    NEATAG_REASON()
  *
  * @par Events:
  *    #nua_r_terminate
@@ -828,31 +795,7 @@ void nua_terminate(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
   NUA_SIGNAL(nh, nua_r_terminate, tag, value);
 }
 
-/** Transfer a call. 
- * 
- * Send a REFER request asking the recipient to transfer the call. The REFER
- * request also establishes a subscription to the "refer" event. The "refer"
- * event will have an "id" parameter, which has the value of CSeq number in
- * the REFER request. After initiating the REFER request, the nua engine
- * sends application a nua_r_refer event with status 100 and tag
- * SIPTAG_EVENT() containing a matching event header.
- *
- * @param nh              Pointer to operation handle
- * @param tag, value, ... List of tagged parameters
- *
- * @return 
- *    nothing
- *
- * @par Related Tags:
- *    NUTAG_URL() \n
- *    Tags in <sip_tag.h>
- *
- * @par Events:
- *    #nua_r_refer \n
- *    #nua_i_notify
- *
- * @sa @RFC3515
- */
+/* Documented with nua_stack_refer() */
 void nua_refer(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
 {
   NUA_SIGNAL(nh, nua_r_refer, tag, value);
@@ -947,34 +890,8 @@ void nua_redirect(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
   NUA_SIGNAL(nh, nua_r_redirect, tag, value);
 }
 
-/** Respond with given status. 
- *
- * Currently, only request application is let to respond is INVITE.
- *
- * @param nh              Pointer to operation handle
- * @param status          SIP response status (see RFCs of SIP)
- * @param phrase          free text (default response phrase used if NULL)
- * @param tag, value, ... List of tagged parameters
- *
- * @return 
- *    nothing
- *
- * @par Related Tags:
- *    NUTAG_EARLY_ANSWER() \n
- *    #SOATAG_ADDRESS \n
- *    #SOATAG_AF \n
- *    #SOATAG_HOLD \n
- *    Tags in <sip_tag.h>.
- *
- * @par Events:
- *    #nua_i_state \n
- *    #nua_i_media_error \n
- *    #nua_i_error \n
- *    #nua_i_active \n
- *    #nua_i_terminated \n
- *
- * @sa #nua_i_invite, 
- */
+/* Documented with nua_stack_respond() */
+
 void nua_respond(nua_handle_t *nh,
 		 int status, char const *phrase,
 		 tag_type_t tag, tag_value_t value,
@@ -1211,7 +1128,7 @@ static int nua_stack_handle_make_replaces_call(void *arg)
  * @since New in @VERSION_1_12_4.
  *
  * @sa nua_handle_by_replaces(), @Replaces, @RFC3891, nua_refer(),
- * nua_i_refer(), @ReferTo, nta_leg_make_replaces()
+ * #nua_i_refer, @ReferTo, nta_leg_make_replaces()
  */
 sip_replaces_t *nua_handle_make_replaces(nua_handle_t *nh, 
 					 su_home_t *home,
@@ -1253,7 +1170,7 @@ static int nua_stack_handle_by_replaces_call(void *arg)
  * done with handle.
  *
  * @sa nua_handle_make_replaces(), @Replaces, @RFC3891, nua_refer(),
- * nua_i_refer(), @ReferTo, nta_leg_by_replaces()
+ * #nua_i_refer, @ReferTo, nta_leg_by_replaces()
  */
 nua_handle_t *nua_handle_by_replaces(nua_t *nua, sip_replaces_t const *r)
 {

libsofia-sip-ua/nua/nua.docs

@@ -2044,7 +2044,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
  * @param nh     operation handle associated with the original call
  * @param hmagic operation magic associated with the original call
  * @param sip    200 series response to INVITE
- * @param tags   #NUTAG_HANDLE of the new forked call
+ * @param tags   NUTAG_HANDLE() of the new forked call
  */
 
 /** @var nua_event_e::nua_i_media_error
@@ -2099,16 +2099,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
  * @since Experimental in @VERSION_1_12_2.
  */
 
-/** @var nua_event_e::nua_i_notify
- *
- * Incoming event.
- *
- * @param nh     operation handle associated with the call
- * @param hmagic operation magic associated with the call
- * @param status statuscode of response sent automatically by stack
- * @param sip    incoming NOTIFY request
- * @param tags   #NUTAG_SUBSTATE indicating the subscription state
- */
+/* nua_i_notify is documented with nua_stack_process_notify() */
 
 /** @var nua_event_e::nua_i_options
  *
@@ -2192,8 +2183,8 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
  * @param nh     operation handle associated with the call
  * @param hmagic operation magic associated with the call
  * @param sip    NULL
- * @param tags   #SIPTAG_EVENT \n
- *               #SIPTAG_CONTENT_TYPE
+ * @param tags   SIPTAG_EVENT() \n
+ *               SIPTAG_CONTENT_TYPE()
  */
 
 /* nua_r_notify is documented with process_response_to_notify() */
@@ -2209,17 +2200,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
  * @param tags   empty
  */
 
-/** @var nua_event_e::nua_r_refer
- *
- * Answer to outgoing REFER.
- *
- * @param nh     operation handle associated with the call
- * @param hmagic operation magic associated with the call
- * @param sip    response to REFER request or NULL upon an error
- *               (error code and message are in status an phrase parameters)
- * @param tags   #NUTAG_REFER_EVENT \n
- *               #NUTAG_SUBSTATE
- */
+/* nua_r_refer is documented with process_response_to_refer() */
 
 /** @var nua_event_e::nua_r_shutdown
  *
@@ -2237,19 +2218,7 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
  * @param tags   empty
  */
 
-/** @var nua_event_e::nua_r_subscribe
- *
- * Answer to outgoing SUBSCRIBE.
- *
- * The SUBSCRIBE may be sent explicitly by nua_subscribe() or
- * implicitly by NUA state machine.
- *
- * @param nh     operation handle associated with the call
- * @param hmagic operation magic associated with the call
- * @param sip    response to SUBSCRIBE request or NULL upon an error
- *               (error code and message are in status an phrase parameters)
- * @param tags   #NUTAG_SUBSTATE
- */
+/* nua_r_subscribe is documented with process_response_to_subscribe() */
 
 /** @var nua_event_e::nua_r_terminate
  *
@@ -2261,13 +2230,4 @@ NUTAG_AUTOANSWER(0) on B side, NUTAG_AUTOACK(0) on A side.
  * @param tags   empty
  */
 
-/** @var nua_event_e::nua_r_unsubscribe
- *
- * Answer to outgoing un-SUBSCRIBE.
- *
- * @param nh     operation handle associated with the call
- * @param hmagic operation magic associated with the call
- * @param sip    response to SUBSCRIBE request or NULL upon an error
- *               (error code and message are in status an phrase parameters)
- * @param tags   empty
- */
+/* nua_r_unsubscribe is documented with process_response_to_subscribe() */

libsofia-sip-ua/nua/nua_notifier.c

@@ -313,8 +313,9 @@ static int nua_stack_notify2(nua_t *, nua_handle_t *, nua_event_t,
  *    nothing
  *
  * @par Related Tags:
+ *    NUTAG_SUBSTATE() \n
+ *    Tags of nua_set_hparams() \n
  *    Tags in <sip_tag.h>
- *    NUTAG_SUBSTATE()
  *
  * @par Events:
  *    #nua_r_notify

libsofia-sip-ua/nua/nua_params.c

@@ -270,8 +270,9 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
  *     nothing
  *
  * @par Related tags:
- *   NUTAG_ALLOW() \n
- *   NUTAG_ALLOW_EVENTS() \n
+ *   NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR() \n
+ *   NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and 
+ *                         SIPTAG_ALLOW_EVENTS_STR() \n
  *   NUTAG_AUTOACK() \n
  *   NUTAG_AUTOALERT() \n
  *   NUTAG_AUTOANSWER() \n
@@ -313,27 +314,16 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
  *   NUTAG_SMIME_SIGNATURE() \n
  *   NUTAG_SOA_NAME() \n
  *   NUTAG_SUBSTATE() \n
- *   NUTAG_SUPPORTED() \n
+ *   NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR() \n
  *   NUTAG_UPDATE_REFRESH() \n
- *   NUTAG_USER_AGENT() \n
- *   SIPTAG_ALLOW() \n
- *   SIPTAG_ALLOW_STR() \n
- *   SIPTAG_ALLOW_EVENTS() \n
- *   SIPTAG_ALLOW_EVENTS_STR() \n
- *   SIPTAG_FROM() \n
- *   SIPTAG_FROM_STR() \n
- *   SIPTAG_ORGANIZATION() \n
- *   SIPTAG_ORGANIZATION_STR() \n
- *   SIPTAG_SUPPORTED() \n
- *   SIPTAG_SUPPORTED_STR() \n
- *   SIPTAG_USER_AGENT() \n
- *   SIPTAG_USER_AGENT_STR() \n
+ *   NUTAG_USER_AGENT(), SIPTAG_USER_AGENT() and SIPTAG_USER_AGENT_STR() \n
+ *   SIPTAG_ORGANIZATION() and SIPTAG_ORGANIZATION_STR() \n
  *
  * nua_set_params() also accepts any soa tags, defined in
  * <sofia-sip/soa_tag.h>, and nta tags, defined in <sofia-sip/nta_tag.h>.
  * 
  * @par Events:
- *     nua_r_set_params
+ *     #nua_r_set_params
  *
  * @par SIP Header as NUA Parameters
  * The @nua parameters include SIP headers @Allow, @Supported, @Organization,
@@ -397,8 +387,9 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
  *     nothing
  *
  * @par Tags Used to Set Handle-Specific Parameters:
- *   NUTAG_ALLOW() \n
- *   NUTAG_ALLOW_EVENTS() \n
+ *   NUTAG_ALLOW(), SIPTAG_ALLOW(), and SIPTAG_ALLOW_STR() \n
+ *   NUTAG_ALLOW_EVENTS(), SIPTAG_ALLOW_EVENTS(), and 
+ *                         SIPTAG_ALLOW_EVENTS_STR() \n
  *   NUTAG_AUTOACK() \n
  *   NUTAG_AUTOALERT() \n
  *   NUTAG_AUTOANSWER() \n
@@ -432,19 +423,10 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
  *   NUTAG_SESSION_TIMER() \n
  *   NUTAG_SOA_NAME() \n
  *   NUTAG_SUBSTATE() \n
- *   NUTAG_SUPPORTED() \n
+ *   NUTAG_SUPPORTED(), SIPTAG_SUPPORTED(), and SIPTAG_SUPPORTED_STR() \n
  *   NUTAG_UPDATE_REFRESH() \n
- *   NUTAG_USER_AGENT() \n
- *   SIPTAG_ALLOW() \n
- *   SIPTAG_ALLOW_STR() \n
- *   SIPTAG_ALLOW_EVENTS() \n
- *   SIPTAG_ALLOW_EVENTS_STR() \n
- *   SIPTAG_ORGANIZATION() \n
- *   SIPTAG_ORGANIZATION_STR() \n
- *   SIPTAG_SUPPORTED() \n
- *   SIPTAG_SUPPORTED_STR() \n
- *   SIPTAG_USER_AGENT() \n
- *   SIPTAG_USER_AGENT_STR() \n
+ *   NUTAG_USER_AGENT(), SIPTAG_USER_AGENT() and SIPTAG_USER_AGENT_STR() \n
+ *   SIPTAG_ORGANIZATION() and SIPTAG_ORGANIZATION_STR() \n
  * Any soa tags are also considered as handle-specific parameters. They are
  * defined in <sofia-sip/soa_tag.h>.
  *
@@ -452,7 +434,7 @@ int nua_stack_init_instance(nua_handle_t *nh, tagi_t const *tags)
  * NUTAG_DETECT_NETWORK_UPDATES(), NUTAG_SMIME_* tags, and all NTA tags.
  * 
  * @par Events:
- *     nua_r_set_params
+ *     #nua_r_set_params
  */
 
 int nua_stack_set_params(nua_t *nua, nua_handle_t *nh, nua_event_t e,
@@ -1285,11 +1267,11 @@ int nua_stack_set_smime_params(nua_t *nua, tagi_t const *tags)
 
 /**@fn void nua_get_hparams(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...)
  * 
- * Get values of handle-specific parameters in nua_r_get_params event.
+ * Get values of handle-specific parameters in #nua_r_get_params event.
  *
  * Application will specify either expilicit list of tags it is interested
  * in, or a filter (at the moment, TAG_ANY()). The values are returned as a
- * list of tags in the nua_r_get_params event.
+ * list of tags in the #nua_r_get_params event.
  *
  * @param nh              Pointer to operation handle
  * @param tag, value, ... List of tagged parameters

libsofia-sip-ua/nua/nua_publish.c

@@ -145,6 +145,7 @@ static int process_response_to_publish(nua_handle_t *nh,
  *
  * @par Related Tags:
  *    NUTAG_URL() \n
+ *    Tags of nua_set_hparams() \n
  *    Tags in <sip_tag.h>
  *
  * @par Events:
@@ -182,6 +183,7 @@ void nua_unpublish(nua_handle_t *nh, tag_type_t tag, tag_value_t value, ...);
  *
  * @par Related Tags:
  *    NUTAG_URL() \n
+ *    Tags of nua_set_hparams() \n
  *    Tags in <sip_tag.h>
  *
  * @par Events:

libsofia-sip-ua/nua/nua_register.c

@@ -414,7 +414,7 @@ outbound_owner_vtable nua_stack_outbound_callbacks = {
  * validate the registration and initiate the keepalive mechanism, too. The
  * user-agent validates the registration by sending a OPTIONS requests to
  * itself. If there is an error, nua_register() will indicate that to the
- * application using nua_i_outbound event, and start unregistration
+ * application using #nua_i_outbound event, and start unregistration
  * procedure (unless that has been explicitly disabled).
  *
  * You can disable validation by inserting "no-validate" into

libsofia-sip-ua/nua/nua_session.c

@@ -351,30 +351,9 @@ int respond_with_retry_after(nua_handle_t *nh, nta_incoming_t *irq,
  *    nothing
  *
  * @par Related Tags:
- *    NUTAG_URL(),
- *    NUTAG_NOTIFY_REFER(), 
- *    NUTAG_ALLOW(),
- *    NUTAG_AUTOACK(),
- *    NUTAG_AUTOALERT(),
- *    NUTAG_AUTOANSWER(),
- *    NUTAG_CALLEE_CAPS(),
- *    NUTAG_EARLY_MEDIA(),
- *    NUTAG_ENABLEINVITE(),
- *    NUTAG_ENABLEMESSAGE(),
- *    NUTAG_ENABLEMESSENGER(),
- *    NUTAG_INVITE_TIMER(),
- *    NUTAG_MEDIA_ENABLE(),
- *    NUTAG_MIN_SE(),
- *    NUTAG_ONLY183_100REL(),
- *    NUTAG_REFER_EXPIRES(),
- *    NUTAG_RETRY_COUNT(),
- *    NUTAG_SERVICE_ROUTE_ENABLE(),
- *    NUTAG_SESSION_REFRESHER(),
- *    NUTAG_SESSION_TIMER(),
- *    NUTAG_SOA_NAME(),
- *    NUTAG_SUPPORTED(),
- *    NUTAG_UPDATE_REFRESH(),
- *    NUTAG_USER_AGENT() \n
+ *    NUTAG_URL() \n
+ *    Tags of nua_set_hparams() \n
+ *    NUTAG_INCLUDE_EXTRA_SDP() \n
  *    SOATAG_HOLD(), SOATAG_AF(), SOATAG_ADDRESS(),
  *    SOATAG_RTP_SELECT(), SOATAG_RTP_SORT(), SOATAG_RTP_MISMATCH(), 
  *    SOATAG_AUDIO_AUX(), \n
@@ -3222,7 +3201,7 @@ static void signal_call_state_change(nua_handle_t *nh,
  * NUTAG_ANSWER_RECV(). SOATAG_ACTIVE_AUDIO() and SOATAG_ACTIVE_VIDEO() are
  * informational tags used to indicate what is the status of these media.
  *
- * Note that nua_event_e::nua_i_state also covers call establisment events
+ * Note that #nua_i_state also covers call establisment events
  * (#nua_i_active) and termination (#nua_i_terminated).
  *
  * @param status Protocol status code. \n

libsofia-sip-ua/nua/nua_stack.c

@@ -1950,7 +1950,57 @@ int nua_default_respond(nua_server_request_t *sr,
   
   return sr->sr_status >= 200 ? sr->sr_status : 0;
 }
-			   
+
+/** Respond to an request with given status. 
+ *
+ * When nua protocol engine receives an incoming SIP request, it can either
+ * respond to the request automatically or let it up to application to
+ * respond to the request. The automatic answer is sent if the request fails
+ * because of method, SIP extension or, in some times, MIME content
+ * negotiation fails.
+ *
+ * When responding to an incoming INVITE request, the nua_respond() can be
+ * called without NUTAG_WITH() (or NUTAG_WITH_CURRENT() or
+ * NUTAG_WITH_SAVED()). Otherwise, NUTAG_WITH() will contain an indication
+ * of the request being responded.
+ *
+ * In order to simplify the application, most requests are responded
+ * automatically. The set of requests always responded by the stack include
+ * BYE, CANCEL and NOTIFY. The application can add methods that it likes to
+ * handle by itself with NUTAG_APPL_METHOD(). The default set of
+ * NUTAG_APPL_METHOD() include INVITE, PUBLISH, REGISTER and SUBSCRIBE. Note
+ * that unless the method is also added to the set of allowed methods with
+ * NUTAG_ALLOW(), the stack will respond to the incoming methods with <i>405
+ * Not Allowed</i>.
+ *
+ * Note that certain methods are rejected outside a SIP session (created
+ * with INVITE transaction). They include BYE, UPDATE, PRACK and INFO.
+ *
+ * @param nh              Pointer to operation handle
+ * @param status          SIP response status (see RFCs of SIP)
+ * @param phrase          free text (default response phrase used if NULL)
+ * @param tag, value, ... List of tagged parameters
+ *
+ * @return 
+ *    nothing
+ *
+ * @par Related Tags:
+ *    NUTAG_WITH(), NUTAG_WITH_CURRENT(), NUTAG_WITH_SAVED() \n
+ *    NUTAG_EARLY_ANSWER() \n
+ *    SOATAG_ADDRESS() \n
+ *    SOATAG_AF() \n
+ *    SOATAG_HOLD() \n
+ *    Tags in <sip_tag.h>.
+ *
+ * @par Events:
+ *    #nua_i_state \n
+ *    #nua_i_media_error \n
+ *    #nua_i_error \n
+ *    #nua_i_active \n
+ *    #nua_i_terminated \n
+ *
+ * @sa #nua_i_invite, #nua_i_register, #nua_i_subscribe, #nua_i_publish
+ */
 void
 nua_stack_respond(nua_t *nua, nua_handle_t *nh,
 		  int status, char const *phrase, tagi_t const *tags)

libsofia-sip-ua/nua/nua_subnotref.c

@@ -118,10 +118,58 @@ void nua_subscribe_usage_remove(nua_handle_t *nh,
 /* ====================================================================== */
 /* SUBSCRIBE */
 
+/** Subscribe to a SIP event. 
+ *
+ * Subscribe a SIP event using the SIP SUBSCRIBE request. If the 
+ * SUBSCRBE is successful a subscription state is established and 
+ * the subscription is refreshed regularly. The refresh requests will
+ * generate #nua_r_subscribe events.
+ *
+ * @param nh              Pointer to operation handle
+ * @param tag, value, ... List of tagged parameters
+ *
+ * @return 
+ *    nothing
+ *
+ * @par Related Tags:
+ *    NUTAG_URL()
+ *    Tags in <sip_tag.h>
+ *
+ * @par Events:
+ *    #nua_r_subscribe \n
+ *    #nua_i_notify
+ *
+ * @sa NUTAG_SUBSTATE(), @RFC3265
+ */
+
+/** Unsubscribe an event. 
+ *
+ * Unsubscribe an active or pending subscription with SUBSCRIBE request 
+ * containing Expires: header with value 0. The dialog associated with 
+ * subscription will be destroyed if there is no other subscriptions or 
+ * call using this dialog.
+ *
+ * @param nh              Pointer to operation handle
+ * @param tag, value, ... List of tagged parameters
+ *
+ * @return 
+ *    nothing
+ *
+ * @par Related Tags:
+ *    SIPTAG_EVENT() or SIPTAG_EVENT_STR() \n
+ *    Tags in <sip_tag.h> except SIPTAG_EXPIRES() or SIPTAG_EXPIRES_STR()
+ *
+ * @par Events:
+ *    #nua_r_unsubscribe 
+ *
+ * @sa NUTAG_SUBSTATE(), @RFC3265
+ */
+
 static int process_response_to_subscribe(nua_handle_t *nh,
 					 nta_outgoing_t *orq,
 					 sip_t const *sip);
 
+
 int
 nua_stack_subscribe(nua_t *nua, nua_handle_t *nh, nua_event_t e,
 		    tagi_t const *tags)
@@ -247,6 +295,35 @@ static void restart_subscribe(nua_handle_t *nh, tagi_t *tags)
   nua_creq_restart(nh, nh->nh_cr, process_response_to_subscribe, tags);
 }
 
+/** @var nua_event_e::nua_r_subscribe
+ *
+ * Response to an outgoing SUBSCRIBE.
+ *
+ * The SUBSCRIBE request may have been sent explicitly by nua_subscribe() or
+ * implicitly by NUA state machine.
+ *
+ * @param nh     operation handle associated with the call
+ * @param hmagic operation magic associated with the call
+ * @param sip    response to SUBSCRIBE request or NULL upon an error
+ *               (error code and message are in status an phrase parameters)