Loading...
Searching...
No Matches
soa.h File Reference

SDP Offer/Answer (RFC 3264) Interface. More...

`#include <sofia-sip/su_wait.h>`
`#include <sofia-sip/su_tag.h>`
Include dependency graph for soa.h:

Go to the source code of this file.

## Macros

#define | SOA_H
| Defined when <sofia-sip/soa.h> has been included.

## Typedefs

typedef struct soa_session | soa_session_t
| "soa" session object.

## Functions

soa_session_t * | soa_create (char const *name, su_root_t *, soa_magic_t *)
| Create a soa session.
soa_session_t * | soa_clone (soa_session_t *, su_root_t *, soa_magic_t *)
| Create a copy of a soa session object.
void | soa_destroy (soa_session_t *)
| Destroy a session.
int | soa_set_params (soa_session_t *ss, tag_type_t tag, tag_value_t value,...)
| Set parameters.
int | soa_get_params (soa_session_t const *ss, tag_type_t tag, tag_value_t value,...)
| Get tagged parameters.
tagi_t * | soa_get_paramlist (soa_session_t const *ss, tag_type_t tag, tag_value_t value,...)
| Return a list of parameters.
int | soa_error_as_sip_response (soa_session_t *soa, char const **return_phrase)
| Convert soa error to a SIP response code and phrase.
char const * | soa_error_as_sip_reason (soa_session_t *soa)
| Convert soa error to a SIP Reason header.
int | soa_get_warning (soa_session_t *ss, char const **return_phrase)
| Return SIP Warning code and text.
int | soa_set_capability_sdp (soa_session_t *ss, struct sdp_session_s const *sdp, char const *str, issize_t len)
| Set capability SDP.
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)
| Return SDP description of capabilities.
int | soa_set_remote_sdp (soa_session_t *ss, struct sdp_session_s const *sdp, char const *str, issize_t len)
| Set remote SDP (offer or answer).
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)
| Return remote SDP description of the session.
int | soa_clear_remote_sdp (soa_session_t *ss)
| Clear remote SDP.
int | soa_get_remote_version (soa_session_t const *ss)
| Returns the version number of remote session description.
int | soa_set_user_sdp (soa_session_t *ss, struct sdp_session_s const *sdp, char const *str, issize_t len)
| Store user SDP to soa session.
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)
| Return user SDP description.
int | soa_get_user_version (soa_session_t const *ss)
| Returns the version number of user session description.
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)
| Get local SDP.
char ** | soa_media_features (soa_session_t *ss, int live, su_home_t *home)
| Return list of media fetures.
int | soa_generate_offer (soa_session_t *, int always, soa_callback_f *)
| Generate offer.
int | soa_generate_answer (soa_session_t *, soa_callback_f *)
| Process offer, generate answer.
int | soa_process_answer (soa_session_t *, soa_callback_f *)
| Complete offer-answer after receiving answer.
int | soa_process_reject (soa_session_t *, soa_callback_f *)
| Process rejection of offer.
int | soa_activate (soa_session_t *, char const *option)
| Activate session.
int | soa_deactivate (soa_session_t *, char const *option)
| Deactivate session.
void | soa_terminate (soa_session_t *, char const *option)
| Terminate session.
int | soa_is_complete (soa_session_t const *ss)
| Return true if the SDP Offer/Answer negotation is complete.
int | soa_init_offer_answer (soa_session_t *ss)
| Initialize the offer/answer state machine.
int | soa_is_audio_active (soa_session_t const *ss)
| Return true if audio has been activated.
int | soa_is_video_active (soa_session_t const *ss)
| Return true if video has been activated.
int | soa_is_image_active (soa_session_t const *ss)
| Return true if image sharing has been activated.
int | soa_is_chat_active (soa_session_t const *ss)
| Return true if messaging session has been activated.
int | soa_is_remote_audio_active (soa_session_t const *ss)
| Return true if remote audio is active (not on hold).
int | soa_is_remote_video_active (soa_session_t const *ss)
| Return true if remote video is active (not on hold).
int | soa_is_remote_image_active (soa_session_t const *ss)
| Return true if image sharing is active (not on hold).
int | soa_is_remote_chat_active (soa_session_t const *ss)
| Return true if chat session is active (not on hold).
int | soa_is_delayed_offer (soa_session_t const *ss)
| Return true if delayed offer has been activated.
int | soa_tag_filter (tagi_t const *f, tagi_t const *t)
| Filter soa tags.

