nta_tag.c 58.8 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2 3 4 5 6 7
/*
 * This file is part of the Sofia-SIP package
 *
 * Copyright (C) 2005 Nokia Corporation.
 *
 * Contact: Pekka Pessi <pekka.pessi@nokia.com>
 *
8
 * This library is free software; you can redistribute it and/or
Pekka Pessi's avatar
Pekka Pessi committed
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 *
 */

/**@CFILE nta_tag.c
 * @brief Tags for Nokia SIP Transaction API
 *
Pekka Pessi's avatar
Pekka Pessi committed
28
 * @note This file is used to automatically generate
Pekka Pessi's avatar
Pekka Pessi committed
29 30 31 32 33 34 35 36 37 38 39 40 41 42
 * nta_tag_ref.c and nta_tag_dll.c
 *
 * @author Pekka Pessi <Pekka.Pessi@nokia.com>
 *
 * @date Created: Tue Jul 24 22:28:34 2001 ppessi
 */

#include "config.h"

#include <string.h>
#include <assert.h>

#define TAG_NAMESPACE "nta"

43 44 45 46
#include "sofia-sip/nta_tag.h"
#include <sofia-sip/su_tag_class.h>
#include <sofia-sip/sip_tag_class.h>
#include <sofia-sip/url_tag_class.h>
Pekka Pessi's avatar
Pekka Pessi committed
47

48
#include <sofia-sip/sip_protos.h>
Pekka Pessi's avatar
Pekka Pessi committed
49

50 51
tag_typedef_t ntatag_any = NSTAG_TYPEDEF(*);

Pekka Pessi's avatar
Pekka Pessi committed
52 53
/**@def NTATAG_MCLASS(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
54
 * Message class used by NTA.
Pekka Pessi's avatar
Pekka Pessi committed
55 56 57 58 59
 *
 * The nta can use a custom or extended parser created with
 * msg_mclass_clone().
 *
 * @par Used with
60 61
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
62 63 64 65 66 67 68 69
 *
 * @par Parameter type
 *    pointer to #msg_mclass_t.
 *
 * @par Values
 *    - custom or extended parser created with msg_mclass_clone()
 *    - NULL - use default parser
 *
70 71 72
 * @par Default Value
 *    - Value returned by sip_default_mclass()
 *
Pekka Pessi's avatar
Pekka Pessi committed
73 74
 * @sa NTATAG_SIPFLAGS()
 */
Pekka Pessi's avatar
Pekka Pessi committed
75
tag_typedef_t ntatag_mclass = PTRTAG_TYPEDEF(mclass);
Pekka Pessi's avatar
Pekka Pessi committed
76

Pekka Pessi's avatar
Pekka Pessi committed
77 78
/**@def NTATAG_BAD_REQ_MASK(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
79 80
 * Mask for bad request messages.
 *
Pekka Pessi's avatar
Pekka Pessi committed
81
 * If an incoming request has erroneous headers matching with the mask, nta
Pekka Pessi's avatar
Pekka Pessi committed
82
 * automatically returns a 400 Bad Message response to them.
Pekka Pessi's avatar
Pekka Pessi committed
83 84 85 86
 *
 * If mask ~0U (all bits set) is specified, all requests with any bad header
 * are dropped. By default only the requests with bad headers essential for
 * request processing or proxying are dropped.
Pekka Pessi's avatar
Pekka Pessi committed
87
 *
Pekka Pessi's avatar
Pekka Pessi committed
88
 * @par Used with
89 90
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
91 92 93 94 95 96 97
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - bitwise or of enum #sip_bad_mask values
 *
98 99 100
 * @par Default Value
 * - <code>sip_mask_response | sip_mask_ua | sip_mask_100rel | </code><br>
 *   <code>sip_mask_events | sip_mask_timer | sip_mask_publish</code>
Pekka Pessi's avatar
Pekka Pessi committed
101 102 103 104 105
 * The following headers are considered essential by default:
 * - @ref sip_request \"request line\"", @From, @To, @CSeq, @CallID,
 *   @ContentLength, @Via, @ContentType, @ContentDisposition,
 *   @ContentEncoding, @Supported, @Contact, @Require, @RecordRoute, @RAck,
 *   @RSeq, @Event, @Expires, @SubscriptionState, @SessionExpires,
Pekka Pessi's avatar
Pekka Pessi committed
106
 *   @MinSE, @SIPETag, and @SIPIfMatch.
Pekka Pessi's avatar
Pekka Pessi committed
107
 *
108
 * @sa enum #sip_bad_mask, NTATAG_BAD_RESP_MASK()
Pekka Pessi's avatar
Pekka Pessi committed
109
 */
Pekka Pessi's avatar
Pekka Pessi committed
110
tag_typedef_t ntatag_bad_req_mask = UINTTAG_TYPEDEF(bad_req_mask);
Pekka Pessi's avatar
Pekka Pessi committed
111 112 113

/**@def NTATAG_BAD_RESP_MASK(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
114 115
 * Mask for bad response messages.
 *
Pekka Pessi's avatar
Pekka Pessi committed
116
 * If an incoming response has erroneous headers matching with the mask, nta
Pekka Pessi's avatar
Pekka Pessi committed
117
 * drops the response message.
Pekka Pessi's avatar
Pekka Pessi committed
118 119 120 121
 *
 * If mask ~0U (all bits set) is specified, all responses with any bad header
 * are dropped. By default only the responses with bad headers essential for
 * response processing or proxying are dropped.
Pekka Pessi's avatar
Pekka Pessi committed
122
 *
Pekka Pessi's avatar
Pekka Pessi committed
123
 * @par Used with
124 125
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
126 127 128 129 130 131 132 133 134
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - bitwise or of enum #sip_bad_mask values
 *
 * @sa enum #sip_bad_mask, NTATAG_BAD_REQ_MASK()
 *
135 136 137
 * @par Default Value
 * - <code>sip_mask_response | sip_mask_ua | sip_mask_100rel | </code><br>
 *   <code>sip_mask_events | sip_mask_timer | sip_mask_publish</code>
Pekka Pessi's avatar
Pekka Pessi committed
138 139 140 141
 * The following headers are considered essential by default:
 * - @ref sip_status \"status line\"", @From, @To, @CSeq, @CallID,
 *   @ContentLength, @Via, @ContentType, @ContentDisposition,
 *   @ContentEncoding, @Supported, @Contact, @Require, @RecordRoute, @RAck,
Pekka Pessi's avatar
Pekka Pessi committed
142
 *   @RSeq, @Event, @Expires, @SubscriptionState, @SessionExpires,
Pekka Pessi's avatar
Pekka Pessi committed
143
 *   @MinSE, @SIPETag, and @SIPIfMatch.
Pekka Pessi's avatar
Pekka Pessi committed
144
 */
Pekka Pessi's avatar
Pekka Pessi committed
145 146
tag_typedef_t ntatag_bad_resp_mask = UINTTAG_TYPEDEF(bad_resp_mask);

