Skip to content
GitLab
Menu
Projects
Groups
Snippets
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
BC
public
external
sofia-sip
Commits
f36532e8
Commit
f36532e8
authored
Nov 15, 2006
by
Pekka Pessi
Browse files
nua: updated documentation.
darcs-hash:20061115171720-65a35-3a6abb1753922d7ffb6f41ee59aa19cdae9df65a.gz
parent
f754be5e
Changes
8
Hide whitespace changes
Inline
Side-by-side
Showing
8 changed files
with
148 additions
and
48 deletions
+148
-48
libsofia-sip-ua/nua/Doxyfile
libsofia-sip-ua/nua/Doxyfile
+1
-1
libsofia-sip-ua/nua/nua.docs
libsofia-sip-ua/nua/nua.docs
+24
-14
libsofia-sip-ua/nua/nua_message.c
libsofia-sip-ua/nua/nua_message.c
+1
-1
libsofia-sip-ua/nua/nua_session.c
libsofia-sip-ua/nua/nua_session.c
+21
-16
libsofia-sip-ua/nua/sofia-sip/nua.h
libsofia-sip-ua/nua/sofia-sip/nua.h
+11
-9
libsofia-sip-ua/nua/sofia-sip/nua_tag.h
libsofia-sip-ua/nua/sofia-sip/nua_tag.h
+88
-5
libsofia-sip-ua/nua/test_init.c
libsofia-sip-ua/nua/test_init.c
+1
-1
libsofia-sip-ua/nua/test_refer.c
libsofia-sip-ua/nua/test_refer.c
+1
-1
No files found.
libsofia-sip-ua/nua/Doxyfile
View file @
f36532e8
...
...
@@ -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
View file @
f36532e8
...
...
@@ -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_
activ
e(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_
stat
e(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_
activ
e() function is called by the callback function when call has
The app_i_
stat
e() 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
View file @
f36532e8
...
...
@@ -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
View file @
f36532e8
...
...
@@ -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
View file @
f36532e8
...
...
@@ -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
View file @
f36532e8
...
...
@@ -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
View file @
f36532e8
...
...
@@ -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
View file @
f36532e8
...
...
@@ -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
)
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment