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

Tags for SDP Offer/Answer Application Interface. More...

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

Go to the source code of this file.

## Macros

#define | SOATAG_ANY()
| Filter tag matching any soa tag.
#define | SOATAG_USER_SDP(x)
| Pass parsed user session description to soa session object.
#define | SOATAG_USER_SDP_STR(x)
| Pass unparsed user session description to soa session object.
#define | SOATAG_CAPS_SDP(x)
| Pass parsed capability description to soa session object.
#define | SOATAG_CAPS_SDP_STR(x)
| Pass capability description to soa session object.
#define | SOATAG_REMOTE_SDP(x)
| Pass parsed remote session description to soa session object.
#define | SOATAG_REMOTE_SDP_STR(x)
| Pass media description file name to the NUA stack.
#define | SOATAG_LOCAL_SDP(x)
| Get parsed local session description from soa session object.
#define | SOATAG_LOCAL_SDP_STR(x)
| Get local session description as a string from soa session object.
#define | SOATAG_AF(x)
| Preferred address family for media.
#define | SOATAG_ADDRESS(x)
| Pass media address.
#define | SOATAG_RTP_SELECT(x)
| When generating answer or second offer, soa can include all the supported codecs, only one codec, or only the codecs supported by both ends in the list of payload types on the m= line.
#define | SOATAG_AUDIO_AUX(x)
| The named audio codecs are considered auxiliary, that is, they are considered as common codec only when they are the only codec listed on the media line.
#define | SOATAG_RTP_SORT(x)
| When selecting the common codecs, soa can either select first local codec supported by remote end, or first remote codec supported by local codecs.
#define | SOATAG_RTP_MISMATCH(x)
| Accept media line even if the SDP negotation code determines that there are no common codecs between local and remote media.
#define | SOATAG_ACTIVE_AUDIO(x)
| Audio session status.
#define | SOATAG_ACTIVE_VIDEO(x)
| Video session status.
#define | SOATAG_ACTIVE_IMAGE(x)
| Active image session status.
#define | SOATAG_ACTIVE_CHAT(x)
| Active chat session status.
#define | SOATAG_SRTP_ENABLE(x)
| Enable SRTP.
#define | SOATAG_SRTP_CONFIDENTIALITY(x)
| Enable SRTP confidentiality negotiation.
#define | SOATAG_SRTP_INTEGRITY(x)
| Enable SRTP integrity protection.
#define | SOATAG_HOLD(x)
| Hold media stream or streams.
#define | SOATAG_ORDERED_USER(x)
| Take account strict ordering of user SDP m=lines.
#define | SOATAG_DELAYED_OFFER_ENABLE(x)
| Enable delayed offer.
#define | SOATAG_USER_O_LINE(x)
| Use address, id and version in the initial o= line from the user SDP o= line.

## Enumerations

enum | { SOA_ACTIVE_REJECTED , SOA_ACTIVE_DISABLED , SOA_ACTIVE_INACTIVE , SOA_ACTIVE_SENDONLY , SOA_ACTIVE_RECVONLY , SOA_ACTIVE_SENDRECV }
| Media states. More...
enum | soa_af { SOA_AF_ANY , SOA_AF_IP4_ONLY , SOA_AF_IP6_ONLY , SOA_AF_IP4_IP6 , SOA_AF_IP6_IP4 }
| SOATAG_AF() parameter type. More...
enum | { SOA_RTP_SELECT_SINGLE , SOA_RTP_SELECT_COMMON , SOA_RTP_SELECT_ALL }
| Parameter type for SOATAG_RTP_SELECT(). More...
enum | { SOA_RTP_SORT_DEFAULT , SOA_RTP_SORT_LOCAL , SOA_RTP_SORT_REMOTE }
| Parameter type for SOATAG_RTP_SORT(). More...

## Variables

tagi_t | soa_tag_list []
| List of base SOA tags (defined in base SOA module).

## Detailed Description

Tags for SDP Offer/Answer Application Interface.