Pekka Pessi's avatar
Pekka Pessi committed
147 148 149 150 151 152 153 154 155 156 157 158 159 160
/**@def NTATAG_DEFAULT_PROXY(x)
 *
 * URL for (default) proxy.
 *
 * The requests are sent towards the <i>default outbound proxy</i> regardless
 * the values of request-URI or @Route headers in the request. The URL of
 * the default proxy is not added to the request in the @Route header or in
 * the request-URI (against the recommendation of @RFC3261 section 8.1.2).
 *
 * The outbound proxy set by NTATAG_DEFAULT_PROXY() is used even if the
 * dialog had an established route set or registration provided User-Agent
 * with a @ServiceRoute set.
 *
 * @par Used with
161 162
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params(),
Pekka Pessi's avatar
Pekka Pessi committed
163 164 165 166 167 168 169 170 171
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), nta_outgoing_prack(), nta_msg_tsend()
 *
 * @par Parameter type
 *    Pointer to a url_t structure or a string containg a SIP or SIPS URI
 *
 * @par Values
 *    - Valid SIP or SIPS URI
 */
Pekka Pessi's avatar
Pekka Pessi committed
172
tag_typedef_t ntatag_default_proxy = URLTAG_TYPEDEF(default_proxy);
Pekka Pessi's avatar
Pekka Pessi committed
173 174 175 176 177

/**@def NTATAG_CONTACT(x)
 *
 * Contact used by NTA.
 */
Pekka Pessi's avatar
Pekka Pessi committed
178
tag_typedef_t ntatag_contact = SIPHDRTAG_NAMED_TYPEDEF(contact, contact);
Pekka Pessi's avatar
Pekka Pessi committed
179 180 181 182 183

/** @def NTATAG_TARGET(x)
 *
 * Dialog target (contact) used by NTA.
 */
Pekka Pessi's avatar
Pekka Pessi committed
184
tag_typedef_t ntatag_target = SIPHDRTAG_NAMED_TYPEDEF(target, contact);
Pekka Pessi's avatar
Pekka Pessi committed
185

Pekka Pessi's avatar
Pekka Pessi committed
186
/** @def NTATAG_ALIASES(x)
Pekka Pessi's avatar
Pekka Pessi committed
187
 *
Pekka Pessi's avatar
Pekka Pessi committed
188
 * Aliases used by NTA.
Pekka Pessi's avatar
Pekka Pessi committed
189 190
 * @deprecated
 */
Pekka Pessi's avatar
Pekka Pessi committed
191 192
tag_typedef_t ntatag_aliases = SIPHDRTAG_NAMED_TYPEDEF(aliases, contact);

Pekka Pessi's avatar
Pekka Pessi committed
193 194 195 196 197 198 199 200 201 202 203 204 205 206
/**@def NTATAG_METHOD(x)
 *
 * Method name.
 *
 * Create a dialogless #nta_leg_t object matching only requests with
 * the specified method.
 *
 * @par Used with
 *   nta_leg_tcreate()
 *
 * @par Parameter type
 *    String containing method name.
 *
 * @par Values
207
 *    - A SIP method name (e.g., "SUBSCRIBE").
Pekka Pessi's avatar
Pekka Pessi committed
208
 *
209 210
 * @par Default Value
 *    - None (i.e., all requests methods match with the leg)
Pekka Pessi's avatar
Pekka Pessi committed
211
 *
Pekka Pessi's avatar
Pekka Pessi committed
212
 */
Pekka Pessi's avatar
Pekka Pessi committed
213
tag_typedef_t ntatag_method = STRTAG_TYPEDEF(method);
Pekka Pessi's avatar
Pekka Pessi committed
214 215 216 217 218 219 220 221 222 223 224 225 226

/**@def NTATAG_BRANCH_KEY(x)
 *
 * Branch ID to the topmost @Via header.
 *
 * The NTA generates a random branch ID for the topmost @Via header by default.
 * The application can the branch by itself, for intance, if it wants to
 * create a @RFC2543-era transaction.
 *
 * Note that according to @RFC3261 the branch ID must start with "z9hG4bK".
 *
 * @par Used with
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
227
 *    nta_outgoing_tcancel(), nta_outgoing_prack(), nta_msg_tsend()
Pekka Pessi's avatar
Pekka Pessi committed
228 229 230 231 232
 *
 * @par Parameter type
 *    string
 *
 * @par Value
Pekka Pessi's avatar
Pekka Pessi committed
233
 * - The "branch" ID to to insert into topmost @Via header of the
234 235 236 237 238 239
 *   request to be sent
 *
 * @par Default Value
 *  - A token is generated, either by random when a client transaction is
 *    created or by hashing the headers and contents of the request when
 *    request is sent statelessly
Pekka Pessi's avatar
Pekka Pessi committed
240 241 242
 *
 * @sa @RFC3261 section 8.1.1.7
 */
Pekka Pessi's avatar
Pekka Pessi committed
243
tag_typedef_t ntatag_branch_key = STRTAG_TYPEDEF(branch_key);
Pekka Pessi's avatar
Pekka Pessi committed
244 245 246

/**@def NTATAG_ACK_BRANCH(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
247
 * Branch of the transaction to ACK.
Pekka Pessi's avatar
Pekka Pessi committed
248 249 250 251 252 253 254
 *
 * When creating a ACK transaction, the application should provide the
 * branch parameter from the original transaction to the stack. The ACK
 * transaction object then receives all the retransmitted 2XX responses to
 * the original INVITE transaction.
 *
 * @par Used with
255
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate()
Pekka Pessi's avatar
Pekka Pessi committed
256 257 258 259 260 261 262
 *
 * @par Parameter type
 *    string
 *
 * @par Value
 *    - "branch" ID used to store the ACK transaction in the nta hash
 *      table for outgoing client transaction
263 264 265 266
 *
 * @par Default Value
 *  - The INVITE transaction is looked from the hash table using the @CallID,
 *    @CSeq, @From and @To tags and its branch ID is used
Pekka Pessi's avatar
Pekka Pessi committed
267
 */
Pekka Pessi's avatar
Pekka Pessi committed
268
tag_typedef_t ntatag_ack_branch = STRTAG_TYPEDEF(ack_branch);
Pekka Pessi's avatar
Pekka Pessi committed
269 270 271

/**@def NTATAG_COMP(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
272
 * Compression algorithm.
Pekka Pessi's avatar
Pekka Pessi committed
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291
 *
 * Set compression algorithm for request as described in @RFC3486.
 *
 * @note This tag is has no effect without a compression plugin.
 *
 * @par Used with
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), nta_outgoing_prack(), nta_msg_tsend()
 *
 * @par
 * Note that NTATAG_COMP(NULL) can be used with nta_incoming_set_params()
 * and nta_incoming_treply(), too. It indicates that the response is sent
 * uncompressed, no matter what the client has in @a comp parameter of @Via
 * header.
 *
 * @par Parameter type
 *    string
 *
 * @par Values
292 293 294 295
 *    - name of the compression algorithm
 *
 * @par Default Value
 *    - "sigcomp"
Pekka Pessi's avatar
Pekka Pessi committed
296 297 298 299 300
 *
 * @sa @RFC3320, @RFC3486, TPTAG_COMPARTMENT(),
 * NTATAG_SIGCOMP_ALGORITHM(), NTATAG_SIGCOMP_AWARE(),
 * NTATAG_SIGCOMP_CLOSE(), NTATAG_SIGCOMP_OPTIONS()
 */
Pekka Pessi's avatar
Pekka Pessi committed
301
tag_typedef_t ntatag_comp = CSTRTAG_TYPEDEF(comp);
Pekka Pessi's avatar
Pekka Pessi committed
302 303 304

