nua_tag.c

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

 *   @c -1 (SM_MODE_NULL) Unspecified \n
 *   @c  0 (SM_MODE_PAYLOAD_ONLY) SIP payload only \n
 *   @c  1 (SM_MODE_TUNNEL) SIP tunneling mode \n
 *   @c  2 (SM_MODE_SIPFRAG) SIPfrag protection
 *
 * Corresponding tag taking reference parameter is NUTAG_SMIME_PROTECTION_MODE_REF().
 */
tag_typedef_t nutag_smime_protection_mode = 
  INTTAG_TYPEDEF(smime_protection_mode);

/**@def NUTAG_SMIME_PROTECTION_MODE_REF(x) 
 * Reference tag for NUTAG_SMIME_PROTECTION_MODE().
 */


/**@def NUTAG_SMIME_MESSAGE_DIGEST(x)
 *
 * S/MIME digest algorithm
 *
 * This tag specifies the message digest algorithm to be used in S/MIME.
 *
 * @par Used with
 *    To be implemented
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_SMIME_MESSAGE_DIGEST_REF().
 */
tag_typedef_t nutag_smime_message_digest = 
  STRTAG_TYPEDEF(smime_message_digest);

/**@def NUTAG_SMIME_MESSAGE_DIGEST_REF(x) 
 * Reference tag for NUTAG_SMIME_MESSAGE_DIGEST().
 */


/**@def NUTAG_SMIME_SIGNATURE(x)
 *
 * S/MIME signature algorithm
 *
 * This tag specifies the signature algorithm to be used in S/MIME.
 *
 * @par Used with
 *    To be implemented.
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_SMIME_SIGNATURE_REF().
 */
tag_typedef_t nutag_smime_signature = 
  STRTAG_TYPEDEF(smime_signature);

/**@def NUTAG_SMIME_SIGNATURE_REF(x) 
 * Reference tag for NUTAG_SMIME_SIGNATURE().
 */


/**@def NUTAG_SMIME_KEY_ENCRYPTION(x)
 *
 * S/MIME key encryption algorithm
 *
 * This tag specifies the key encryption algorithm to be used by S/MIME.
 *
 * @par Used with
 *    To be implemented
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_SMIME_KEY_ENCRYPTION_REF().
 */
tag_typedef_t nutag_smime_key_encryption = 
  STRTAG_TYPEDEF(smime_key_encryption);

/**@def NUTAG_SMIME_KEY_ENCRYPTION_REF(x) 
 * Reference tag for NUTAG_SMIME_KEY_ENCRYPTION().
 */


/**@def NUTAG_SMIME_MESSAGE_ENCRYPTION(x)
 *
 * S/MIME message encryption algorithm
 *
 * This tag specifies the message encryption algorithm to be used in S/MIME.
 *
 * @par Used with
 *    To be implemented.
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_SMIME_MESSAGE_ENCRYPTION_REF().
 */
tag_typedef_t nutag_smime_message_encryption = 
  STRTAG_TYPEDEF(smime_message_encryption);

/**@def NUTAG_SMIME_MESSAGE_ENCRYPTION_REF(x) 
 * Reference tag for NUTAG_SMIME_MESSAGE_ENCRYPTION().
 */


/**@def NUTAG_SIPS_URL(x)
 *
 * Local SIPS url.
 *
 * The application can specify an alternative local address for
 * NUA user agent engine. Usually the alternative address is a
 * secure SIP URI (SIPS) used with TLS transport.
 *
 * @par Used with
 *    nua_create()
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_SIPS_URL_REF().
 */
tag_typedef_t nutag_sips_url = URLTAG_TYPEDEF(sips_url);

/**@def NUTAG_SIPS_URL_REF(x) 
 * Reference tag for NUTAG_SIPS_URL().
 */


/**@def NUTAG_CERTIFICATE_DIR(x)
 *
 * X.500 certificate directory
 *
 * @par Used with
 *    nua_create()
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *    NULL terminated pathname of directory containing agent.pem and cafile.pem files.
 *
 * Corresponding tag taking reference parameter is NUTAG_CERTIFICATE_DIR_REF().
 */
tag_typedef_t nutag_certificate_dir = STRTAG_TYPEDEF(certificate_dir);

/**@def NUTAG_CERTIFICATE_DIR_REF(x) 
 * Reference tag for NUTAG_CERTIFICATE_DIR().
 */


/**@def NUTAG_CERTIFICATE_PHRASE(x)
 *
 * Certificate phrase
 *
 * @par Used with
 *    Currently not processed by NUA
 *
 * @par Parameter type
 *    char const *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_CERTIFICATE_PHRASE_REF().
 */
tag_typedef_t nutag_certificate_phrase = STRTAG_TYPEDEF(certificate_phrase);

/**@def NUTAG_CERTIFICATE_PHRASE_REF(x) 
 * Reference tag for NUTAG_CERTIFICATE_PHRASE().
 */

extern msg_hclass_t sip_route_class[];

