Skip to content

S
sofia-sip
Commit abdfe2c0 authored by Pekka Pessi's avatar Pekka Pessi
Browse files
Options

soa: updated documentation. 

darcs-hash:20061115171817-65a35-14d76f87c7dee45b2f8ab160e4c1854d9af64ebc.gz
parent f36532e8
Hide whitespace changes
Inline Side-by-side
Showing with 154 additions and 2 deletions
libsofia-sip-ua/soa/soa.c
View file @ abdfe2c0
......@@ -266,6 +266,7 @@ soa_session_t *soa_create(char const *name,
return ss;
}
/** Create a copy of a @soa session object. */
soa_session_t *soa_clone(soa_session_t *parent_ss,
su_root_t *root,
soa_magic_t *magic)
......@@ -808,10 +809,19 @@ int soa_get_warning(soa_session_t *ss, char const **return_text)
}
/** Return SDP description of capabilities.
*
* @param ss pointer to @soa session
* @param return_sdp return value for capability SDP structure
* @param return_sdp_str return value for capability SDP string
* @param return_len return value for length of capability SDP string
*
* @retval 0 if there is no description to return
* @retval 1 if description is returned
* @retval -1 upon an error
*
* @sa @RFC3261 section 11, soa_set_capability_sdp(),
* SOATAG_CAPS_SDP(), SOATAG_CAPS_SDP_STR(),
* nua_options(), #nua_i_options()
*/
int soa_get_capability_sdp(soa_session_t const *ss,
sdp_session_t const **return_sdp,
......@@ -844,6 +854,25 @@ int soa_get_capability_sdp(soa_session_t const *ss,
}
/** Set capability SDP.
*
* Capability SDP is used instead of user SDP when generating OPTIONS
* responses describing media capabilities.
*
* @param ss pointer to @soa session
* @param sdp pointer to SDP session structure
* @param str pointer to string containing SDP session description
* @param len lenght of string @a str
*
* @retval 1 when SDP is stored and it differs from previously stored
* @retval 0 when SDP is identical to previously stored one (and user version
* returned by soa_get_user_version() is not incremented)
* @retval -1 upon an error
*
* @sa @RFC3261 section 11, soa_get_capability_sdp(),
* SOATAG_CAPS_SDP(), SOATAG_CAPS_SDP_STR(),
* nua_options(), #nua_i_options()
*/
int soa_set_capability_sdp(soa_session_t *ss,
sdp_session_t const *sdp,
char const *str, issize_t len)
......@@ -912,7 +941,7 @@ soa_base_set_capability_sdp(soa_session_t *ss,
* @param return_sdp SDP session structure return value
* @param return_sdp_str return value for pointer to string
* containing the user SDP session description
* @param return_len return value for user SDP session descrioption string
* @param return_len return value for user SDP session description string
* length
*
* Any of the parameters @a return_sdp, @a return_sdp_str, or @a return_len
......@@ -1758,46 +1787,58 @@ void soa_base_terminate(soa_session_t *ss, char const *option)
soa_set_activity(ss, NULL, 1);
}
/** Return true if the SDP Offer/Answer negotation is complete.
*
* The soa_init_offer_answer() clears the completion flag.
*/
int soa_is_complete(soa_session_t const *ss)
{
return ss && ss->ss_complete;
}
/** Return true if audio has been activated. */
int soa_is_audio_active(soa_session_t const *ss)
{
return ss ? ss->ss_local_activity->ma_audio : SOA_ACTIVE_DISABLED;
}
/** Return true if video has been activated. */
int soa_is_video_active(soa_session_t const *ss)
{
return ss ? ss->ss_local_activity->ma_video : SOA_ACTIVE_DISABLED;
}
/** Return true if image sharing has been activated. */
int soa_is_image_active(soa_session_t const *ss)
{
return ss ? ss->ss_local_activity->ma_image : SOA_ACTIVE_DISABLED;
}
/** Return true if messaging session has been activated. */
int soa_is_chat_active(soa_session_t const *ss)
{
return ss ? ss->ss_local_activity->ma_chat : SOA_ACTIVE_DISABLED;
}
/** Return true if remote audio is active (not on hold). */
int soa_is_remote_audio_active(soa_session_t const *ss)
{
return ss ? ss->ss_remote_activity->ma_audio : SOA_ACTIVE_DISABLED;
}
/** Return true if remote video is active (not on hold). */
int soa_is_remote_video_active(soa_session_t const *ss)
{
return ss ? ss->ss_remote_activity->ma_video : SOA_ACTIVE_DISABLED;
}
/** Return true if image sharing is active (not on hold). */
int soa_is_remote_image_active(soa_session_t const *ss)
{
return ss ? ss->ss_remote_activity->ma_image : SOA_ACTIVE_DISABLED;
}
/** Return true if chat session is active (not on hold). */
int soa_is_remote_chat_active(soa_session_t const *ss)
{
return ss ? ss->ss_remote_activity->ma_chat : SOA_ACTIVE_DISABLED;
......
libsofia-sip-ua/soa/soa.docs
View file @ abdfe2c0
......@@ -771,4 +771,115 @@ The session upgraded is rejected.
</pre>
*/
\ No newline at end of file
*/
/** @typedef struct soa_session soa_session_t;
@brief "soa" session object.
The @soa session object is responsible for
@ref soa_with_sip "SDP offer/answer negotiation"
defined in @RFC3264. The session object is used to
store the SDP template from user, remote SDP received from the network and
the negotiation result, local SDP.
@par Functions used to create, copy and destroy @soa session objects:
@code
soa_session_t *soa_create(char const *name, su_root_t *, soa_magic_t *);
soa_session_t *soa_clone(soa_session_t *, su_root_t *, soa_magic_t *);
void soa_destroy(soa_session_t *);
@endcode
@par Functions used to set and get parameters for "soa" session objects:
@code
int soa_set_params(soa_session_t *ss,
tag_type_t tag, tag_value_t value, ...);
int soa_get_params(soa_session_t const *ss,
tag_type_t tag, tag_value_t value, ...);
tagi_t *soa_get_paramlist(soa_session_t const *ss,
tag_type_t tag, tag_value_t value, ...);
@endcode
@par Functions used to obtain status information from "soa" session objects:
@code
int soa_error_as_sip_response(soa_session_t *soa,
char const **return_phrase);
char const *soa_error_as_sip_reason(soa_session_t *soa);
int soa_get_warning(soa_session_t *ss, char const **return_phrase);
@endcode
@par Functions Used to Store and Retrieve SDP Descriptions:
@code
int soa_set_capability_sdp(soa_session_t *ss,
struct sdp_session_s const *sdp,
char const *str, issize_t len);
int soa_get_capability_sdp(soa_session_t const *ss,
struct sdp_session_s const **return_sdp,
char const **return_sdp_str,
isize_t *return_len);
int soa_set_remote_sdp(soa_session_t *ss,
struct sdp_session_s const *sdp,
char const *str, issize_t len);
int soa_get_remote_sdp(soa_session_t const *ss,
struct sdp_session_s const **return_sdp,
char const **return_sdp_str,
isize_t *return_len);
int soa_clear_remote_sdp(soa_session_t *ss);
int soa_get_remote_version(soa_session_t const *ss);
int soa_set_user_sdp(soa_session_t *ss,
struct sdp_session_s const *sdp,
char const *str, issize_t len);
int soa_get_user_sdp(soa_session_t const *ss,
struct sdp_session_s const **return_sdp,
char const **return_sdp_str,
isize_t *return_len);
int soa_get_user_version(soa_session_t const *ss);
int soa_get_local_sdp(soa_session_t const *ss,
struct sdp_session_s const **return_sdp,
char const **return_sdp_str,
isize_t *return_len);
@endcode
@par Functions for Executing Offer/Answer Negotiation Steps:
@code
int soa_init_offer_answer(soa_session_t *ss);
int soa_generate_offer(soa_session_t *, int always, soa_callback_f *);
int soa_generate_answer(soa_session_t *, soa_callback_f *);
int soa_process_answer(soa_session_t *, soa_callback_f *);
int soa_process_reject(soa_session_t *, soa_callback_f *);
int soa_is_complete(soa_session_t const *ss);
@endcode
@par Functions for Signaling Completion of Session Signaling:
@code
int soa_activate(soa_session_t *, char const *option);
int soa_deactivate(soa_session_t *, char const *option);
void soa_terminate(soa_session_t *, char const *option);
@endcode
@par Functions for Checking Activated Media:
@code
int soa_is_audio_active(soa_session_t const *ss);
int soa_is_video_active(soa_session_t const *ss);
int soa_is_remote_audio_active(soa_session_t const *ss);
int soa_is_remote_video_active(soa_session_t const *ss);
@endcode
*/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment