sip_header.h

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

SOFIAPUBFUN int sip_from_tag(su_home_t *, sip_from_t *from, char const *tag);

/** Create a @To header object. */
SOFIAPUBFUN sip_to_t *sip_to_create(su_home_t *, url_string_t const *url);

SOFIAPUBFUN int sip_to_tag(su_home_t *, sip_to_t *to, char const *tag);

/** Create a @Via object. */ 
SOFIAPUBFUN sip_via_t *sip_via_create(su_home_t *h,
				      char const *host,
				      char const *port, 
				      char const *transport,
				      /* char const *params */
				      ...);

/** Get transport protocol name. */
#if SU_HAVE_INLINE
su_inline char const *sip_via_transport(sip_via_t const *v)
{
  char const *tp = v->v_protocol;
  if (tp) {
    tp = strchr(tp, '/'); 
    if (tp) {
      tp = strchr(tp + 1, '/');
      if (tp)
	return tp + 1;
    }
  }
  return NULL;
}
#else
char const *sip_via_transport(sip_via_t const *v);
#endif

SOFIAPUBFUN char const *sip_via_port(sip_via_t const *v, int *using_rport);

SOFIAPUBFUN
sip_payload_t *sip_payload_create(su_home_t *, void const *data, isize_t len);

/**@ingroup sip_payload
 *
 * Initialize a SIP payload structure with pointer to data and its length. 
 *
 * The SIP_PAYLOAD_INIT2() macro initializes a #sip_payload_t header
 * structure with a pointer to data and its length in octets. For
 * instance,
 * @code 
 *  sip_payload_t txt_payload = SIP_PAYLOAD_INIT2(txt, strlen(txt));
 * @endcode
 *
 * The SIP_PAYLOAD_INIT2() macro can be used when creating a new payload
 * from heap is not required, for instance, when the resulting payload
 * structure is immediately copied.
 *
 * @HIDE 
 */
#define SIP_PAYLOAD_INIT2(data, length) \
  {{{ 0, 0, sip_payload_class, data, length }, NULL, data, length }}

/** Create a SIP separator line structure. */
SOFIAPUBFUN sip_separator_t *sip_separator_create(su_home_t *home);

/** Check that a required feature is supported. */
SOFIAPUBFUN
sip_unsupported_t *sip_has_unsupported(su_home_t *,
				       sip_supported_t const *support, 
				       sip_require_t const *require);

SOFIAPUBFUN
sip_unsupported_t *sip_has_unsupported2(su_home_t *,
					sip_supported_t const *support,
					sip_require_t const *by_require,
					sip_require_t const *require);

SOFIAPUBFUN
sip_unsupported_t *
sip_has_unsupported_any(su_home_t *,
			sip_supported_t const *support,
			sip_require_t const *by_require,
			sip_proxy_require_t const *by_proxy_require,
			sip_require_t const *require,
			sip_require_t const *require2,
			sip_require_t const *require3);

/** Check that a feature is supported. */
SOFIAPUBFUN
int sip_has_supported(sip_supported_t const *support, char const *feature);

/** Check that a feature is in the list. */
SOFIAPUBFUN
int sip_has_feature(msg_list_t const *supported, char const *feature);

/** Return true if the method is listed in @Allow header. */
SOFIAPUBFUN int sip_is_allowed(sip_allow_t const *allow, 
			       sip_method_t method, char const *name);

/** Check if the well-known method is listed in @Allow header. @NEW_1_12_6. */
#define SIP_IS_ALLOWED(allow, method) \
  (sip_method_unknown < (method) && (method) < 32 && \
   (allow) && ((allow)->k_bitmap & (1 << (method))) != 0)

/**
 * Bitmasks for header classifications.
 *
 * If parsing of a particular header fails, the error bits in #msg_t are
 * updated. The error bits can be obtained via msg_extract_errors() after
 * parsing. The header-specific bits are stored along with the
 * @ref msg_hclass_t "header class" in the #msg_href_t structure, found in
 * the parser tables of the #msg_mclass_t object.
 *
 * @sa NTATAG_BAD_REQ_MASK(), NTATAG_BAD_RESP_MASK(),
 * #msg_mclass_t, struct #msg_mclass_s, msg_mclass_clone(),
 * msg_mclass_insert_with_mask(),
 * #msg_href_t, struct #msg_href_s, msg_mclass_insert().
 */
enum sip_bad_mask {
  /** Bit marking essential headers in a request message.
   *
   * @ref sip_request \"request line\"", @From, @To, @CSeq, @CallID,
   * @ContentLength, @Via
   */
  sip_mask_request = (1 << 0),