Author
  Pekka Pessi Pekka.nosp@m..Pes.nosp@m.si@no.nosp@m.kia..nosp@m.com

Date
  Created: Mon Aug 1 15:43:53 EEST 2005 ppessi

## Macro Definition Documentation

## SOATAG_ACTIVE_AUDIO

#define SOATAG_ACTIVE_AUDIO | ( |  | x | ) |

Audio session status.

Used with

Parameter type
  enum { SOA_ACTIVE_DISABLED, SOA_ACTIVE_REJECTED, SOA_ACTIVE_INACTIVE, SOA_ACTIVE_SENDONLY, SOA_ACTIVE_RECVONLY, SOA_ACTIVE_SENDRECV }

Values
  - SOA_ACTIVE_REJECTED (-8)
  - SOA_ACTIVE_INACTIVE (0)
  - SOA_ACTIVE_SENDONLY (1)
  - SOA_ACTIVE_RECVONLY (2)
  - SOA_ACTIVE_SENDRECV (3)

Corresponding tag taking reference parameter is SOATAG_ACTIVE_AUDIO_REF()

## SOATAG_ACTIVE_CHAT

#define SOATAG_ACTIVE_CHAT | ( |  | x | ) |

Active chat session status.

Used with
  nua_i_active
  nua_i_state

Parameter type
  enum { SOA_ACTIVE_DISABLED, SOA_ACTIVE_REJECTED, SOA_ACTIVE_INACTIVE, SOA_ACTIVE_SENDONLY, SOA_ACTIVE_RECVONLY, SOA_ACTIVE_SENDRECV }

Values
  - SOA_ACTIVE_REJECTED (-8)
  - SOA_ACTIVE_INACTIVE (0)
  - SOA_ACTIVE_SENDONLY (1)
  - SOA_ACTIVE_RECVONLY (2)
  - SOA_ACTIVE_SENDRECV (3)

Corresponding tag taking reference parameter is SOATAG_ACTIVE_CHAT_REF()

## SOATAG_ACTIVE_IMAGE

#define SOATAG_ACTIVE_IMAGE | ( |  | x | ) |

Active image session status.

Used with
  nua_i_active
  nua_i_state

Parameter type
  enum { SOA_ACTIVE_DISABLED, SOA_ACTIVE_REJECTED, SOA_ACTIVE_INACTIVE, SOA_ACTIVE_SENDONLY, SOA_ACTIVE_RECVONLY, SOA_ACTIVE_SENDRECV }

Values
  - SOA_ACTIVE_REJECTED (-8)
  - SOA_ACTIVE_INACTIVE (0)
  - SOA_ACTIVE_SENDONLY (1)
  - SOA_ACTIVE_RECVONLY (2)
  - SOA_ACTIVE_SENDRECV (3)

Parameter type
  enum { SOA_ACTIVE_DISABLED, SOA_ACTIVE_REJECTED, SOA_ACTIVE_INACTIVE, SOA_ACTIVE_SENDONLY, SOA_ACTIVE_RECVONLY, SOA_ACTIVE_SENDRECV }

Values
  - SOA_ACTIVE_REJECTED (-8)
  - SOA_ACTIVE_INACTIVE (0)
  - SOA_ACTIVE_SENDONLY (1)
  - SOA_ACTIVE_RECVONLY (2)
  - SOA_ACTIVE_SENDRECV (3)

Corresponding tag taking reference parameter is SOATAG_ACTIVE_IMAGE_REF()

## SOATAG_ACTIVE_VIDEO

#define SOATAG_ACTIVE_VIDEO | ( |  | x | ) |

Video session status.

Used with

Parameter type
  enum { SOA_ACTIVE_DISABLED, SOA_ACTIVE_REJECTED, SOA_ACTIVE_INACTIVE, SOA_ACTIVE_SENDONLY, SOA_ACTIVE_RECVONLY, SOA_ACTIVE_SENDRECV }