/**@def NTATAG_MSG(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
305
 * Pass a SIP message to treply()/tcreate() functions.
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320
 *
 * @par Used with
 *    nta_outgoing_tcreate(), nta_incoming_treply()
 *
 * @par Parameter type
 *    #msg_t
 *
 * @par Values
 * - A message object which will be completed, serialized and encoded.
 *   Note that the functions modify directly the message.
 *
 * @par Default Value
 * - A new  message object is created and populated by the function call.
 *
 * @sa msg_copy(), msg_dup(), msg_create(), sip_default_mclass()
Pekka Pessi's avatar
Pekka Pessi committed
321
 */
Pekka Pessi's avatar
Pekka Pessi committed
322
tag_typedef_t ntatag_msg = PTRTAG_TYPEDEF(msg);
Pekka Pessi's avatar
Pekka Pessi committed
323 324 325

/**@def NTATAG_TPORT(x)
 *
326 327 328 329
 * Pass a transport object. The transport object is used to send the request
 * or response message(s).
 *
 * @par Used with
Pekka Pessi's avatar
Pekka Pessi committed
330
 *    nta_outgoing_tcreate(), nta_outgoing_mcreate(), nta_outgoing_tcancel(),
331 332 333 334 335 336 337 338 339 340 341 342
 *    nta_incoming_create(), nta_msg_tsend(), nta_msg_mreply()
 *
 * @par Parameter type
 *  - #tport_t
 *
 * @par Values
 * - A pointer to the transport object. Note that a new reference to the transport
 *   is created.
 *
 * @par Default Value
 * - The transport is selected by resolving the outbound URI (specified with
 *   NTATAG_DEFAULT_PROXY(), the topmost @Route URI or Request-URI.
Pekka Pessi's avatar
Pekka Pessi committed
343
 */
Pekka Pessi's avatar
Pekka Pessi committed
344
tag_typedef_t ntatag_tport = PTRTAG_TYPEDEF(tport);
Pekka Pessi's avatar
Pekka Pessi committed
345 346 347

/**@def NTATAG_SMIME(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
348
 * Provide S/MIME context to NTA.
Pekka Pessi's avatar
Pekka Pessi committed
349
 *
Pekka Pessi's avatar
Pekka Pessi committed
350
 * @todo S/MIME is not implemented.
Pekka Pessi's avatar
Pekka Pessi committed
351
 */
Pekka Pessi's avatar
Pekka Pessi committed
352
tag_typedef_t ntatag_smime = PTRTAG_TYPEDEF(smime);
Pekka Pessi's avatar
Pekka Pessi committed
353 354 355 356

/**@def NTATAG_REMOTE_CSEQ(x)
 *
 * Remote CSeq number.
357 358 359 360 361 362 363 364 365 366 367 368 369
 *
 * Specify remote command sequence number for a #nta_leg_t dialog object. If
 * an request is received matching with the dialog but with @CSeq number
 * less than the remote sequence number associated with the dialog, a <i>500
 * Internal Server Error</i> response is automatically returned to the client.
 *
 * @par Used with
 *   nta_leg_tcreate()
 *
 * @par Parameter type
 *   - uint32_t
 *
 * @par Values
Pekka Pessi's avatar
Pekka Pessi committed
370
 *    - Remote command sequence number
371 372 373 374
 *
 * @par Default Value
 *    - Initially 0, then determined by the received requests
 *
Pekka Pessi's avatar
Pekka Pessi committed
375
 */
Pekka Pessi's avatar
Pekka Pessi committed
376 377
tag_typedef_t ntatag_remote_cseq = UINTTAG_TYPEDEF(remote_cseq);

Pekka Pessi's avatar
Pekka Pessi committed
378 379
/**@def NTATAG_MAXSIZE(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
380
 * Maximum size of incoming message.
Pekka Pessi's avatar
Pekka Pessi committed
381 382 383 384 385 386
 *
 * If the size of an incoming request message would exceed the
 * given limit, the stack will automatically respond with <i>413 Request
 * Entity Too Large</i>.
 *
 * @par Used with
387 388
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
389 390
 *
 * @par Parameter type
Pekka Pessi's avatar
Pekka Pessi committed
391
 *    - #usize_t
Pekka Pessi's avatar
Pekka Pessi committed
392 393 394
 *
 * @par Values
 *    - Maximum acceptable size of an incoming request message.
395 396 397
 *
 * @par Default Value
 *    - 2097152 (bytes or 2 megabytes)
Pekka Pessi's avatar
Pekka Pessi committed
398 399 400
 *
 * @sa msg_maxsize(), NTATAG_UDP_MTU()
 */
Pekka Pessi's avatar
Pekka Pessi committed
401
tag_typedef_t ntatag_maxsize = USIZETAG_TYPEDEF(maxsize);
Pekka Pessi's avatar
Pekka Pessi committed
402

Michael Jerris's avatar
Michael Jerris committed
403 404
/**@def NTATAG_MAX_PROCEEDING(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
405
 * Maximum size of proceeding queue.
Michael Jerris's avatar
Michael Jerris committed
406 407
 *
 * If the size of the proceedng message queue would exceed the
Pekka Pessi's avatar
Pekka Pessi committed
408
 * given limit, the stack will automatically respond with <i>503
Michael Jerris's avatar
Michael Jerris committed
409 410 411 412 413 414 415
 * Service Unavailable</i>.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
Pekka Pessi's avatar
Pekka Pessi committed
416
 *    - #usize_t
Michael Jerris's avatar
Michael Jerris committed
417 418 419 420 421 422 423
 *
 * @par Values
 *    - Maximum acceptable size of a queue (size_t).
 *
 */
tag_typedef_t ntatag_max_proceeding = USIZETAG_TYPEDEF(max_proceeding);

Pekka Pessi's avatar
Pekka Pessi committed
424 425
/**@def NTATAG_UDP_MTU(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
426
 * Maximum size of outgoing UDP request.
Pekka Pessi's avatar
Pekka Pessi committed
427 428 429 430 431 432 433 434
 *
 * The maximum UDP request size is used to control use of UDP with overtly
 * large messages. The IETF requires that the SIP requests over 1300 bytes
 * are sent over congestion-controlled transport such as TCP. If a SIP
 * message size exceeds the UDP MTU, the TCP is tried instead of UDP. (If
 * the TCP connection is refused, the stack reverts back to UDP).
 *
 * @par Used with
435 436
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
437 438
 *
 * @par Parameter type
439
 *    - unsigned
Pekka Pessi's avatar
Pekka Pessi committed
440 441 442 443
 *
 * @par Values
 *    - Maximum size of an outgoing UDP request
 *
444 445 446
 * @par Default Value
 *    - 1300 (bytes)
 *
Pekka Pessi's avatar
Pekka Pessi committed
447 448
 * @sa @RFC3261 section 18.1.1, NTATAG_MAXSIZE()
 */
Pekka Pessi's avatar
Pekka Pessi committed
449
tag_typedef_t ntatag_udp_mtu = UINTTAG_TYPEDEF(udp_mtu);
Pekka Pessi's avatar
Pekka Pessi committed
450 451 452

/**@def NTATAG_MAX_FORWARDS(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
453
 * Default value for @MaxForwards header.
Pekka Pessi's avatar
Pekka Pessi committed
454 455 456 457 458 459
 *
 * The default value of @MaxForwards header added to the requests. The
 * initial value recommended by @RFC3261 is 70, but usually SIP proxies use
 * much lower default value, such as 24.
 *
 * @par Used with
460 461
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
462 463 464 465 466 467 468
 *
 * @par Parameter type
 *    unsigned
 *
 * @par Values
 *    - Default value added to the @MaxForwards header in the sent requests
 *
469 470 471
 * @par Default Value
 *    - 70 (hops)
 *
Pekka Pessi's avatar
Pekka Pessi committed
472 473
 * @since New in @VERSION_1_12_2.
 */
