soa.c

Sofia SIP is an open-source SIP User-Agent library, compliant with the IETF RFC3261 specification.

 *                        containing the user SDP session description
 * @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 
 * may be NULL.
 *
 * @retval 0 if there is no description to return
 * @retval 1 if description is returned
 * @retval -1 upon an error
 *
 * @sa 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()
 */
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)
{
  sdp_session_t const *sdp;
  char const *sdp_str;

  SU_DEBUG_9(("soa_get_user_sdp(%s::%p, [%p], [%p], [%p]) called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss,
			  (void *)return_sdp, (void *)return_sdp_str, (void *)return_len));

  if (ss == NULL)
    return (void)su_seterrno(EFAULT), -1;

  sdp = ss->ss_user->ssd_sdp;
  sdp_str = ss->ss_user->ssd_str;

  if (sdp == NULL)
    return 0;
  if (return_sdp)
    *return_sdp = sdp;
  if (return_sdp_str)
    *return_sdp_str = sdp_str;
  if (return_len)
    *return_len = strlen(sdp_str);

  return 1;
}

/**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.
 *
 * @param ss  pointer to @soa session

 * @return Sequence number of user SDP.
 *
 * @sa soa_set_user_sdp(), soa_get_user_sdp(), soa_set_params(),
 * SOATAG_USER_SDP(), SOATAG_USER_SDP_STR()
 */
int soa_get_user_version(soa_session_t const *ss)
{
  assert(ss != NULL);
  return ss ? (int)ss->ss_user_version : -1;
} 

/**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 <i>local SDP</i> and it is available
 * with soa_get_local_sdp() or SOATAG_LOCAL_SDP()/SOATAG_LOCAL_SDP_STR()
 * tags.
 *
 * @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
 *
 * Either @a sdp or @a str must be non-NULL. If @a len is -1, length of
 * string @a str is calculated using strlen().
 *
 * @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 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()
 */