Values
  - SOA_ACTIVE_REJECTED (-8)
  - SOA_ACTIVE_INACTIVE (0)
  - SOA_ACTIVE_SENDONLY (1)
  - SOA_ACTIVE_RECVONLY (2)
  - SOA_ACTIVE_SENDRECV (3)

Corresponding tag taking reference parameter is SOATAG_ACTIVE_VIDEO_REF()

## SOATAG_ADDRESS

#define SOATAG_ADDRESS | ( |  | x | ) |

Pass media address.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  char const *

Values
  NUL-terminated C string containing a domain name, IPv4 address, or IPv6 address.

Corresponding tag taking reference parameter is SOATAG_ADDRESS_REF()

See also
  SOATAG_AF()

## SOATAG_AF

#define SOATAG_AF | ( |  | x | ) |

Preferred address family for media.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  enum soa_af { SOA_AF_ANY, SOA_AF_IP4_ONLY, SOA_AF_IP6_ONLY, SOA_AF_IP4_IP6, SOA_AF_IP6_IP4 }

Values
  - SOA_AF_ANY (0) any address family (default)
  - SOA_AF_IP4_ONLY (1) only IP version 4
  - SOA_AF_IP6_ONLY (2) only IP version 6
  - SOA_AF_IP4_IP6 (3) either IP version 4 or 6, version 4 preferred
  - SOA_AF_IP6_IP4 (4) either IP version 4 or 6, version 6 preferred

Corresponding tag taking reference parameter is SOATAG_AF_REF()

See also
  SOATAG_ADDRESS()

## SOATAG_ANY

#define SOATAG_ANY | ( |  | ) |

Filter tag matching any soa tag.

Filter tag matching any SOATAG_*() item.

## SOATAG_AUDIO_AUX

#define SOATAG_AUDIO_AUX | ( |  | x | ) |

The named audio codecs are considered auxiliary, that is, they are considered as common codec only when they are the only codec listed on the media line.

When generating answer or second offer soa includes auxiliary audio codecs in the list of codecs even if it is selecting only one codec or common codecs.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  A string with whitespace separated list of codec names.

Values
  E.g., "telephone-event cn".

By default, there are no auxiliary audio codecs.

Corresponding tag taking a reference parameter is SOATAG_AUDIO_AUX_REF().

Since
  New in 1.12.2.

See also
  SOATAG_RTP_SELECT(), SOATAG_RTP_MISMATCH(), SOATAG_RTP_SORT()

## SOATAG_CAPS_SDP

#define SOATAG_CAPS_SDP | ( |  | x | ) |

Pass parsed capability description to soa session object.

Used with
  soa_set_params()
  soa_get_params()

Parameter type
  sdp_session_t *

Values
  sdp_session_t describing soa capabilities

Corresponding tag taking reference parameter is SOATAG_CAPS_SDP_REF()

## SOATAG_CAPS_SDP_STR

#define SOATAG_CAPS_SDP_STR | ( |  | x | ) |

Pass capability description to soa session object.

Used with
  soa_set_param()
  soa_get_params()

Parameter type
  char const *

Values
  String containing SDP description of soa capabilities

Corresponding tag taking reference parameter is SOATAG_CAPS_SDP_STR_REF()

## SOATAG_DELAYED_OFFER_ENABLE

#define SOATAG_DELAYED_OFFER_ENABLE | ( |  | x | ) |

Enable delayed offer.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  boolean (int)

Values
  `!=0` enable
  `0` disable

Corresponding tag taking reference parameter is SOATAG_DELAYED_OFFER_ENABLE_REF()

## SOATAG_HOLD

#define SOATAG_HOLD | ( |  | x | ) |

Hold media stream or streams.

The hold media stream will have the attribute a=sendonly (meaning that some hold announcements or pause music is sent to the held party but that the held party should not generate any media) or a=inactive (meaning that no media is sent).

