sip.docs

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

 *
 * The #sip_X_t is defined as follows:
 * @code
 * typedef struct sip_X_s {
 *   msg_common_t   X_common[1];        // Common fragment info
 *   sip_X_t       *X_next;             // Link to next X header field
 *   uint32_t       X_value;            // Value of X
 *   msg_param_t   *X_param;            // List of parameters
 * } sip_X_t;
 * @endcode
 */
typedef struct sip_X_s sip_X_t;

/**@var msg_hclass_t sip_X_class[];
 * @brief Header class for SIP X.
 * 
 * The header class sip_X_class defines how a SIP
 * X is parsed and printed.  It also
 * contains methods used by SIP parser and other functions
 * to manipulate the sip_X_t header structure.
 * 
 */
SIP_DLL extern msg_hclass_t sip_X_class[];

enum { 
 /** Hash of X. @internal */
 sip_X_hash = hash 
};

/** Parse a X. @internal */
msg_parse_f sip_X_d;

/** Print a X. @internal */
msg_print_f sip_X_e;

/**Initializer for structure sip_X_t.
 * 
 * A static sip_X_t structure must be initialized
 * with the SIP_X_INIT() macro. For instance,
 * @code 
 * 
 *  sip_X_t sip_X = SIP_X_INIT;
 * 
 * @endcode
 * @HI
 */
#define SIP_X_INIT() SIP_HDR_INIT(X)

/**Initialize a structure sip_X_t.
 * 
 * An sip_X_t structure can be initialized with the
 * sip_X_init() function/macro. For instance,
 * @code
 * 
 *  sip_X_t sip_X;
 * 
 *  sip_X_init(&sip_X);
 * 
 * @endcode
 * @HI
 */
#if SU_HAVE_INLINE
su_inline sip_X_t *sip_X_init(sip_X_t x[1])
{
  return SIP_HEADER_INIT(x, sip_X_class, sizeof(sip_X_t));
}
#else
#define sip_X_init(x) \
  SIP_HEADER_INIT(x, sip_X_class, sizeof(sip_X_t))
#endif

/**Test if header object is instance of sip_X_t.
 * 
 * The function sip_is_X() returns true (nonzero) if
 * the header class is an instance of X
 * object and false (zero) otherwise.
 * 
 * @param header pointer to the header structure to be tested
 * 
 * @return
 * The function sip_is_X() returns true (nonzero) if
 * the header object is an instance of header X and
 * false (zero) otherwise.
 */
#if SU_HAVE_INLINE
su_inline int sip_is_X(sip_header_t const *header)
{
  return header && header->sh_class->hc_id == sip_hdr_X;
}
#else
int sip_is_X(sip_header_t const *header);
#endif

#define sip_X_p(h) sip_is_X((h))

/**Duplicate (deep copy) @c sip_X_t.
 * 
 * The function sip_X_dup() duplicates a header
 * structure @a hdr.  If the header structure @a hdr
 * contains a reference (@c hdr->x_next) to a list of
 * headers, all the headers in the list are duplicated, too.
 * 
 * @param home  memory home used to allocate new structure
 * @param hdr   header structure to be duplicated
 * 
 * When duplicating, all parameter lists and non-constant
 * strings attached to the header are copied, too.  The
 * function uses given memory @a home to allocate all the
 * memory areas used to copy the header.
 * 
 * @par Example
 * @code
 * 
 *   X = sip_X_dup(home, sip->sip_X);
 * 
 * @endcode
 * 
 * @return
 * The function sip_X_dup() returns a pointer to the
 * newly duplicated sip_X_t header structure, or NULL
 * upon an error.
 */
sip_X_t *sip_X_dup(su_home_t *home, sip_X_t const *hdr);

/**Copy a sip_X_t header structure.
 * 
 * The function sip_X_copy() copies a header structure @a
 * hdr.  If the header structure @a hdr contains a reference (@c
 * hdr->h_next) to a list of headers, all the headers in that
 * list are copied, too. The function uses given memory @a home
 * to allocate all the memory areas used to copy the header
 * structure @a hdr.
 * 
 * @param home    memory home used to allocate new structure
 * @param hdr     pointer to the header structure to be duplicated
 * 
 * When copying, only the header structure and parameter lists
 * attached to it are duplicated.  The new header structure
 * retains all the references to the strings within the old @a
 * header, including the encoding of the old header, if present.
 * 
 * @par Example
 * @code
 * 
 *   X = sip_X_copy(home, sip->sip_X);
 * 
 * @endcode
 * 
 * @return
 * The function sip_X_copy() returns a pointer to
 * newly copied header structure, or NULL upon an error.
 */
sip_X_t *sip_X_copy(su_home_t *home, sip_X_t const *hdr);