474
tag_typedef_t ntatag_max_forwards = UINTTAG_TYPEDEF(max_forwards);
Pekka Pessi's avatar
Pekka Pessi committed
475 476 477

/**@def NTATAG_SIP_T1(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
478
 * Initial retransmission interval (in milliseconds)
Pekka Pessi's avatar
Pekka Pessi committed
479 480 481 482 483 484
 *
 * Set the T1 retransmission interval used by the SIP transaction engine. The
 * T1 is the initial duration used by request retransmission timers A and E
 * (UDP) as well as response retransmission timer G.
 *
 * @par Used with
485 486
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
487 488 489 490 491
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
Pekka Pessi's avatar
Pekka Pessi committed
492
 *    - Value of SIP T1 in milliseconds
Pekka Pessi's avatar
Pekka Pessi committed
493
 *
494 495 496 497
 * @par Default Value
 *    - #NTA_SIP_T1 or 500 (milliseconds)
 *
 * @sa @RFC3261 appendix A, #NTA_SIP_T1, NTATAG_SIP_T1X4(), NTATAG_SIP_T1(), NTATAG_SIP_T4()
Pekka Pessi's avatar
Pekka Pessi committed
498
 */
Pekka Pessi's avatar
Pekka Pessi committed
499
tag_typedef_t ntatag_sip_t1 = UINTTAG_TYPEDEF(sip_t1);
Pekka Pessi's avatar
Pekka Pessi committed
500 501 502

/**@def NTATAG_SIP_T1X64(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
503
 * Transaction timeout (defaults to T1 * 64).
Pekka Pessi's avatar
Pekka Pessi committed
504 505
 *
 * Set the T1x64  timeout value used by the SIP transaction engine. The T1x64 is
Pekka Pessi's avatar
Pekka Pessi committed
506
 * duration used for timers B, F, H, and J (UDP) by the SIP transaction engine.
Pekka Pessi's avatar
Pekka Pessi committed
507 508
 * The timeout value T1x64 can be adjusted separately from the initial
 * retransmission interval T1, which is set with NTATAG_SIP_T1().
Pekka Pessi's avatar
Pekka Pessi committed
509
 *
Pekka Pessi's avatar
Pekka Pessi committed
510 511 512
 * The default value for T1x64 is 64 times value of T1, or 32000 milliseconds.
 *
 * @par Used with
513 514
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
515 516 517 518 519 520 521
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - Value of T1x64 in milliseconds
 *
522 523 524 525
 * @par Default Value
 *    - 64 * #NTA_SIP_T1 or 32000 (milliseconds)
 *
 * @sa @RFC3261 appendix A, #NTA_SIP_T1, NTATAG_SIP_T1(), NTATAG_SIP_T2(), NTATAG_SIP_T4()
Pekka Pessi's avatar
Pekka Pessi committed
526 527
 *
 */
Pekka Pessi's avatar
Pekka Pessi committed
528
tag_typedef_t ntatag_sip_t1x64 = UINTTAG_TYPEDEF(sip_t1x64);
Pekka Pessi's avatar
Pekka Pessi committed
529 530 531

/**@def NTATAG_SIP_T2(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
532
 * Maximum retransmission interval (in milliseconds)
Pekka Pessi's avatar
Pekka Pessi committed
533 534 535
 *
 * Set the maximum retransmission interval used by the SIP transaction
 * engine. The T2 is the maximum duration used for the timers E (UDP) and G
Pekka Pessi's avatar
Pekka Pessi committed
536
 * by the SIP transaction engine. Note that the timer A is not capped by T2.
Pekka Pessi's avatar
Pekka Pessi committed
537 538 539 540
 * Retransmission interval of INVITE requests grows exponentially until the
 * timer B fires.
 *
 * @par Used with
541 542
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
543 544 545 546 547
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
Pekka Pessi's avatar
Pekka Pessi committed
548
 *    - Value of SIP T2 in milliseconds
Pekka Pessi's avatar
Pekka Pessi committed
549
 *
550 551 552 553
 * @par Default Value
 *    - #NTA_SIP_T2 or 4000 (milliseconds)
 *
 * @sa @RFC3261 appendix A, #NTA_SIP_T2, NTATAG_SIP_T1(), NTATAG_SIP_T1X4(), NTATAG_SIP_T4()
Pekka Pessi's avatar
Pekka Pessi committed
554
 */
Pekka Pessi's avatar
Pekka Pessi committed
555
tag_typedef_t ntatag_sip_t2 = UINTTAG_TYPEDEF(sip_t2);
Pekka Pessi's avatar
Pekka Pessi committed
556 557 558

/**@def NTATAG_SIP_T4(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
559
 * Transaction lifetime (in milliseconds)
Pekka Pessi's avatar
Pekka Pessi committed
560 561 562 563 564 565 566
 *
 * Set the lifetime for completed transactions used by the SIP transaction
 * engine. A completed transaction is kept around for the duration of T4 in
 * order to catch late responses. The T4 is the maximum duration for the
 * messages to stay in the network and the duration of SIP timer K.
 *
 * @par Used with
567 568
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
569 570 571 572 573 574 575
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    - Value of SIP T4 in milliseconds
 *
576 577 578 579
 * @par Default Value
 *    - #NTA_SIP_T4 or 4000 (milliseconds)
 *
 * @sa @RFC3261 appendix A, #NTA_SIP_T4, NTATAG_SIP_T1(), NTATAG_SIP_T1X4(), NTATAG_SIP_T2()
Pekka Pessi's avatar
Pekka Pessi committed
580
 */
Pekka Pessi's avatar
Pekka Pessi committed
581
tag_typedef_t ntatag_sip_t4 = UINTTAG_TYPEDEF(sip_t4);
Pekka Pessi's avatar
Pekka Pessi committed
582 583 584 585 586 587 588 589 590 591 592 593

/**@def NTATAG_PROGRESS(x)
 *
 * Progress timer for User-Agents (interval for retranmitting 1XXs).
 *
 * The UAS should retransmit preliminary responses to the INVITE
 * transactions every minute in order to re-set the timer C within the
 * intermediate proxies.
 *
 * The default value for the progress timer is 60000.
 *
 * @par Used with
594 595
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
596 597 598 599 600 601 602
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    Value of progress timer in milliseconds.
 *
603 604 605
 * @par Default Value
 *   - 90000 (milliseconds, 1.5 minutes)
 *
Pekka Pessi's avatar
Pekka Pessi committed
606 607 608
 * @sa @RFC3261 sections 13.3.1.1, 16.7 and 16.8, NTATAG_TIMER_C(),
 * NTATAG_SIP_T1(), NTATAG_SIP_T1X4(), NTATAG_SIP_T2(), NTATAG_SIP_T4()
 */
Pekka Pessi's avatar
Pekka Pessi committed
609
tag_typedef_t ntatag_progress = UINTTAG_TYPEDEF(progress);
Pekka Pessi's avatar
Pekka Pessi committed
610 611 612 613 614 615 616 617 618 619 620 621