## Detailed Description

SDP Offer/Answer (RFC 3264) Interface.

Author
  Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com
  Kai Vehmanen Kai.V.nosp@m.ehma.nosp@m.nen@n.nosp@m.okia.nosp@m..com

Date
  Created: Fri Jul 15 15:43:53 EEST 2005 ppessi

## Typedef Documentation

## soa_session_t

typedef struct soa_session soa_session_t

"soa" session object.

The soa session object is responsible for SDP offer/answer negotiation defined in RFC 3264. The session object is used to store the SDP template from user, remote SDP received from the network and the negotiation result, local SDP.

Functions used to create, copy and destroy "soa" session objects:
  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 *);
  soa_session_t
  struct soa_session soa_session_t
  "soa" session object.
  Definition soa.h:45
  soa_create
  soa_session_t * soa_create(char const *name, su_root_t *, soa_magic_t *)
  Create a soa session.
  Definition soa.c:218
  soa_clone
  soa_session_t * soa_clone(soa_session_t *, su_root_t *, soa_magic_t *)
  Create a copy of a soa session object.
  Definition soa.c:270
  soa_destroy
  void soa_destroy(soa_session_t *)
  Destroy a session.
  Definition soa.c:352
  su_root_t
  struct su_root_t su_root_t

Functions used to set and get parameters for "soa" session objects:
  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, ...);
  soa_get_paramlist
  tagi_t * soa_get_paramlist(soa_session_t const *ss, tag_type_t tag, tag_value_t value,...)
  Return a list of parameters.
  Definition soa.c:713
  soa_get_params
  int soa_get_params(soa_session_t const *ss, tag_type_t tag, tag_value_t value,...)
  Get tagged parameters.
  Definition soa.c:625
  soa_set_params
  int soa_set_params(soa_session_t *ss, tag_type_t tag, tag_value_t value,...)
  Set parameters.
  Definition soa.c:397
  tagi_t
  tag_value_t
  intptr_t tag_value_t
  tag_type_t
  struct tag_type_s const * tag_type_t

Functions used to obtain status information from "soa" session objects:
  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);
  soa_get_warning
  int soa_get_warning(soa_session_t *ss, char const **return_phrase)
  Return SIP Warning code and text.
  Definition soa.c:830
  soa_error_as_sip_response
  int soa_error_as_sip_response(soa_session_t *soa, char const **return_phrase)
  Convert soa error to a SIP response code and phrase.
  Definition soa.c:788
  soa_error_as_sip_reason
  char const * soa_error_as_sip_reason(soa_session_t *soa)
  Convert soa error to a SIP Reason header.
  Definition soa.c:806