/**Make a header structure sip_X_t.
 * 
 * The function sip_X_make() makes a new
 * sip_X_t header structure.  It allocates a new
 * header structure, and decodes the string @a s as the
 * value of the structure.
 * 
 * @param home memory home used to allocate new header structure.
 * @param s    string to be decoded as value of the new header structure
 * 
 * @note This function is usually implemented as a macro calling
 * sip_header_make().
 * 
 * @return
 * The function sip_X_make() returns a pointer to
 * newly maked sip_X_t header structure, or NULL upon
 * an error.
 */
#if SU_HAVE_INLINE
su_inline sip_X_t *sip_X_make(su_home_t *home, char const *s)
{
  return sip_header_make(home, sip_X_class, s)->sh_X;
}
#else
sip_X_t *sip_X_make(su_home_t *home, char const *s);
#endif

/**Make a X from formatting result.
 * 
 * The function sip_X_format() makes a new
 * X object using formatting result as its
 * value.  The function first prints the arguments according to
 * the format @a fmt specified.  Then it allocates a new header
 * structure, and uses the formatting result as the header
 * value.
 * 
 * @param home   memory home used to allocate new header structure.
 * @param fmt    string used as a printf()-style format
 * @param ...    argument list for format
 * 
 * @note This function is usually implemented as a macro calling
 * msg_header_format().
 * 
 * @return
 * The function sip_X_format() returns a pointer to newly
 * makes header structure, or NULL upon an error.
 * 
 * @HIDE
 */
#if SU_HAVE_INLINE
su_inline
#endif
sip_X_t *sip_X_format(su_home_t *home, char const *fmt, ...)
     __attribute__((format (printf, 2, 3)));

#if SU_HAVE_INLINE
su_inline sip_X_t *sip_X_format(su_home_t *home, char const *fmt, ...)
{
  sip_header_t *h;
  va_list ap;
  
  va_start(ap, fmt);
  h = sip_header_vformat(home, sip_X_class, fmt, ap);
  va_end(ap);
 
  return h->sh_X;
}
#endif

/**Decode a header X.
 *
 * The function sip_X_d() decodes value of the header X in the preallocated
 * header structure @a h.  The string @a s to be decoded should not contain
 * the header name or colon. The decoding function also expects that the
 * leading and trailing whitespace has been removed from the string @a s.
 *
 * @param home   memory home used to allocate new header structure.
 * @param h      sip_X_t header structure 
 * @param s      string to be decoded
 * @param bsiz   length of string @a s
 *
 * @return
 * The function sip_X_d() returns non-negative value when successful, or
 * -1 upon an error.
 */
int sip_X_d(su_home_t *home, sip_header_t *h, char *s, int bsiz);

/**Encode a header X.
 *
 * The function sip_X_e() encodes a header structure @a h to the given
 * buffer @a buf.  Even if the given buffer @a buf is NULL or its size @a
 * bufsiz is too small to fit the encoding result, the function returns the
 * number of characters required for the encoding.
 *
 * @param buf    buffer to store the encoding result
 * @param bsiz   size of the encoding buffer
 * @param h      header to be encoded.
 * @param flags  flags controlling the encoding
 * 
 * @note 
 * The encoding buffer size @b must be @b bigger than, not equal to,
 * the actual encoding result.
 *
 * @return
 * The function sip_X_e() returns the number of characters required for the
 * encoding.
 * 
 */
int sip_X_e(char buf[], int bsiz, sip_header_t const *h, int flags);

/** @} */

/**@defgroup sip_status_codes SIP Status Codes and Reason Phrases
 *
 * The macros and variables for the standard SIP status codes and reason
 * phrases are defined in <sofia-sip/sip_status.h>.
 */

/**@defgroup sip_tag SIP Tags
 *
 * SIP headers in tag item lists and tagged argument lists. 
 *
 * The include file <sofia-sip/sip_tag.h> defines tags and tag items for including SIP
 * headers in tag item lists or tagged argument lists. For each header,
 * there is a tag for pointer to header object and an another tag for string
 * containing header value. For example, @From header has tags
 * SIPTAG_FROM() and SIPTAG_FROM_STR().
 *
 * It is also possible to include user-defined headers or non-standard
 * headers using SIPTAG_HEADER_STR().
 *
 * A function taking SIP headers as arguments could be called like this:
 * @code
 * sip_payload_t *payload;
 * ...
 * sip_add_tl(msg, sip, 
 *            SIPTAG_CONTENT_TYPE_STR("text/plain"),
 *            SIPTAG_USER_AGENT(agent->user_agent),
 *            SIPTAG_PAYLOAD(payload),
 *            SIPTAG_HEADER_STR("X-Header: contents\nP-Header: bar"),
 *            TAG_END());
 * ...
 * @endcode
 *
 * In the above fragment, the function sip_add_tl() will add @ContentType
 * and @UserAgent headers along with message payload to the SIP message.
 * The @ContentType header is made with value "text/plain".
 *
 */