/**@def NUTAG_INITIAL_ROUTE(x)
 *
 * Specify initial route set.
 *
 * The initial route set is used instead or or in addition to the outbound
 * proxy URL given by NUTAG_PROXY(). The NUTAG_INITIAL_ROUTE() accepts a
 * list of parsed @Route header structures, NUTAG_INITIAL_ROUTE_STR() an
 * unparsed string. 
 * 
 * If a tag list contains multiple NUTAG_INITIAL_ROUTE() or
 * NUTAG_INITIAL_ROUTE_STR() tags, the route set is constructed from them
 * all.
 *
 * The initial route is inserted into request message before the route
 * entries set with SIPTAG_ROUTE() or SIPTAG_ROUTE_STR().
 *
 * @par Used with
 *    nua_set_params() \n
 *    nua_set_hparams() \n
 *    any handle-specific nua call
 *
 * @par Parameter type
 *    sip_route_t const *
 *
 * @par Values
 *    Linked list of #sip_route_t structures
 *
 * Corresponding tag taking reference parameter is NUTAG_INITIAL_ROUTE_REF().
 *
 * @NEW_1_12_7.
 */
tag_typedef_t nutag_initial_route = SIPEXTHDRTAG_TYPEDEF(initial_route, route);

/**@def NUTAG_INITIAL_ROUTE_REF(x) 
 * Reference tag for NUTAG_INITIAL_ROUTE().
 */


/**@def NUTAG_INITIAL_ROUTE_STR(x)
 *
 * Specify initial route set.
 *
 * The initial route set is used instead or or in addition to the outbound
 * proxy URL given by NUTAG_PROXY(). The NUTAG_INITIAL_ROUTE() accepts a
 * list of parsed @Route header structures, NUTAG_INITIAL_ROUTE_STR() a
 * unparsed string containing route URIs, quoted with <> and separated by
 * commas.
 *
 * Please note that the syntax requires <> around the @Route URIs if they
 * contain parameters, e.g., "lr". 
 *
 * If a tag list contains multiple NUTAG_INITIAL_ROUTE() or
 * NUTAG_INITIAL_ROUTE_STR() tags, the route set is constructed from them
 * all. 
 *
 * The initial route set can be reset with NUTAG_INITIAL_ROUTE(NULL).
 *
 * If a tag list of a request contains SIPTAG_ROUTE() or
 * SIPTAG_ROUTE_STR() tags, the resulting route set will contain first the
 * initial route entries followed by the route URIs given with the
 * SIPTAG_ROUTE()/SIPTAG_ROUTE_STR() tags.
 *
 * @par Used with
 *    nua_set_params() \n
 *    nua_set_hparams() \n
 *    any handle-specific nua call
 *
 * @par Parameter type
 *    sip_route_t const *
 *
 * @par Values
 *    Linked list of #sip_route_t structures
 *
 * Corresponding tag taking reference parameter is NUTAG_INITIAL_ROUTE_STR_REF().
 *
 * @NEW_1_12_7.
 */
tag_typedef_t nutag_initial_route_str = STRTAG_TYPEDEF(inital_route_str);

/**@def NUTAG_INITIAL_ROUTE_STR_REF(x) 
 * Reference tag for NUTAG_INITIAL_ROUTE_STR().
 */


/**@def NUTAG_REGISTRAR(x)
 *
 * Registrar URL
 *
 * @par Used with
 *    nua_register()   \n
 *    nua_set_params() \n
 *    nua_get_params()
 *
 * @par Parameter type
 *    url_string_t const * (either char const * or url_t *)
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_REGISTRAR_REF().
 */
tag_typedef_t nutag_registrar = URLTAG_TYPEDEF(registrar);

/**@def NUTAG_REGISTRAR_REF(x) 
 * Reference tag for NUTAG_REGISTRAR().
 */


/**@def NUTAG_IDENTITY(x)
 *
 * Registration handle (used with requests and nua_respond()) (NOT YET IMPLEMENTED)
 *
 * When a new request is made or new call is responded, a new identity can
 * be selected with NUTAG_IDENTITY(). The identity comprises of @b From
 * header, initial route set, local contact header and media tags associated
 * with it, soa handle and so on. User can make multiple registrations using
 * multiple identities.
 *
 * @par Used with
 *    nua_invite()
 *
 * @par Parameter type
 *    nua_handle_t *
 *
 * @par Values
 *
 * Corresponding tag taking reference parameter is NUTAG_IDENTITY_REF().
 */
tag_typedef_t nutag_identity = PTRTAG_TYPEDEF(identity);

/**@def NUTAG_IDENTITY_REF(x) 
 * Reference tag for NUTAG_IDENTITY().
 */