Functions used to store and retrieve SDP descriptions:
  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);
  soa_get_local_sdp
  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)
  Get local SDP.
  Definition soa.c:1284
  soa_set_remote_sdp
  int soa_set_remote_sdp(soa_session_t *ss, struct sdp_session_s const *sdp, char const *str, issize_t len)
  Set remote SDP (offer or answer).
  Definition soa.c:1190
  soa_get_user_version
  int soa_get_user_version(soa_session_t const *ss)
  Returns the version number of user session description.
  Definition soa.c:1036
  soa_set_user_sdp
  int soa_set_user_sdp(soa_session_t *ss, struct sdp_session_s const *sdp, char const *str, issize_t len)
  Store user SDP to soa session.
  Definition soa.c:1071
  soa_get_user_sdp
  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)
  Return user SDP description.
  Definition soa.c:995
  soa_set_capability_sdp
  int soa_set_capability_sdp(soa_session_t *ss, struct sdp_session_s const *sdp, char const *str, issize_t len)
  Set capability SDP.
  Definition soa.c:909
  soa_clear_remote_sdp
  int soa_clear_remote_sdp(soa_session_t *ss)
  Clear remote SDP.
  Definition soa.c:1235
  soa_get_capability_sdp
  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)
  Return SDP description of capabilities.
  Definition soa.c:859
  soa_get_remote_version
  int soa_get_remote_version(soa_session_t const *ss)
  Returns the version number of remote session description.
  Definition soa.c:1153
  soa_get_remote_sdp
  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)
  Return remote SDP description of the session.
  Definition soa.c:1112
  sdp_session_s

Functions for executing Offer/Answer negotiation steps:
  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);
  soa_generate_offer
  int soa_generate_offer(soa_session_t *, int always, soa_callback_f *)
  Generate offer.
  Definition soa.c:1445
  soa_is_complete
  int soa_is_complete(soa_session_t const *ss)
  Return true if the SDP Offer/Answer negotation is complete.
  Definition soa.c:1836
  soa_process_answer
  int soa_process_answer(soa_session_t *, soa_callback_f *)
  Complete offer-answer after receiving answer.
  Definition soa.c:1615
  soa_process_reject
  int soa_process_reject(soa_session_t *, soa_callback_f *)
  Process rejection of offer.
  Definition soa.c:1696
  soa_generate_answer
  int soa_generate_answer(soa_session_t *, soa_callback_f *)
  Process offer, generate answer.
  Definition soa.c:1535
  soa_init_offer_answer
  int soa_init_offer_answer(soa_session_t *ss)
  Initialize the offer/answer state machine.
  Definition soa.c:1321

Functions for signaling events of session signaling:
  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);
  soa_terminate
  void soa_terminate(soa_session_t *, char const *option)
  Terminate session.
  Definition soa.c:1805
  soa_activate
  int soa_activate(soa_session_t *, char const *option)
  Activate session.
  Definition soa.c:1751
  soa_deactivate
  int soa_deactivate(soa_session_t *, char const *option)
  Deactivate session.
  Definition soa.c:1782
  These functions are used to activate actions taken by soa, for instance, a COMEDIA connection is established with soa_activate().

Functions for Checking Activated Media:
  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);
  soa_is_remote_video_active
  int soa_is_remote_video_active(soa_session_t const *ss)
  Return true if remote video is active (not on hold).
  Definition soa.c:1882
  soa_is_remote_audio_active
  int soa_is_remote_audio_active(soa_session_t const *ss)
  Return true if remote audio is active (not on hold).
  Definition soa.c:1874
  soa_is_video_active
  int soa_is_video_active(soa_session_t const *ss)
  Return true if video has been activated.
  Definition soa.c:1850
  soa_is_audio_active
  int soa_is_audio_active(soa_session_t const *ss)
  Return true if audio has been activated.
  Definition soa.c:1842

## Function Documentation

## soa_activate()

int soa_activate | ( | soa_session_t * | ss,
|  | char const * | option )

Activate session.

Mark soa session as active.

Return values

  0 | when operation was successful
  -1 | upon an error

Errors:

\n EFAULT Bad address as ss.

## soa_clear_remote_sdp()

int soa_clear_remote_sdp | ( | soa_session_t * | ss | ) |

Clear remote SDP.

Remote SDP (offer or answer) should be cleared after a it has been stored in the SDP session object using soa_set_remote_sdp() or soa_set_params(), but the SDP Offer/Answer negotiation step (soa_generate_answer() or soa_process_answer()) cannot be completed.

Parameters

  ss | pointer to soa session

Return values

  0 | when successful
  -1 | upon an error