When putting a SIP session on hold with sendonly, the application can include, e.g., SOATAG_HOLD("audio") or SOATAG_HOLD("video") or SOATAG_HOLD("audio, video") or SOATAG_HOLD("*") as soa parameters. When using inactive instead, the application should use "#" or "audio=inactive" instead. When resuming the session, application should include the tag SOATAG_HOLD(NULL).

Note that last SOATAG_HOLD() in the tag list will override the SOATAG_HOLD() tags before it.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  character string

Values
  Comma-separated media name ("audio", "video") or wildcard ("*").

Corresponding tag taking reference parameter is SOATAG_HOLD_REF()

See also
  soa_set_params(), nua_invite(), Holding Call

## SOATAG_LOCAL_SDP

#define SOATAG_LOCAL_SDP | ( |  | x | ) |

Get parsed local session description from soa session object.

Used with
  soa_get_params(), soa_get_paramlist()

Parameter type
  sdp_session_t *

Values
  pointer to sdp_session_t.

Corresponding tag taking reference parameter is SOATAG_LOCAL_SDP_REF()

See also
  soa_get_local_sdp(), SOATAG_LOCAL_SDP_STR(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR().

## SOATAG_LOCAL_SDP_STR

#define SOATAG_LOCAL_SDP_STR | ( |  | x | ) |

Get local session description as a string from soa session object.

Used with
  soa_get_params(), soa_get_paramlist()

Parameter type
  char const *

Values
  String containing SDP offer or answer.

Corresponding tag taking reference parameter is SOATAG_LOCAL_SDP_STR_REF()..

See also
  soa_get_local_sdp(), SOATAG_LOCAL_SDP(), SOATAG_USER_SDP(), SOATAG_USER_SDP_STR().

## SOATAG_ORDERED_USER

#define SOATAG_ORDERED_USER | ( |  | x | ) |

Take account strict ordering of user SDP m=lines.

If user SDP has been updated, the new media lines replace old ones even if the media type has been changed. This allows the application to replace m=audio with m=image/t38, for instance.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  boolean

Values
  - false (0) - update session with user SDP based on media type
  - true (1) - update session with m= line in user SDP based on their order

The default value is false and session are updated based on media types.

Corresponding tag taking a reference parameter is SOATAG_RTP_SELECT_REF().

See also
  RFC 3264 section 8.3.3, T.38

Since
  New in 1.12.7.

## SOATAG_REMOTE_SDP

#define SOATAG_REMOTE_SDP | ( |  | x | ) |

Pass parsed remote session description to soa session object.

Used with
  soa_get_params(), soa_get_paramlist()

Parameter type
  sdp_session_t *

Values
  pointer to sdp_session_t.

Corresponding tag taking reference parameter is SOATAG_REMOTE_SDP_REF()

See also
  soa_set_remote_sdp(), soa_get_remote_sdp(), SOATAG_REMOTE_SDP_STR(), SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR().

## SOATAG_REMOTE_SDP_STR

#define SOATAG_REMOTE_SDP_STR | ( |  | x | ) |

Pass media description file name to the NUA stack.

Pass name of media description file that contains media templates (normally mss.sdp) to the NUA stack.

Used with
  soa_get_params(), soa_get_paramlist()

Parameter type
  char const *

Values
  String containing SDP description received from remote end.

Corresponding tag taking reference parameter is SOATAG_REMOTE_SDP_STR_REF()

See also
  soa_set_remote_sdp(), soa_get_remote_sdp(), SOATAG_REMOTE_SDP(), SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR().

## SOATAG_RTP_MISMATCH

#define SOATAG_RTP_MISMATCH | ( |  | x | ) |

Accept media line even if the SDP negotation code determines that there are no common codecs between local and remote media.

Normally, if the soa determines there are no common codecs, the media line is rejected.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  Boolean (int)

Values
  0 - reject media if there are no common codecs
  1 (!= 0) - accept media even if there are no common codecs
  Default value is 0.

Corresponding tag taking reference parameter is SOATAG_RTP_MISMATCH_REF()

See also
  SOATAG_RTP_SELECT(), SOATAG_RTP_MISMATCH(), SOATAG_AUDIO_AUX()

## SOATAG_RTP_SELECT

#define SOATAG_RTP_SELECT | ( |  | x | ) |

When generating answer or second offer, soa can include all the supported codecs, only one codec, or only the codecs supported by both ends in the list of payload types on the m= line.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  enum { SOA_RTP_SELECT_SINGLE, SOA_RTP_SELECT_COMMON, SOA_RTP_SELECT_ALL }
  (int in range 0..2)

Values
  - SOA_RTP_SELECT_SINGLE (0) - select the best common codec
  - SOA_RTP_SELECT_COMMON (1) - select all common codecs
  - SOA_RTP_SELECT_ALL (2) - select all local codecs

The default value is 0, only one RTP codec is selected. Note, however, that if there is no common codec (no local codec is supported by remote end), all the codecs are included in the list. In that case the media line is rejected, too, unless SOATAG_RTP_MISMATCH(1) has been used.

Corresponding tag taking a reference parameter is SOATAG_RTP_SELECT_REF().

See also
  SOATAG_RTP_MISMATCH(), SOATAG_RTP_SORT(), SOATAG_AUDIO_AUX()

## SOATAG_RTP_SORT

#define SOATAG_RTP_SORT | ( |  | x | ) |

When selecting the common codecs, soa can either select first local codec supported by remote end, or first remote codec supported by local codecs.

The preference is indicated with ordering: the preferred codec is first and so on.

The auxiliary audio codecs (specified with SOATAG_AUDIO_AUX()) are listed after other codecs.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  enum { SOA_RTP_SORT_DEFAULT, SOA_RTP_SORT_LOCAL, SOA_RTP_SORT_REMOTE }
  (int in range 0..2)

Values
  - SOA_RTP_SORT_DEFAULT (0) - select by local preference if media is recvonly, remote preference othewise
  - SOA_RTP_SORT_LOCAL (1) - always select by local preference
  - SOA_RTP_SORT_REMOTE (2) - always select by remote preference

The default value is SOA_RTP_SORT_DEFAULT (0).

Corresponding tag taking reference parameter is SOATAG_RTP_SORT_REF()

See also
  SOATAG_RTP_SELECT(), SOATAG_RTP_MISMATCH(), SOATAG_AUDIO_AUX()

## SOATAG_SRTP_CONFIDENTIALITY

#define SOATAG_SRTP_CONFIDENTIALITY | ( |  | x | ) |

Enable SRTP confidentiality negotiation.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  boolean (int)

Values
  `!=` 0 enable SRTP confidentiality
  `0` disable SRTP conidentiality

Corresponding tag taking reference parameter is SOATAG_SRTP_CONFIDENTIALITY_REF()

Todo
  SRTP functionality is not implemented.

## SOATAG_SRTP_ENABLE

#define SOATAG_SRTP_ENABLE | ( |  | x | ) |

Enable SRTP.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  boolean (int)

Values
  `!=0` enable
  `0` disable

Corresponding tag taking reference parameter is SOATAG_SRTP_ENABLE_REF()

Todo
  SRTP functionality is not implemented.

## SOATAG_SRTP_INTEGRITY

#define SOATAG_SRTP_INTEGRITY | ( |  | x | ) |

Enable SRTP integrity protection.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  boolean (int)

Values
  `!=0` enable
  `0` disable

Corresponding tag taking reference parameter is SOATAG_SRTP_INTEGRITY_REF()

Todo
  SRTP functionality is not implemented.

## SOATAG_USER_O_LINE

#define SOATAG_USER_O_LINE | ( |  | x | ) |

Use address, id and version in the initial o= line from the user SDP o= line.

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  Boolean (int)

Values
  0 - generate address, id and version
  1 (!= 0) - use address, id and version from o= line

Corresponding tag taking reference parameter is SOATAG_USER_O_LINE_REF()

See also
  SOATAG_USER_SDP()

Since
  Not yet released

## SOATAG_USER_SDP

#define SOATAG_USER_SDP | ( |  | x | ) |

Pass parsed user session description to soa session object.

User SDP is used as basis for SDP Offer/Answer negotiation. It can be very minimal, consisting just sdp_session_t structures, sdp_media_t structures and sdp_rtpmap_t structures listing te supported media, used RTP port number, and RTP payload descriptions of supported codecs.

When generating the offer or answer the user SDP is augmented with the required SDP lines (v=, o=, t=, c=, a=rtpmap, etc.) as required. The complete offer or answer generated by soa is passed in SOATAG_LOCAL_SDP() (SOATAG_LOCAL_SDP_STR() contains same in text format).

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  sdp_session_t *

Values
  pointer to sdp_session_t.

Corresponding tag taking reference parameter is SOATAG_USER_SDP_REF()

See also
  soa_set_user_sdp(), soa_get_user_sdp(), SOATAG_USER_SDP_STR(), SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR().

## SOATAG_USER_SDP_STR

#define SOATAG_USER_SDP_STR | ( |  | x | ) |

Pass unparsed user session description to soa session object.

User SDP is used as basis for SDP Offer/Answer negotiation. It can be very minimal, listing just m= lines with the port numbers and RTP payload numbers of supported codecs, like

SOATAG_USER_SDP_STR("m=audio 5004 RTP/AVP 0 8")
SOATAG_USER_SDP_STR
#define SOATAG_USER_SDP_STR(x)
Pass unparsed user session description to soa session object.
Definition soa_tag.h:81

When generating the offer or answer the user SDP is augmented with the required SDP lines (v=, o=, t=, c=, a=rtpmap, etc.) as required. The complete offer or answer generated by soa is passed in SOATAG_LOCAL_SDP_STR() (SOATAG_LOCAL_SDP() contains session in parsed format).

Used with
  soa_set_params(), soa_get_params(), soa_get_paramlist()

Parameter type
  char const *

Values
  String containing minimal SDP description.

Corresponding tag taking reference parameter is SOATAG_USER_SDP_STR_REF()

See also
  soa_set_user_sdp(), soa_get_user_sdp(), SOATAG_USER_SDP(), SOATAG_LOCAL_SDP(), SOATAG_LOCAL_SDP_STR()

## Enumeration Type Documentation

## anonymous enum

anonymous enum

Media states.

Enumerator
SOA_ACTIVE_REJECTED | Media rejected in negotiation.
SOA_ACTIVE_DISABLED | Media not negotiated.
SOA_ACTIVE_INACTIVE | Media is inactive: no RTP.
SOA_ACTIVE_SENDONLY | Media is sent only.
SOA_ACTIVE_RECVONLY | Media is received only.
SOA_ACTIVE_SENDRECV | Media is bidirectional.

## anonymous enum

anonymous enum

Parameter type for SOATAG_RTP_SORT().

Enumerator
SOA_RTP_SORT_DEFAULT | Select codecs by local preference when media is recvonly, remote preference othewise.
SOA_RTP_SORT_LOCAL | Select codecs by local preference.
SOA_RTP_SORT_REMOTE | Select codecs by remote preference.

## anonymous enum

anonymous enum

Parameter type for SOATAG_RTP_SELECT().

Enumerator
SOA_RTP_SELECT_SINGLE | Select the best common codec.
SOA_RTP_SELECT_COMMON | Select all common codecs.
SOA_RTP_SELECT_ALL | Select all local codecs.

## soa_af

enum soa_af

SOATAG_AF() parameter type.

Enumerator
SOA_AF_ANY | Use any address family.
SOA_AF_IP4_ONLY | Use IP version 4 only.
SOA_AF_IP6_ONLY | Use IP version 6 only.
SOA_AF_IP4_IP6 | Prefer IP4 to IP6.
SOA_AF_IP6_IP4 | Prefer IP6 to IP4.

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