/**@def NUTAG_M_DISPLAY(x)
 *
 * Display name for @Contact.
 *
 * Specify display name for the Contact header URI generated for
 * registration request and dialog-creating requests/responses.
 *
 * Note that the display name is not included the request-URI when proxy
 * forwards the request towards the user-agent.
 *
 * @par Used with
 *    nua_register(), nua_set_hparams(), nua_set_params().
 *    nua_invite(), nua_respond(), nua_subscribe(), nua_notify()
 *
 * @par Parameter type
 *    string (char *)
 *
 * @par Values
 *    Valid display name.
 *
 * @sa NUTAG_M_USERNAME(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(),
 * NUTAG_CALLEE_CAPS().
 *
 * Corresponding tag taking reference parameter is NUTAG_M_DISPLAY_REF().
 *
 * @since New in @VERSION_1_12_2.
 */
tag_typedef_t nutag_m_display = STRTAG_TYPEDEF(m_display);

/**@def NUTAG_M_DISPLAY_REF(x) 
 * Reference tag for NUTAG_M_DISPLAY().
 */


/**@def NUTAG_M_USERNAME(x)
 *
 * Username prefix for @Contact.
 *
 * Specify username part for the Contact header URI generated for
 * registration request and dialog-creating requests/responses.
 *
 * Using username, application can make multiple registrations using
 * multiple identities, or it can distinguish between different logical
 * destinations.
 *
 * @par Used with
 *    nua_register(), nua_set_hparams(), nua_set_params().
 *    nua_invite(), nua_respond(), nua_subscribe(), nua_notify()
 *
 * @par Parameter type
 *    string (char *)
 *
 * @par Values
 *    Valid SIP username.
 *
 * @sa NUTAG_M_DISPLAY(), NUTAG_M_PARAMS(), NUTAG_M_FEATURES(),
 * NUTAG_CALLEE_CAPS().
 *
 * Corresponding tag taking reference parameter is NUTAG_M_USERNAME_REF().
 *
 * @since New in @VERSION_1_12_2.
 */
tag_typedef_t nutag_m_username = STRTAG_TYPEDEF(m_username);

/**@def NUTAG_M_USERNAME_REF(x) 
 * Reference tag for NUTAG_M_USERNAME().
 */


/**@def NUTAG_M_PARAMS(x)
 *
 * URL parameters for @Contact.
 *
 * Specify URL parameters for the @Contact header URI generated for
 * registration request and dialog-creating requests/responses.
 *
 * Please note that some proxies may remove even the non-transport
 * parameters from the request-URI when they forward the request towards
 * user-agent.
 *
 * @par Used with
 *    nua_register(), nua_set_hparams(), nua_set_params(), 
 *    nua_invite(), nua_respond(), nua_subscribe(), nua_notify()
 *
 * @par Parameter type
 *    string (char *)
 *
 * @par Values
 *    Semicolon-separated URL parameters.
 *
 * @sa NUTAG_M_DISPLAY(), NUTAG_M_USERNAME(), NUTAG_M_FEATURES(),
 * NUTAG_CALLEE_CAPS().
 *
 * Corresponding tag taking reference parameter is NUTAG_M_PARAMS_REF().
 *
 * @since New in @VERSION_1_12_2.
 */
tag_typedef_t nutag_m_params = STRTAG_TYPEDEF(m_params);

/**@def NUTAG_M_PARAMS_REF(x) 
 * Reference tag for NUTAG_M_PARAMS().
 */


/**@def NUTAG_M_FEATURES(x)
 *
 * Header parameters for @Contact used in registration.
 *
 * Specify header parameters for the @Contact header generated for
 * registration request and dialog-creating requests/responses. Such header
 * parameters include "q", indicating preference for the @Contact URI, and
 * "expires", indicating the desired expiration time for the registration.
 *
 * Additional header parameters are typically media feature tags, specified in
 * @RFC3840. If NUTAG_CALLEE_CAPS(1) is specified, additional @Contact header
 * parameters are generated based on SDP capabilities and SIP @Allow header.
 *
 * When using the "outbound" extension option, the stack will also add
 * "+sip.instance" and "reg-id" header parameters to the @Contact.
 *
 * @par Used with
 *    nua_register(), nua_set_hparams(), nua_set_params()
 *
 * @par Parameter type
 *    string (char *)
 *
 * @par Values
 *    Semicolon-separated SIP header parameters.
 *
 * @sa NUTAG_M_DISPLAY(), NUTAG_M_USERNAME(), NUTAG_M_PARAMS(),
 * NUTAG_CALLEE_CAPS(), NUTAG_IDENTITY().
 *
 * Corresponding tag taking reference parameter is NUTAG_M_FEATURES_REF().
 *
 * @since New in @VERSION_1_12_2.
 */
tag_typedef_t nutag_m_features = STRTAG_TYPEDEF(m_features);

/**@def NUTAG_M_FEATURES_REF(x) 
 * Reference tag for NUTAG_M_FEATURES().
 */


/**@def NUTAG_INSTANCE(x)
 *
 * Intance identifier.
 *
 * @par Used with
 *    nua_create(), nua_set_params(), nua_get_params(), 
 *    nua_register()
 *
 * @par Parameter type
 *    char const *
 *
 * @par Value
 *    urn:uuid string, a globally unique identifier for this user-agent
 *    instance.
 *
 * Corresponding tag taking reference parameter is NUTAG_INSTANCE_REF().
 */