See also
  soa_init_offer_answer(), soa_set_remote_sdp(), soa_has_received_sdp(), soa_set_params(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR(), soa_generate_answer(), soa_process_answer(), soa_process_reject().

## soa_deactivate()

int soa_deactivate | ( | soa_session_t * | ss,
|  | char const * | option )

Deactivate session.

Mark soa session as inactive.

Return values

  0 | when operation was successful
  -1 | upon an error

Errors:

\n EFAULT Bad address as ss.

## soa_generate_answer()

int soa_generate_answer | ( | soa_session_t * | ss,
|  | soa_callback_f * | completed )

Process offer, generate answer.

When generating the offer the soa session combines remote offer with user SDP. There are various other parameters directing the generation of answer, set by soa_set_params().

Before calling soa_generate_answer() the remote SDP offer should have been stored into the soa session ss with soa_set_remote_sdp() or with the soa_set_params() tags SOATAG_REMOTE_SDP() or SOATAG_REMOTE_SDP_STR().

Also, the user SDP should have been stored into ss with soa_set_user_sdp() or with the soa_set_params() tags SOATAG_USER_SDP() or SOATAG_USER_SDP_STR().

The resulting SDP is also known as local SDP. It is available with soa_get_local_sdp() or with the soa_get_params() or soa_get_paramlist() tags SOATAG_LOCAL_SDP() and SOATAG_LOCAL_SDP_STR().

Parameters

  ss | pointer to session object
  completed | pointer to callback function which is invoked when operation is completed (currently not in use)

Return values

  0 | when operation is successful
  -1 | upon an error

Errors:

\n EFAULT Bad address as ss.

\n EALREADY An operation is already in progress.

\n EPROTO We have sent an offer, but have received no answer.

\n EPROTO We have not received offer.

See also
  soa_init_offer_answer(), soa_set_user_sdp(), soa_set_remote_sdp(), soa_get_local_sdp(), soa_process_reject(), soa_generate_offer(), soa_set_params(), soa_get_params(), soa_get_paramlist(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR().

## soa_generate_offer()

int soa_generate_offer | ( | soa_session_t * | ss,
|  | int | always,
|  | soa_callback_f * | completed )

Generate offer.

When generating the offer the user SDP is augmented with the required SDP lines (v=, o=, t=, c=, a=rtpmap, etc.).

The resulting SDP is also known as local SDP. It is available with soa_get_local_sdp() or with soa_get_params() and soa_get_paramlist() tags SOATAG_LOCAL_SDP() or SOATAG_LOCAL_SDP_STR().

The user SDP has been stored to the soa session with soa_set_user_sdp() or with soa_set_params() tags SOATAG_USER_SDP() or SOATAG_USER_SDP_STR(). There are various other parameters directing the generation of offer, set by soa_set_params().

Parameters

  ss | pointer to session object
  always | always send offer (even if offer/answer has been completed)
  completed | pointer to callback function which is invoked when operation is completed (currently not in use)

Return values

  1 | when operation is successful
  0 | when operation was not needed
  -1 | upon an error

Errors:

\n EFAULT Bad address.

\n EALREADY An operation is already in progress

\n EPROTO We have received offer, now we should send answer

\n EPROTO We have received SDP, but it has not been processed

\n EPROTO We have sent an offer, but have received no answer

\n EPROTO We have received offer.

See also
  soa_init_offer_answer(), soa_set_user_sdp(), soa_get_local_sdp(), soa_set_remote_sdp(), soa_process_answer(), soa_process_reject(), soa_generate_answer(), soa_set_params(), soa_get_params(), soa_get_paramlist(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR().

## soa_get_capability_sdp()

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 )

Return SDP description of capabilities.

Parameters

  ss | pointer to soa session
  return_sdp | return value for capability SDP structure
  return_sdp_str | return value for capability SDP string
  return_len | return value for length of capability SDP string

Return values

  0 | if there is no description to return
  1 | if description is returned
  -1 | upon an error

See also
  RFC 3261 section 11, soa_set_capability_sdp(), SOATAG_CAPS_SDP(), SOATAG_CAPS_SDP_STR(), nua_options(), nua_i_options

## soa_get_local_sdp()

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 )

Get local SDP.

The local SDP is used as an offer or answer and it is generated by soa_generate_offer() or soa_generate_answer(), respectively. It can be retrieved using soa_get_params() or soa_get_paramlist() with SOATAG_LOCAL_SDP() or SOATAG_LOCAL_SDP_STR() tags.

Parameters

  ss | pointer to soa session
  return_sdp | SDP session structure return value
  return_sdp_str | return value for pointer to string containing the user SDP session description
  return_len | return value for user SDP session descrioption string length

Any of the parameters return_sdp, return_sdp_str, or return_len may be NULL.

Return values

  0 | if there is no description to return
  1 | if description is returned
  -1 | upon an error

See also
  soa_generate_offer(), soa_generate_answer(), soa_get_params(), soa_get_paramlist(), SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR(), soa_get_user_sdp(), soa_get_remote_sdp(), soa_get_capability_sdp().

## soa_get_params()

int soa_get_params | ( | soa_session_t const * | ss,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Get tagged parameters.

Parameters

  ss | soa session object
  tag,value,... | tagged parameter list

Returns
  Number of parameters get, or -1 upon an error.

Related Tags:
  SOATAG_CAPS_SDP(), SOATAG_CAPS_SDP_STR(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR(), SOATAG_AF(), SOATAG_ADDRESS(), SOATAG_AUDIO_AUX() (currently for "default" only), SOATAG_HOLD(), SOATAG_RTP_SELECT(), SOATAG_RTP_SORT(), SOATAG_RTP_MISMATCH(), SOATAG_SRTP_ENABLE(), SOATAG_SRTP_CONFIDENTIALITY(), and SOATAG_SRTP_INTEGRITY().

## soa_get_remote_sdp()

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 )

Return remote SDP description of the session.

Remote SDP is used, together with User SDP as basis for SDP Offer/Answer negotiation.

Parameters

  ss | pointer to soa session
  return_sdp | SDP session structure return value
  return_sdp_str | return value for pointer to string containing the user SDP session description
  return_len | return value for user SDP session descrioption string length

Any of the parameters return_sdp, return_sdp_str, or return_len may be NULL.

Return values

  0 | if there is no description to return
  1 | if description is returned
  -1 | upon an error

See also
  soa_set_remote_sdp(), soa_get_remote_version(), soa_get_params(), soa_get_paramlist(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR(), soa_get_local_sdp(), soa_get_user_sdp(), soa_get_capability_sdp().

## soa_get_remote_version()

int soa_get_remote_version | ( | soa_session_t const * | ss | ) |

Returns the version number of remote session description.

The version numbering starts from zero and it is incremented each time soa_set_remote_sdp() or soa_set_params() modifies remote SDP.

Parameters

  ss | pointer to soa session

Returns
  Sequence number of remote SDP.

See also
  soa_set_remote_sdp(), soa_get_remote_sdp(), soa_set_params(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR()

## soa_get_user_sdp()

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 )

Return user SDP description.

User SDP is used as basis for SDP Offer/Answer negotiation. It can be very minimal template, consisting just m= line containing media name, transport protocol, port number and list of supported codecs.

The SDP used as an offer or answer (generated by soa_generate_answer() or soa_generate_offer()) is known as local SDP and it is available with soa_get_local_sdp() or SOATAG_LOCAL_SDP()/SOATAG_LOCAL_SDP_STR() tags.

Parameters

  ss | pointer to soa session
  return_sdp | SDP session structure return value
  return_sdp_str | return value for pointer to string containing the user SDP session description
  return_len | return value for user SDP session description string length

Any of the parameters return_sdp, return_sdp_str, or return_len may be NULL.

Return values

  0 | if there is no description to return
  1 | if description is returned
  -1 | upon an error

See also
  soa_get_local_sdp(), soa_set_user_sdp(), soa_get_user_version(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), soa_get_remote_sdp(), soa_get_capability_sdp()

## soa_get_user_version()

int soa_get_user_version | ( | soa_session_t const * | ss | ) |

Returns the version number of user session description.

The version numbering starts from zero and it is incremented each time soa_set_user_sdp() or soa_set_params() modifies user SDP.

Parameters

  ss | pointer to soa session

Returns
  Sequence number of user SDP.

See also
  soa_set_user_sdp(), soa_get_user_sdp(), soa_set_params(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR()

## soa_init_offer_answer()

int soa_init_offer_answer | ( | soa_session_t * | ss | ) |

Initialize the offer/answer state machine.

Parameters

  ss | pointer to soa session

Return values

  0 | when successful
  -1 | upon an error

## soa_is_complete()

int soa_is_complete | ( | soa_session_t const * | ss | ) |

Return true if the SDP Offer/Answer negotation is complete.

The soa_init_offer_answer() clears the completion flag.

## soa_process_answer()

int soa_process_answer | ( | soa_session_t * | ss,
|  | soa_callback_f * | completed )

Complete offer-answer after receiving answer.

The SDP offer/answer negotiation is completed after receiving answer from remote end. The answer is combined with the offer, and the application should activate the media and codecs according to the negotiation result, available as local SDP.

Parameters

  ss | pointer to session object
  completed | pointer to callback function which is invoked when operation is completed (currently not in use)

Return values

  1 | when operation is successful
  0 | when operation was not needed
  -1 | upon an error

Errors:

\n EFAULT Bad address as ss.

\n EALREADY An operation is already in progress.

\n EPROTO We have not sent an offer
  or already have received answer.

\n EPROTO We have not received answer.

See also
  soa_init_offer_answer(), soa_set_user_sdp(), soa_set_remote_sdp(), soa_get_local_sdp(), soa_generate_offer(), soa_generate_answer(), soa_process_reject(), soa_set_params(), soa_get_params(), soa_get_paramlist(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR().

## soa_process_reject()

int soa_process_reject | ( | soa_session_t * | ss,
|  | soa_callback_f * | completed )

Process rejection of offer.

If the SDP offer was rejected (e.g., an offer in re-INVITE asked remote end to add video to the session but the request was rejected), the session should be restored to the state it was before last offer-answer negotation round with soa_process_reject().

Parameters

  ss | pointer to session object
  completed | pointer to callback function which is invoked when operation is completed (currently not in use)

Return values

  1 | when operation is successful
  0 | when operation was not needed
  -1 | upon an error

Errors:

\n EFAULT Bad address as ss.

\n EALREADY An operation is already in progress.

\n EPROTO We have not sent an offer
  or already have received answer.

See also
  soa_init_offer_answer(), soa_set_user_sdp(), soa_set_remote_sdp(), soa_get_local_sdp(), soa_generate_offer(), soa_generate_answer(), soa_process_answer(), soa_set_params(), soa_get_params(), soa_get_paramlist(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR().

## soa_set_capability_sdp()

int soa_set_capability_sdp | ( | soa_session_t * | ss,
|  | struct sdp_session_s const * | sdp,
|  | char const * | str,
|  | issize_t | len )

Set capability SDP.

Capability SDP is used instead of user SDP when generating OPTIONS responses describing media capabilities.

Parameters

  ss | pointer to soa session
  sdp | pointer to SDP session structure
  str | pointer to string containing SDP session description
  len | lenght of string str

Return values

  1 | when SDP is stored and it differs from previously stored
  0 | when SDP is identical to previously stored one (and user version returned by soa_get_user_version() is not incremented)
  -1 | upon an error

See also
  RFC 3261 section 11, soa_get_capability_sdp(), SOATAG_CAPS_SDP(), SOATAG_CAPS_SDP_STR(), nua_options(), nua_i_options

## soa_set_params()

int soa_set_params | ( | soa_session_t * | ss,
|  | tag_type_t | tag,
|  | tag_value_t | value,
|  |  | ... )

Set parameters.

Parameters

  ss | soa session object
  tag,value,... | tagged parameter list

Returns
  Number of parameters set, or -1 upon an error.

Related Tags:
  SOATAG_CAPS_SDP(), SOATAG_CAPS_SDP_STR(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR(), SOATAG_AF(), SOATAG_ADDRESS(), SOATAG_AUDIO_AUX() (currently for "default" only), SOATAG_HOLD(), SOATAG_RTP_SELECT(), SOATAG_RTP_SORT(), SOATAG_RTP_MISMATCH(), SOATAG_SRTP_ENABLE(), SOATAG_SRTP_CONFIDENTIALITY(), SOATAG_SRTP_INTEGRITY(), and SOATAG_DELAYED_OFFER_ENABLE().

## soa_set_remote_sdp()

int soa_set_remote_sdp | ( | soa_session_t * | ss,
|  | struct sdp_session_s const * | sdp,
|  | char const * | str,
|  | issize_t | len )

Set remote SDP (offer or answer).

Remote SDP is an SDP offer or answer received from the remote end. It is used together with User SDP as basis for SDP Offer/Answer negotiation in soa_generate_answer() or soa_process_answer(). Remote SDP can be set using soa_set_params() and SOATAG_REMOTE_SDP() or SOATAG_REMOTE_SDP_STR() tags, too.

If the SDP Offer/Answer negotiation step cannot be completed and the received remote offer or answer should be ignored, call soa_clear_remote_sdp().

Parameters

  ss | pointer to soa session
  sdp | pointer to SDP session structure
  str | pointer to string containing SDP session description
  len | lenght of string str

Either sdp or str must be non-NULL. If len is -1, length of string str is calculated using strlen().

Return values

  1 | when SDP is stored and it differs from previously stored
  0 | when SDP is identical to previously stored one (and remote version returned by soa_get_remote_version() is not incremented)
  -1 | upon an error

See also
  soa_has_received_sdp(), soa_get_remote_sdp(), soa_get_remote_version(), soa_set_params(), SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR(), soa_generate_answer(), soa_process_answer(), soa_clear_remote_sdp(), soa_init_offer_answer(), soa_get_local_sdp(), soa_set_user_sdp(), soa_set_capability_sdp().

## soa_set_user_sdp()

int soa_set_user_sdp | ( | soa_session_t * | ss,
|  | struct sdp_session_s const * | sdp,
|  | char const * | str,
|  | issize_t | len )

Store user SDP to soa session.

User SDP is used as basis for SDP Offer/Answer negotiation. It can be very minimal, consisting just m= line containing media name, transport protocol port number and list of supported codecs.

The SDP used as an offer or answer (generated by soa_generate_answer() or soa_generate_offer()) is known as local SDP and it is available with soa_get_local_sdp() or SOATAG_LOCAL_SDP()/SOATAG_LOCAL_SDP_STR() tags.

Parameters

  ss | pointer to soa session
  sdp | pointer to SDP session structure
  str | pointer to string containing SDP session description
  len | lenght of string str

Either sdp or str must be non-NULL. If len is -1, length of string str is calculated using strlen().

Return values

  1 | when SDP is stored and it differs from previously stored
  0 | when SDP is identical to previously stored one (and user version returned by soa_get_user_version() is not incremented)
  -1 | upon an error

See also
  soa_get_user_sdp(), soa_get_user_version(), soa_set_params(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR(), soa_generate_offer(), soa_generate_answer(), soa_get_local_sdp(), soa_set_capability_sdp(), soa_set_remote_sdp()

## soa_terminate()

void soa_terminate | ( | soa_session_t * | ss,
|  | char const * | option )

Terminate session.

\n EFAULT Bad address as ss.

Sofia-SIP 1.12.11devel - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.