  /** Bit marking essential headers in a response message.
   *
   * @ref sip_status \"status line\"", @From, @To, @CSeq, @CallID,
   * @ContentLength, @Via
   */
  sip_mask_response = (1 << 1),

  /** Bit marking essential headers for User-Agent.
   *
   * @ContentType, @ContentDisposition, @ContentEncoding, @Supported,
   * @Contact, @Require, and @RecordRoute.
   */
  sip_mask_ua = (1 << 2),

  /** Bit marking essential headers for proxy server.
   *
   * @Route, @MaxForwards, @ProxyRequire, @ProxyAuthorization, @Supported,
   * @Contact, and @RecordRoute.
   */
  sip_mask_proxy = (1 << 3),

  /** Bit marking essential headers for registrar server.
   *
   * @MinExpires, @Authorization, @Path, @Supported, @Contact, @Require, and
   * @Expires.
   * 
   */
  sip_mask_registrar = (1 << 4),

  /** Bit marking essential headers for 100rel extension.
   *
   * @RAck and @RSeq.
   *
   * @sa @RFC3262.
   */
  sip_mask_100rel = (1 << 5),

  /** Bit marking essential headers for SIP events.
   *
   * @Event, @Expires, and @SubscriptionState.
   * 
   * @sa @RFC3265.
   */
  sip_mask_events = (1 << 6),

  /** Bit marking essential headers for session timer extension.
   *
   * @SessionExpires, and @MinSE.
   * 
   * @RFC4028
   */
  sip_mask_timer = (1 << 7),

  /** Bit marking essential headers for privacy extension.
   *
   * @Privacy.
   * 
   * @sa @RFC3323
   */
  sip_mask_privacy = (1 << 8),

  /** Bit marking essential headers for caller preference extension.
   *
   * @RequestDisposition, @AcceptContact, and @RejectContact.
   * 
   * @sa @RFC3841.
   */
  sip_mask_pref = (1 << 9),

  /** Bit marking essential headers for PUBLISH servers and clients.
   *
   * @SIPETag, and @SIPIfMatch.
   * 
   * @sa @RFC3903.
   */
  sip_mask_publish = (1 << 10)

  /* NOTE:
   * When adding bits, please update nta_agent_create() and 
   * NTATAG_BAD_RESP_MASK()/NTATAG_BAD_REQ_MASK() documentation.
   */
};

/* ------------------------------------------------------------------------- */

/* Here are @deprecated functions and names for compatibility */

/** Encode a SIP header field (name: contents CRLF). */
SOFIAPUBFUN issize_t sip_header_e(char[], isize_t, sip_header_t const *, int);

/** Decode a SIP header string (name: contents CRLF?). */
SOFIAPUBFUN
sip_header_t *sip_header_d(su_home_t *, msg_t const *, char const *);

/** Encode contents of a SIP header field. */
SOFIAPUBFUN issize_t sip_header_field_e(char[], isize_t, sip_header_t const *, int);

/** Decode the string containing header field */
SOFIAPUBFUN issize_t sip_header_field_d(su_home_t *, sip_header_t *, char *, isize_t);

/** Calculate the size of a SIP header and associated memory areas. */
SOFIAPUBFUN isize_t sip_header_size(sip_header_t const *h);

/** Duplicate (deep copy) a SIP header or whole list. */ 
SOFIAPUBFUN sip_header_t *sip_header_dup(su_home_t *, sip_header_t const *);

/** Copy a SIP header or whole list. */
SOFIAPUBFUN sip_header_t *sip_header_copy(su_home_t *, sip_header_t const *o);

/** Add an event to @AllowEvents header. */
SOFIAPUBFUN int sip_allow_events_add(su_home_t *, 
				     sip_allow_events_t *ae, 
				     char const *e);

/** Add a parameter to a @Contact header object. */
SOFIAPUBFUN int sip_contact_add_param(su_home_t *, sip_contact_t *,
				      char const *param);

SOFIAPUBFUN int sip_to_add_param(su_home_t *, sip_to_t *, char const *);

SOFIAPUBFUN int sip_from_add_param(su_home_t *, sip_from_t *, char const *);

/** Add a parameter to a @Via header object. */ 
SOFIAPUBFUN int sip_via_add_param(su_home_t *, sip_via_t *, char const *);

#define sip_from_make_url     sip_from_create
#define sip_to_make_url       sip_to_create
#define sip_params_find       msg_params_find

SOFIA_END_DECLS

#endif