/**@def NTATAG_TIMER_C(x)
 *
 * Value for timer C in milliseconds.
 *
 * By default the INVITE transaction will not timeout after a preliminary
 * response has been received. However, an intermediate proxy can timeout
 * the transaction using timer C. Timer C is reset every time a response
 * belonging to the transaction is received.
 *
 * The default value for the timer C is 185000 milliseconds (3 minutes and 5
 * seconds). By default, timer C is not run on user agents (if NTATAG_UA(1)
622
 * without NTATAG_TIMER_C() is given).
Pekka Pessi's avatar
Pekka Pessi committed
623 624
 *
 * @par Used with
625 626
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
627 628 629 630 631 632 633 634
 *
 * @par Parameter type
 *    unsigned int
 *
 * @par Values
 *    Value of SIP timer C in milliseconds. The default value is used
 *    instead if NTATAG_TIMER_C(0) is given.
 *
635 636 637
 * @par Default Value
 *   - 180000 (milliseconds, 3 minutes)
 *
Pekka Pessi's avatar
Pekka Pessi committed
638 639 640 641 642 643
 * @sa @RFC3261 sections 13.3.1.1, 16.7 and 16.8,
 * NTATAG_UA(1), NTATAG_TIMER_C(),
 * NTATAG_SIP_T1(), NTATAG_SIP_T1X4(), NTATAG_SIP_T2(), NTATAG_SIP_T4()
 *
 * @NEW_1_12_7.
 */
644
tag_typedef_t ntatag_timer_c = UINTTAG_TYPEDEF(timer_c);
Pekka Pessi's avatar
Pekka Pessi committed
645

Pekka Pessi's avatar
Pekka Pessi committed
646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670
/**@def NTATAG_GRAYLIST(x)
 *
 * Avoid failed servers.
 *
 * The NTATAG_GRAYLIST() provides the time that the servers are avoided
 * after a request sent to them has been failed. Avoiding means that if a
 * domain provides multiple servers, the failed servers are tried last.
 *
 * @par Used with
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
 *
 * @par Parameter type
 *     unsigned int
 *
 * @par Values
 *    - Number of seconds that server is kept in graylist, from 0 to 86400.
 *
 * @par Default Value
 *    - 600 (graylist server for 10 minutes)
 *
 * @sa NTATAG_BLACKLIST(), NTATAG_TIMEOUT_408()
 */
tag_typedef_t ntatag_graylist = UINTTAG_TYPEDEF(graylist);

Pekka Pessi's avatar
Pekka Pessi committed
671 672
/**@def NTATAG_BLACKLIST(x)
 *
673
 * Add Retry-After header to error responses returned to application.
Pekka Pessi's avatar
Pekka Pessi committed
674 675 676 677 678 679 680
 *
 * The NTATAG_BLACKLIST() provides a default value for @RetryAfter header
 * added to the internally generated responses such as <i>503 DNS Error</i>
 * or <i>408 Timeout</i>. The idea is that the application can retain its
 * current state and retry the operation after a while.
 *
 * @par Used with
681 682
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
683 684 685 686 687
 *
 * @par Parameter type
 *     unsigned int
 *
 * @par Values
688
 *    - Value of @a delta-seconds in @RetryAfter header, from 0 to 86400
689 690
 *
 * @par Default Value
691
 *    - 0 (no @RetryAfter header is included)
Pekka Pessi's avatar
Pekka Pessi committed
692 693 694
 *
 * @sa NTATAG_TIMEOUT_408()
 */
Pekka Pessi's avatar
Pekka Pessi committed
695
tag_typedef_t ntatag_blacklist = UINTTAG_TYPEDEF(blacklist);
Pekka Pessi's avatar
Pekka Pessi committed
696 697 698

/**@def NTATAG_DEBUG_DROP_PROB(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
699
 * Packet drop probability for debugging.
Pekka Pessi's avatar
Pekka Pessi committed
700 701 702
 *
 * The packet drop probability parameter is useful mainly for debugging
 * purposes. The stack drops an incoming message received over an unreliable
Pekka Pessi's avatar
Pekka Pessi committed
703
 * transport (such as UDP) with the given probability. The range is in 0 ..
Pekka Pessi's avatar
Pekka Pessi committed
704 705 706
 * 1000, 500 means p=0.5.
 *
 * @par Used with
707 708
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
709 710 711 712 713 714 715 716
 *
 * @par Parameter type
 *    unsigned integer
 *
 * @par Values
 *    - Valid values are in range 0 ... 1000
 *    - Probablity to drop a given message is value / 1000.
 *
717 718 719 720
 * @par Default Value
 *    - 0 (no packets are dropped)
 *
 * @sa TPTAG_DEBUG_DROP()
Pekka Pessi's avatar
Pekka Pessi committed
721
 */
Pekka Pessi's avatar
Pekka Pessi committed
722 723
tag_typedef_t ntatag_debug_drop_prob = UINTTAG_TYPEDEF(debug_drop_prob);

Pekka Pessi's avatar
Pekka Pessi committed
724 725 726 727 728 729 730
/**@def NTATAG_SIGCOMP_OPTIONS(x)
 *
 * Semicolon-separated SigComp options.
 *
 * @note This tag is has no effect without a SigComp plugin.
 *
 * @par Used with
731 732 733
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params(),
 *    nta_agent_add_tport()
Pekka Pessi's avatar
Pekka Pessi committed
734 735
 *
 * @par Parameter type
Pekka Pessi's avatar
Pekka Pessi committed
736
 *    string
Pekka Pessi's avatar
Pekka Pessi committed
737 738 739 740 741 742 743
 *
 * @par Values
 *    - semicolon-separated parameter-value pairs, passed to the SigComp plugin
 *
 * @sa NTATAG_COMP(), NTATAG_SIGCOMP_ALGORITHM(), NTATAG_SIGCOMP_AWARE(),
 * NTATAG_SIGCOMP_CLOSE(), @RFC3320
 */
Pekka Pessi's avatar
Pekka Pessi committed
744
tag_typedef_t ntatag_sigcomp_options = STRTAG_TYPEDEF(sigcomp_options);
Pekka Pessi's avatar
Pekka Pessi committed
745 746 747 748 749 750 751 752 753 754

/**@def NTATAG_SIGCOMP_CLOSE(x)
 *
 * Close SigComp compartment after completing transaction.
 *
 * @note This tag is has no effect without a SigComp plugin.
 *
 * @par Used with
 *    nta_incoming_set_params(), nta_incoming_treply()
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
755
 *    nta_outgoing_tmcreate(), nta_outgoing_tcancel(),
Pekka Pessi's avatar
Pekka Pessi committed
756 757 758 759 760 761 762 763 764 765 766 767 768 769
 *    nta_outgoing_prack(), nta_msg_tsend(), nta_msg_treply()
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - application takes care of compartment management
 *    - false - stack manages compartments
 *
 * @sa NTATAG_COMP(), TPTAG_COMPARTMENT(),
 * NTATAG_SIGCOMP_ALGORITHM(), NTATAG_SIGCOMP_AWARE(),
 * NTATAG_SIGCOMP_OPTIONS(), @RFC3320
 */
Pekka Pessi's avatar
Pekka Pessi committed
770
tag_typedef_t ntatag_sigcomp_close = BOOLTAG_TYPEDEF(sigcomp_close);
Pekka Pessi's avatar
Pekka Pessi committed
771 772 773