int soa_set_user_sdp(soa_session_t *ss, 
		     struct sdp_session_s const *sdp,
		     char const *str, issize_t len)
{
  SU_DEBUG_9(("soa_set_user_sdp(%s::%p, %p, %p, "MOD_ZD") called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss, (void *)sdp, (void *)str, (ssize_t)len));

  return soa_set_sdp(ss, soa_user_sdp_kind, sdp, str, len);
}

/** Set user SDP (base version). */
int soa_base_set_user_sdp(soa_session_t *ss, 
			  sdp_session_t *sdp, char const *str0, isize_t len0)
{
  ++ss->ss_user_version;
  return soa_description_set(ss, ss->ss_user, sdp, str0, len0);
}

/**Return remote SDP description of the session.
 *
 * <i>Remote SDP</i> is used, together with <i>User SDP</i> as basis for SDP
 * Offer/Answer negotiation.
 *
 * @param ss  pointer to @soa session
 * @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
 *                    length 
 *
 * Any of the parameters @a return_sdp, @a return_sdp_str, or @a return_len 
 * may be NULL.
 *
 * @retval 0 if there is no description to return
 * @retval 1 if description is returned
 * @retval -1 upon an error
 *
 * @sa 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().
 */
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)
{
  sdp_session_t const *sdp;
  char const *sdp_str;

  SU_DEBUG_9(("soa_get_remote_sdp(%s::%p, [%p], [%p], [%p]) called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss,
			  (void *)return_sdp, (void *)return_sdp_str, (void *)return_len));

  if (ss == NULL)
    return (void)su_seterrno(EFAULT), -1;

  sdp = ss->ss_remote->ssd_sdp;
  sdp_str = ss->ss_remote->ssd_str;

  if (sdp == NULL)
    return 0;
  if (return_sdp)
    *return_sdp = sdp;
  if (return_sdp_str)
    *return_sdp_str = sdp_str;
  if (return_len)
    *return_len = strlen(sdp_str);

  return 1;
}

/**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.
 *
 * @param ss  pointer to @soa session

 * @return Sequence number of remote SDP.
 *
 * @sa soa_set_remote_sdp(), soa_get_remote_sdp(), soa_set_params(),
 * SOATAG_REMOTE_SDP(), SOATAG_REMOTE_SDP_STR()
 */
int soa_get_remote_version(soa_session_t const *ss)
{
  assert(ss != NULL);
  return ss->ss_remote_version;
} 

/** Set remote SDP (offer or answer).
 *
 * <i>Remote SDP</i> is an SDP offer or answer received from the remote end. 
 * It is used together with <i>User SDP</i> 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().
 *
 * @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
 *
 * Either @a sdp or @a str must be non-NULL. If @a len is -1, length of
 * string @a str is calculated using strlen().
 *
 * @retval 1 when SDP is stored and it differs from previously stored
 * @retval 0 when SDP is identical to previously stored one (and remote version
 *           returned by soa_get_remote_version() is not incremented)
 * @retval -1 upon an error
 *
 * @sa 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().
 */
int soa_set_remote_sdp(soa_session_t *ss, 
		       struct sdp_session_s const *sdp,
		       char const *str, issize_t len)
{
  SU_DEBUG_9(("soa_set_remote_sdp(%s::%p, %p, %p, "MOD_ZD") called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss, (void *)sdp, (void *)str, (ssize_t)len));

  return soa_set_sdp(ss, soa_remote_sdp_kind, sdp, str, len);
}

/** Base method for setting the remote SDP (offer or answer). */
int soa_base_set_remote_sdp(soa_session_t *ss,
			    int new_version,
			    sdp_session_t *sdp, char const *str0, isize_t len0)
{
  /* This is cleared in soa_generate_answer() or soa_process_answer(). */
  ss->ss_unprocessed_remote = 1;

  if (!new_version)
    return 0;
    
  soa_set_activity(ss, sdp->sdp_media, soa_activity_remote);

  ss->ss_remote_version++;
  
  return soa_description_set(ss, ss->ss_remote, sdp, str0, len0);
}

/** 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.
 *
 * @param ss  pointer to @soa session
 *
 * @retval 0  when successful
 * @retval -1 upon an error
 *
 * @sa 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().
 */
int soa_clear_remote_sdp(soa_session_t *ss)
{
  SU_DEBUG_9(("soa_clear_remote_sdp(%s::%p) called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss));

  if (!ss)
    return (void)su_seterrno(EFAULT), -1;

  ss->ss_unprocessed_remote = 0;

  return 0;
}

/** Check if remote SDP has been saved but it has not been processed.
 *
 * @sa soa_init_offer_answer(), soa_set_remote_sdp(), soa_generate_answer(),
 * soa_process_answer(), soa_clear_remote_sdp().
 */
int soa_has_received_sdp(soa_session_t const *ss)
{
  return ss && ss->ss_unprocessed_remote;
}


/**Get local SDP.
 *
 * The <i>local SDP</i> 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.
 *
 * @param ss  pointer to @soa session
 * @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
 *                    length 
 *
 * Any of the parameters @a return_sdp, @a return_sdp_str, or @a return_len 
 * may be NULL.
 *
 * @retval 0 if there is no description to return
 * @retval 1 if description is returned
 * @retval -1 upon an error
 *
 * @sa 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().
 */
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)
{
  sdp_session_t const *sdp;
  char const *sdp_str;

  SU_DEBUG_9(("soa_get_local_sdp(%s::%p, [%p], [%p], [%p]) called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss,
			  (void *)return_sdp, (void *)return_sdp_str, (void *)return_len));

  if (ss == NULL)
    return (void)su_seterrno(EFAULT), -1;

  sdp = ss->ss_local->ssd_sdp;
  sdp_str = ss->ss_local->ssd_str;

  if (sdp == NULL)
    return 0;
  if (return_sdp)
    *return_sdp = sdp;
  if (return_sdp_str)
    *return_sdp_str = sdp_str;
  if (return_len)
    *return_len = strlen(sdp_str);

  return 1;
}

/**Initialize the offer/answer state machine.
 *
 * @param ss  pointer to @soa session
 *
 * @retval 0  when successful
 * @retval -1 upon an error
 */
int soa_init_offer_answer(soa_session_t *ss)
{
  int complete;

  SU_DEBUG_9(("soa_init_offer_answer(%s::%p) called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss));

  if (!ss)
    return 0;

  complete = ss->ss_complete;

  ss->ss_complete = 0;
  ss->ss_offer_sent = 0;
  ss->ss_offer_recv = 0;
  ss->ss_answer_sent = 0;
  ss->ss_answer_recv = 0;

  ss->ss_unprocessed_remote = 0;

  return complete;
}

/** Return list of media fetures. */
char **soa_media_features(soa_session_t *ss, int live, su_home_t *home)
{
  SU_DEBUG_9(("soa_media_features(%s::%p, %u, %p) called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss, live, (void *)home));

  if (ss)
    return ss->ss_actions->soa_media_features(ss, live, home);
  else
    return (void)su_seterrno(EFAULT), NULL;
}

char **soa_base_media_features(soa_session_t *ss, int live, su_home_t *home)
{
  return su_zalloc(home, 8 * sizeof (char **));
}

char const * const * soa_sip_require(soa_session_t const *ss)
{
  SU_DEBUG_9(("soa_sip_require(%s::%p) called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss));

  if (ss)
    return ss->ss_actions->soa_sip_require(ss);
  else
    return (void)su_seterrno(EFAULT), NULL;
}

char const * const * soa_base_sip_require(soa_session_t const *ss)
{
  static char const *null = NULL;
  return &null;
}

char const * const * soa_sip_supported(soa_session_t const *ss)
{
  SU_DEBUG_9(("soa_sip_supported(%s::%p) called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss));

  if (ss)
    return ss->ss_actions->soa_sip_supported(ss);
  else
    return (void)su_seterrno(EFAULT), NULL;
}

char const * const * soa_base_sip_supported(soa_session_t const *ss)
{
  static char const *null = NULL;
  return &null;
}

int soa_remote_sip_features(soa_session_t *ss,
			    char const * const * supported,
			    char const * const * require)
{
  SU_DEBUG_9(("soa_remote_sip_features(%s::%p, %p, %p) called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss, (void *)supported, (void *)require));

  if (ss)
    return ss->ss_actions->soa_remote_sip_features(ss, supported, require);
  else
    return (void)su_seterrno(EFAULT), -1;
}

int soa_base_remote_sip_features(soa_session_t *ss,
				    char const * const * supported,
				    char const * const * require)
{
  return 0;
}


/**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 <i>local SDP</i>. 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().
 *
 * @param ss pointer to session object
 * @param always always send offer (even if offer/answer has been completed)
 * @param completed pointer to callback function which is invoked when
 *                  operation is completed (currently not in use)
 *
 * @retval 1 when operation is successful
 * @retval 0 when operation was not needed
 * @retval -1 upon an error
 *
 * @ERRORS
 */
int soa_generate_offer(soa_session_t *ss,
		       int always,
		       soa_callback_f *completed)
{
  SU_DEBUG_9(("soa_generate_offer(%s::%p, %u) called\n",
	      ss ? ss->ss_actions->soa_name : "", (void *)ss, always));

  /** @ERROR EFAULT Bad address. */
  if (ss == NULL)
    return su_seterrno(EFAULT), -1;