/**@def NTATAG_SIGCOMP_AWARE(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
774
 * Indicate that the application is SigComp-aware.
Pekka Pessi's avatar
Pekka Pessi committed
775 776 777 778
 *
 * @note This tag is has no effect without a SigComp plugin.
 *
 * @par Used with
779 780
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
781 782 783 784 785 786 787 788 789 790 791 792
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - application takes care of compartment management
 *    - false - stack manages compartments
 *
 * @sa NTATAG_COMP(), NTATAG_SIGCOMP_ALGORITHM(), NTATAG_SIGCOMP_CLOSE(),
 * NTATAG_SIGCOMP_OPTIONS(), @RFC3320
 */
Pekka Pessi's avatar
Pekka Pessi committed
793
tag_typedef_t ntatag_sigcomp_aware = BOOLTAG_TYPEDEF(sigcomp_aware);
Pekka Pessi's avatar
Pekka Pessi committed
794 795 796

/**@def NTATAG_SIGCOMP_ALGORITHM(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
797
 * Specify SigComp algorithm.
Pekka Pessi's avatar
Pekka Pessi committed
798 799 800 801
 *
 * @note This tag is has no effect without a SigComp plugin.
 *
 * @par Used with
802 803 804
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params(),
 *    nta_agent_add_tport()
Pekka Pessi's avatar
Pekka Pessi committed
805 806
 *
 * @par Parameter type
Pekka Pessi's avatar
Pekka Pessi committed
807
 *    string
Pekka Pessi's avatar
Pekka Pessi committed
808 809 810 811 812 813 814
 *
 * @par Values
 *    - opaque string passed to the SigComp plugin
 *
 * @sa NTATAG_COMP(), NTATAG_SIGCOMP_AWARE(), NTATAG_SIGCOMP_CLOSE(),
 * NTATAG_SIGCOMP_OPTIONS(), @RFC3320
 */
Pekka Pessi's avatar
Pekka Pessi committed
815 816
tag_typedef_t ntatag_sigcomp_algorithm = STRTAG_TYPEDEF(sigcomp_algorithm);

Pekka Pessi's avatar
Pekka Pessi committed
817 818 819 820 821 822 823 824 825 826 827 828 829
/**@def NTATAG_UA(x)
 *
 * If true, NTA acts as User Agent Server or Client by default.
 *
 * When acting as an UA, the NTA stack will
 * - respond with 481 to a PRACK request with no matching "100rel" response
 * - check for out-of-order CSeq headers for each #nta_leg_t dialog object
 * - if NTATAG_MERGE_482(1) is also used, return <i>482 Request Merged</i> to
 *   a duplicate request with same @CallID, @CSeq, @From tag but different
 *   topmost @Via header (see @RFC3261 section 8.2.2.2 Merged Requests)
 * - silently discard duplicate final responses to INVITE
 * - retransmit preliminary responses (101..199) to INVITE request in regular
 *   intervals ("timer N2")
Pekka Pessi's avatar
Pekka Pessi committed
830
 * - retransmit 2XX response to INVITE request with exponential intervals
Pekka Pessi's avatar
Pekka Pessi committed
831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846
 * - handle ACK sent in 2XX response to an INVITE using the
 *   #nta_ack_cancel_f callback bound to #nta_incoming_t with
 *   nta_incoming_bind()
 * - not use timer C unless its value has been explicitly set
 *
 * @note This NUTAG_UA(1) is set internally by nua_create()
 *
 * @par Used with
 *    nta_agent_create() \n
 *    nta_agent_set_params() \n
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
Pekka Pessi's avatar
Pekka Pessi committed
847 848
 *    - true - act as an UA
 *    - false - act as an proxy
Pekka Pessi's avatar
Pekka Pessi committed
849
 *
850 851
 * @par Default Value
 *    - 0 (false)
Pekka Pessi's avatar
Pekka Pessi committed
852
 *
Pekka Pessi's avatar
Pekka Pessi committed
853 854
 * @sa NTATAG_MERGE_482()
 */
Pekka Pessi's avatar
Pekka Pessi committed
855
tag_typedef_t ntatag_ua = BOOLTAG_TYPEDEF(ua);
Pekka Pessi's avatar
Pekka Pessi committed
856 857 858 859 860 861 862 863 864 865 866

/**@def NTATAG_STATELESS(x)
 *
 * Enable stateless processing.
 *
 * @par Server side
 * The incoming requests are processed statefully if there is a default leg
 * (created with nta_leg_default()). This option is provided for proxies or
 * other server elements that process requests statelessly.
 *
 * @par Used with
867 868
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
869 870 871 872 873
 *
 * @par Values
 *    - true - do not pass incoming requests to default leg
 *    - false - pass incoming requests to default leg, if it exists
 *
874 875 876
 * @par Default Value
 *    - 0 (false,  pass incoming requests to default leg)
 *
Pekka Pessi's avatar
Pekka Pessi committed
877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892
 * @par Client side
 * The outgoing requests can be sent statelessly, too, if the
 * NTATAG_STATELESS(1) is included in the tag list of nta_outgoing_tcreate().
 *
 * @par Used with
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), nta_outgoing_prack()
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - create only a transient #nta_outgoing_t transaction object
 *    - false - create an ordinary client transaction object
 *
893 894 895
 * @par Default Value
 *    - 0 (false, create client transaction)
 *
Pekka Pessi's avatar
Pekka Pessi committed
896 897 898
 * @sa NTATAG_IS_UA(), nta_incoming_default(), nta_outgoing_default(),
 * nta_leg_default()
 */
Pekka Pessi's avatar
Pekka Pessi committed
899
tag_typedef_t ntatag_stateless = BOOLTAG_TYPEDEF(stateless);
Pekka Pessi's avatar
Pekka Pessi committed
900 901 902 903 904 905

/**@def NTATAG_USER_VIA(x)
 *
 * Allow application to insert Via headers.
 *
 * @par Used with
906 907 908 909
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params(),
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), nta_outgoing_prack(), nta_msg_tsend()
Pekka Pessi's avatar
Pekka Pessi committed
910 911 912 913 914 915
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
916 917
 *    - true - do not add @Via header to the request (if it has one)
 *    - false - always add a @Via header
Pekka Pessi's avatar
Pekka Pessi committed
918
 *
919 920
 * @par Default Value
 *    - 0 (false, always add a @Via header)
Pekka Pessi's avatar
Pekka Pessi committed
921
 *
922
 * @sa NTATAG_BRANCH(), NTATAG_TPORT()
Pekka Pessi's avatar
Pekka Pessi committed
923
 */
Pekka Pessi's avatar
Pekka Pessi committed
924
tag_typedef_t ntatag_user_via = BOOLTAG_TYPEDEF(user_via);
Pekka Pessi's avatar
Pekka Pessi committed
925 926 927

/**@def NTATAG_PASS_100(x)
 *
928
 * Pass "<i>100 Trying</i>" provisional answers to the application.
Pekka Pessi's avatar
Pekka Pessi committed
929 930 931 932 933 934 935 936 937
 *
 * By default, the stack silently processes the <i>100 Trying</i> responses
 * from the server. Usually the <i>100 Trying</i> responses are not
 * important to the application but rather sent by the outgoing proxy
 * immediately after it has received the request. However, the application
 * can ask nta for them by setting NTATAG_PASS_100(1) if, for instance, the
 * <i>100 Trying</i> responses are needed for user feedback.
 *
 * @par Used with
938 939
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params(),
Pekka Pessi's avatar
Pekka Pessi committed
940 941 942 943 944 945 946 947 948 949 950
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), nta_outgoing_prack(), nta_msg_tsend()
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - pass <i>100 Trying</i> to application
 *    - false - silently process <i>100 Trying</i> responses
 *
951 952 953
 * @par Default Value
 *    - 0 (false, save application from seeing 100 Trying)
 *
Pekka Pessi's avatar
Pekka Pessi committed
954 955
 * @sa NTATAG_EXTRA_100(), NTATAG_DEFAULT_PROXY()
 */
Pekka Pessi's avatar
Pekka Pessi committed
956
tag_typedef_t ntatag_pass_100 = BOOLTAG_TYPEDEF(pass_100);
Pekka Pessi's avatar
Pekka Pessi committed
957 958 959 960 961 962 963 964

/**@def NTATAG_EXTRA_100(x)
 *
 * Respond with "100 Trying" if application has not responded.
 *
 * As per recommended by @RFC4320, the stack can generate a 100 Trying
 * response to the non-INVITE requests if the application has not responded
 * to a request within half of the SIP T2 (the default value for T2 is 4000
Pekka Pessi's avatar
Pekka Pessi committed
965
 * milliseconds, so the extra <i>100 Trying</i> would be sent after 2 seconds).
Pekka Pessi's avatar
Pekka Pessi committed
966
 *
Pekka Pessi's avatar
Pekka Pessi committed
967
 * @par Used with
968 969
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
970 971 972 973 974 975 976
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - send extra 100 Trying if application does not respond
977
 *    - false - do not send 100 Trying
Pekka Pessi's avatar
Pekka Pessi committed
978
 *
979 980 981
 * @par Default Value
 *    - 0 (false, do not respond with 100 Trying to retransmissions)

Pekka Pessi's avatar
Pekka Pessi committed
982 983
 * @sa @RFC4320, NTATAG_PASS_408(), NTATAG_TIMEOUT_408()
 */
Pekka Pessi's avatar
Pekka Pessi committed
984
tag_typedef_t ntatag_extra_100 = BOOLTAG_TYPEDEF(extra_100);
Pekka Pessi's avatar
Pekka Pessi committed
985 986 987

/**@def NTATAG_TIMEOUT_408(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
988
 * Generate "408 Request Timeout" response when request times out.
Pekka Pessi's avatar
Pekka Pessi committed
989 990 991 992 993 994 995 996 997
 *
 * This tag is used to prevent stack from generating extra 408 response
 * messages to non-INVITE requests upon timeout. As per recommended by
 * @RFC4320, the <i>408 Request Timeout</i> responses to non-INVITE
 * transaction are not sent over the network to the client by default. The
 * application can ask stack to pass the 408 responses with
 * NTATAG_PASS_408(1).
 *
 * @par Used with
998 999
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - generate 408 response
 *    - false - invoke #nta_response_f callback with NULL sip pointer
 *              when a non-INVITE transaction times out
 *
 * @sa @RFC4320, NTATAG_PASS_408(), NTATAG_EXTRA_100(),
 */
Pekka Pessi's avatar
Pekka Pessi committed
1012
tag_typedef_t ntatag_timeout_408 = BOOLTAG_TYPEDEF(timeout_408);
Pekka Pessi's avatar
Pekka Pessi committed
1013 1014 1015

/**@def NTATAG_PASS_408(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
1016
 * Pass "408 Request Timeout" responses to the client.
Pekka Pessi's avatar
Pekka Pessi committed
1017 1018 1019 1020
 *
 * As per recommended by @RFC4320, the <i>408 Request Timeout</i> responses
 * to non-INVITE transaction are not sent over the network to the client by
 * default. The application can ask stack to pass the 408 responses with
Pekka Pessi's avatar
Pekka Pessi committed
1021
 * NTATAG_PASS_408(1).
Pekka Pessi's avatar
Pekka Pessi committed
1022 1023 1024 1025 1026
 *
 * Note that unlike NTATAG_PASS_100(), this tags changes the way server side
 * works.
 *
 * @par Used with
1027 1028
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
1029 1030 1031 1032 1033 1034
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
Pekka Pessi's avatar
Pekka Pessi committed
1035
 *    - true - pass superfluous 408 responses
Pekka Pessi's avatar
Pekka Pessi committed
1036 1037 1038 1039 1040
 *    - false - discard superfluous 408 responses
 *
 * @sa @RFC4320, NTATAG_EXTRA_100(), NTATAG_TIMEOUT_408()
 *
 */
Pekka Pessi's avatar
Pekka Pessi committed
1041
tag_typedef_t ntatag_pass_408 = BOOLTAG_TYPEDEF(pass_408);
Pekka Pessi's avatar
Pekka Pessi committed
1042 1043 1044

/**@def NTATAG_MERGE_482(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
1045
 * Merge requests, send 482 to other requests.
Pekka Pessi's avatar
Pekka Pessi committed
1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063
 *
 * If an User-Agent receives a duplicate request with same @CallID, @CSeq,
 * @From tag but different topmost @Via header (see @RFC3261 section 8.2.2.2
 * Merged Requests), it should return <i>482 Request Merged</i> response to
 * the duplicate request. Such a duplicate request has been originally
 * generated by a forking proxy and usually routed via different route to
 * the User-Agent. The User-Agent should only respond meaningfully to the
 * first request and return the 482 response to the following forked
 * requests.
 *
 * Note that also NTATAG_UA(1) should be set before nta detects merges and
 * responds with 482 to them.
 *
 * @note If your application is an multi-lined user-agent, you may consider
 * disabling request merging. However, you have to somehow handle merging
 * within a single line.
 *
 * @par Used with
1064 1065
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - detect duplicate requests and respond with 482 to them
 *    - false - process duplicate requests separately
 *
 * @sa NTATAG_UA(1)
 */
Pekka Pessi's avatar
Pekka Pessi committed
1077
tag_typedef_t ntatag_merge_482 = BOOLTAG_TYPEDEF(merge_482);
Pekka Pessi's avatar
Pekka Pessi committed
1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095

/**@def NTATAG_CANCEL_2543(x)
 *
 *Follow @RFC2543 semantics with CANCEL.
 *
 * By default, the nta follows "@RFC3261" semantics when CANCELing a
 * request. The CANCEL does not terminate transaction, rather, it is just a
 * hint to the server that it should respond immediately (with <i>487
 * Request Terminated</i> if it has no better response). Also, if the
 * original request was sent over unreliable transport such as UDP, the
 * CANCEL is delayed until the server has sent a preliminary response to the
 * original request.
 *
 * If NTATAG_CANCEL_2543(1) is given, the transaction is canceled
 * immediately internally (a 487 response is generated locally) and the
 * CANCEL request is sent without waiting for an provisional response.
 *
 * @par Used with
1096 1097
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109
 *    nta_outgoing_tcancel()
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - follow "RFC 2543" semantics with CANCEL
 *    - false - follow "RFC 3261" semantics with CANCEL
 *
 * @sa NTATAG_CANCEL_408()
 */
Pekka Pessi's avatar
Pekka Pessi committed
1110
tag_typedef_t ntatag_cancel_2543 = BOOLTAG_TYPEDEF(cancel_2543);
Pekka Pessi's avatar
Pekka Pessi committed
1111 1112 1113

/**@def NTATAG_CANCEL_408(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
1114
 * Do not send a CANCEL but just timeout the request.
Pekka Pessi's avatar
Pekka Pessi committed
1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133
 *
 * Calling nta_outgoing_tcancel() with this tag set marks request as
 * canceled but does not actually send a CANCEL request. If
 * NTATAG_CANCEL_2543(1) is also included, a 487 response is generated
 * internally.
 *
 * @par Used with
 *    nta_outgoing_tcancel() \n
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - do not send CANCEL
 *    - false - let request to timeout
 *
 * @sa NTATAG_CANCEL_2543()
 */
Pekka Pessi's avatar
Pekka Pessi committed
1134
tag_typedef_t ntatag_cancel_408 = BOOLTAG_TYPEDEF(cancel_408);
Pekka Pessi's avatar
Pekka Pessi committed
1135 1136 1137 1138 1139 1140 1141 1142 1143 1144

/**@def NTATAG_CANCEL_487(x)
 *
 * When a CANCEL is received, automatically return 487 response to original request.
 *
 * When the CANCEL is received for an ongoing server transaction
 * #nta_incoming_t, the stack will automatically return a <i>487 Request
 * Terminated</i> response to the client after returning from the
 * #nta_incoming_f callback bound to the transaction with
 * nta_incoming_bind()
Pekka Pessi's avatar
Pekka Pessi committed
1145
 *
Pekka Pessi's avatar
Pekka Pessi committed
1146 1147 1148 1149 1150 1151
 * The application can delay sending the response to the original request
 * when NTATAG_CANCEL_408(0) is used. This is useful, for instance, with a
 * proxy that forwards the CANCEL downstream and the forwards the response
 * back to upstream.
 *
 * @par Used with
1152 1153
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - respond automatically to the CANCELed transaction
 *    - false - application takes care of responding
 *
 * @sa NTATAG_CANCEL_2543(), nta_incoming_bind()
 */
Pekka Pessi's avatar
Pekka Pessi committed
1165
tag_typedef_t ntatag_cancel_487 = BOOLTAG_TYPEDEF(cancel_487);
Pekka Pessi's avatar
Pekka Pessi committed
1166 1167 1168

/**@def NTATAG_TAG_3261(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
1169
 * When responding to requests, use unique tags.
Pekka Pessi's avatar
Pekka Pessi committed
1170 1171 1172 1173 1174 1175
 *
 * If set the UA would generate an unique @From/@To tag for all dialogs. If
 * unset UA would reuse same tag in order to make it easier to re-establish
 * dialog state after a reboot.
 *
 * @par Used with
1176 1177
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - use different tag for each dialog
 *    - false - use same tag for all dialogs
 *
 * @sa @RFC3261 section 12.2.2
 */
Pekka Pessi's avatar
Pekka Pessi committed
1189
tag_typedef_t ntatag_tag_3261 = BOOLTAG_TYPEDEF(tag_3261);
Pekka Pessi's avatar
Pekka Pessi committed
1190 1191 1192

/**@def NTATAG_REL100(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
1193
 * Include rel100 in INVITE requests.
Pekka Pessi's avatar
Pekka Pessi committed
1194 1195 1196 1197
 *
 * Include feature tag "100rel" in @Supported header of the INVITE requests.
 *
 * @par Used with
1198 1199
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - include "100rel"
 *    - false - do not include "100rel"
 *
 * @sa nta_outgoing_prack(), nta_reliable_treply(), nta_reliable_mreply()
 */
Pekka Pessi's avatar
Pekka Pessi committed
1211
tag_typedef_t ntatag_rel100 = BOOLTAG_TYPEDEF(rel100);
Pekka Pessi's avatar
Pekka Pessi committed
1212 1213 1214 1215

/**@def NTATAG_NO_DIALOG(x)
 *
 * Create a leg without dialog. */
Pekka Pessi's avatar
Pekka Pessi committed
1216
tag_typedef_t ntatag_no_dialog = BOOLTAG_TYPEDEF(no_dialog);
Pekka Pessi's avatar
Pekka Pessi committed
1217 1218 1219

/**@def NTATAG_USE_TIMESTAMP(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
1220
 * Use @Timestamp header.
Pekka Pessi's avatar
Pekka Pessi committed
1221 1222 1223 1224 1225 1226
 *
 * If set, a @Timestamp header would be added to stateful requests. The
 * header can be used to calculate the roundtrip transport latency between
 * client and server.
 *
 * @par Used with
Pekka Pessi's avatar
Pekka Pessi committed
1227
 *    nua_create(),
Pekka Pessi's avatar
Pekka Pessi committed
1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242
 *    nta_agent_create(),
 *    nta_agent_set_params(),
 *    nta_outgoing_mcreate(), nta_outgoing_tcreate(),
 *    nta_outgoing_tcancel(), and nta_outgoing_prack().
 *
 * @par Parameter type
 *    boolean: true (non-zero or non-NULL pointer)
 *          or false (zero or NULL pointer)
 *
 * @par Values
 *    - true - Add @Timestamp header
 *    - false - do not add @Timestamp header
 *
 * @sa @RFC3261 section 8.2.6
 */
Pekka Pessi's avatar
Pekka Pessi committed
1243
tag_typedef_t ntatag_use_timestamp = BOOLTAG_TYPEDEF(use_timestamp);
Pekka Pessi's avatar
Pekka Pessi committed
1244 1245 1246

/**@def NTATAG_SIPFLAGS(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
1247
 * Set SIP parser flags.
Pekka Pessi's avatar
Pekka Pessi committed
1248 1249 1250 1251
 *
 * The SIP parser flags affect how the messages are parsed and the result
 * presented to the application. They also control encoding of messages.
 * The most important flags are as follows:
Pekka Pessi's avatar
Pekka Pessi committed
1252
 * - MSG_FLG_COMPACT - use compact form
Pekka Pessi's avatar
Pekka Pessi committed
1253
 *                     (single-letter header names, minimum whitespace)
Pekka Pessi's avatar
Pekka Pessi committed
1254
 * - MSG_FLG_EXTRACT_COPY - cache printable copy of headers when parsing.
Pekka Pessi's avatar
Pekka Pessi committed
1255 1256 1257 1258 1259
 *   Using this flag can speed up proxy processing considerably. It is
 *   implied when the parsed messages are logged (because #TPORT_LOG
 *   environment variable is set, or TPTAG_LOG() is used.
 *
 * @par Used with
1260 1261
 *    nua_create(), nua_set_params(),
 *    nta_agent_create(), nta_agent_set_params()
Pekka Pessi's avatar
Pekka Pessi committed
1262 1263
 *
 * @par Parameter type
Pekka Pessi's avatar
Pekka Pessi committed
1264
 *    unsigned int
Pekka Pessi's avatar
Pekka Pessi committed
1265 1266 1267 1268 1269 1270
 *
 * @par Values
 *    - Bitwise OR of SIP parser flags (enum #msg_flg_user)
 *
 * @sa NTATAG_PRELOAD(), enum #msg_flg_user, sip_s::sip_flags
 */
Pekka Pessi's avatar
Pekka Pessi committed
1271
tag_typedef_t ntatag_sipflags = UINTTAG_TYPEDEF(sipflags);
Pekka Pessi's avatar
Pekka Pessi committed
1272 1273 1274

/**@def NTATAG_CLIENT_RPORT(x)
 *
Pekka Pessi's avatar
Pekka Pessi committed
1275
 * Enable client-side "rport".
Pekka Pessi's avatar
Pekka Pessi committed
1276 1277 1278 1279 1280
 *
 * This tag controls @RFC3581 support on client side. The "rport" parameter
 * is used when the response has to be routed symmetrically through a NAT box.
 *
 * The client-side support involves just adding the "rport" parameter to the topmost
Pekka Pessi's avatar<