nta.docs

this is simple sip stack.

/* -*- c -*- */

/**@mainpage Sofia Transaction API for SIP - "nta"
 *
 * @section nta_meta Module Meta Information
 *
 * Sofia SIP Transaction API (nta) provides simple interface to the SIP
 * transaction, transport and message handling. The @b nta interface is
 * intended for both network and user elements. The public interface for 
 * @b nta is mostly defined in <nta.h>, but tag parameters are defined in
 * <nta_tag.h>.
 *
 * Functions and datatypes providing compatibility for old sources are in
 * <nta_compat.h>
 * 
 * @CONTACT Pekka Pessi <[e-mail]>
 *
 * @STATUS Core library
 *
 * @LICENSE LGPL
 *
 * @section nta_objects NTA Objects
 * 
 * The NTA deals with a few kinds of objects: @e agent (#nta_agent_t), @e
 * call @e legs (#nta_leg_t), @e outgoing @e client @e requests
 * (#nta_outgoing_t), and @e incoming @e server @e requests
 * (#nta_incoming_t).
 * 
 * NTA also uses SIP message objects #msg_t and #sip_t for handling
 * messages, as defined in <msg.h> and <sip.h>, respectively. The various
 * SIP headers are also defined in <sip.h>.
 * 
 * @section nta_agent_t Creating an NTA Agent
 * 
 * Most of the SIP entities, like @e user @e agent or @e proxy, consist of a
 * SIP server and a SIP client working together.  The NTA provides a simple
 * interface to SIP server and client with the #nta_agent_t objects.
 * 
 * The #nta_agent_t object is created by calling nta_agent_create(). The
 * object listens for incoming connections, receives messages, parses them,
 * and pass them to the application. It also takes care of sending the
 * messages.
 * 
 * The agent needs a #su_root_t object to schedule its execution. A root
 * object is used to wait for the network events, schedule the timer
 * routines, and pass messages asyncronously. A root object can be created
 * by, e.g., the function su_root_create(). The root object can be have its
 * own thread, or its main loop can be executed by an application thread by
 * calling the function su_root_run(). The main loop can be terminated by
 * calling the function su_root_break().
 * 
 * A simple agent could be created as follows:
 * @code
 *  registrar->reg_root = su_root_create(NULL);
 * 
 *  if (registrar->reg_root) {
 *    registrar->reg_agent = nta_agent_create(registrar->reg_root,
 *                                            (url_string_t*)argv[1],
 *                                            NULL,
 *                                            NULL,
 *                                            NULL);
 * 
 *    if (registrar->reg_agent) {
 *      su_root_run(registrar->reg_root);
 *      nta_agent_destroy(registrar->reg_agent);
 *    }
 * 
 *    su_root_destroy(registrar->reg_root);
 *  }
 * @endcode
 * 
 * @section nta_server SIP Server Action
 * 
 * A SIP server responds to the transactions sent by a client. The SIP
 * server can operate in two modes; it can be stateless or stateful. This
 * section describes how a stateful SIP server uses NTA.
 * 
 * @subsection nta_leg_t The NTA Legs
 * 
 * A leg is required for stateful transaction processing.  A default
 * leg is created like this:
 * @code
 * default_leg = nta_leg_tcreate(agent, process_requests, context,
 *                               URLTAG_URL(url), 
 *                               NTATAG_NO_DIALOG(1),
 *                               TAG_END());
 * @endcode			       
 * 
 * The @a url parameter is used to specify which URLs match to the leg. If
 * it is given, only requests with requestURI matching are processed by the
 * leg. The nta_leg_tcreate() is a @ref tagarg "tagarg" function, taking a
 * tagged argument list as its arguments.
 * 
 * Other, ordinary legs can be used to match incoming requests with existing
 * dialogs, calls or transaction contexts, or to provide outgoing requests
 * with consistent headers. When a call leg is created, it is provided with
 * @b From and @b To headers, and optionally with other headers like @b
 * Call-ID, @b Route, or @b CSeq.
 * 
 * A new call leg can be created as follows:
 * @code
 * call_leg = nta_leg_tcreate(agent,
 *                            process_call_requests, call_context,
 *                            SIPTAG_CALL_ID(sip->sip_call_id),
 *                            SIPTAG_TO(sip->sip_from),   
 *                            SIPTAG_FROM(sip->sip_to),
 *                            TAG_END());
 * @endcode
 *
 * @note In the example above, the @b From and @b To are reversed. This
 * happens if the headers are taken from an incoming request; the @b From
 * and @b To headers change direction when an outgoing request is initiated.
 *
 * @note An existing leg can be used in any direction, however.  If the leg
 * was created for an incoming INVITE transaction, it is also possible to
 * use the leg for an outgoing BYE transaction.
 * 
 * @subsection nta_leg_tag Tagging the Call Leg
 * 
 * All the SIP UAS elements (however, not proxy servers) are required to tag
 * the @b To header in their final responses. The function nta_leg_tag()
 * adds a tag to the leg's local address. Local address is used as the @b To
 * header in the reply messages, and as the @b From header in the requests.
 * 
 * @subsection nta_incoming_t Incoming Transactions
 * 
 * An incoming transaction object (nta_incoming_t) is created by NTA for
 * each unique incoming request message. When NTA has created the incoming
 * transaction object, it invokes the callback function provided with 
 * nta_leg_tcreate().  
 * 
 * The simplest way to reply to the request is to return a valid status code
 * from the callback function. Valid status codes are in range of 100 to
 * 699, inclusive.  If no automatic response is desired, the callback
 * function should return 0.
 * 
 * @note If the status code is final, the incoming transaction object will
 * be destroyed immediately after the callback function returns. It can not
 * be used afterwards.
 * 
 * @note It is not possible to respond with a 2xx status code to an incoming
 * INVITE transaction by returning the status code from the callback.
 * 
 * Valid return values for callback function are as follows:
 * @li 0, 100 .. 699 for requests other than INVITE, and
 * @li 0, 100 .. 199, 300..699 for INVITE requests.
 * 
 * All other return codes are interpreted as 500, that is, a @e 500 @e
 * Internal @e Server @e Error reply message is sent back to the client and
 * the request is immediately destroyed.
 * 
 * The simple registrar/redirect server may have a incoming request callback
 * as follows:
 * @code
 * int process_request(server_t *server,
 * 	               nta_leg_t *leg,
 * 	     	       nta_incoming_t *irq,
 * 	     	       sip_t const *sip)
 * {
 *   sip_contact_t *m;
 * 
 *   switch (sip->sip_request->rq_method) {
 *   case sip_method_register:
 *     return registrar_add(server, leg, reply, sip);
 * 
 *   case sip_method_ack:
 *     return 500;
 * 
 *   case sip_method_cancel:
 *     return 200;
 * 
 *   default:
 *     if (registrar_find(server, sip->sip_request->rq_url, &m) {
 *       nta_incoming_treply(irq, SIP_302_MOVED_TEMPORARILY, 
 *                           SIPTAG_CONTACT(m), TAG_END());
 *       return 302;
 *     }
 *     else {
 *       nta_incoming_treply(irq, SIP_404_NOT_FOUND, TAG_END());
 *       return 404;
 *     }
 *   }
 * }
 * @endcode
 * 
 * The default reply message will contain the status line with default
 * phrase, then Via, To, From, Call-ID, CSeq, and Content-Length headers.
 * If a more complex response message is required, the application should
 * respond using the function nta_incoming_treply(): 
 * @code
 * nta_incoming_treply(reply, SIP_200_OK, 
 *                     SIPTAG_CONTACT(contact),
 *                     SIPTAG_CONTENT_TYPE_STR("application/sdp"),
 *                     SIPTAG_PAYLOAD(sdp),
 *                     TAG_END());
 * @endcode
 * 
 * The nta_incoming_treply() is a @ref tagarg "tagarg" function, taking a
 * tagged argument list as its argument.
 * 
 * @note It is possible to send provisional replies (containing 1xx status
 * codes) several times with nta_incoming_treply(), but only one final
 * reply (containing status codes 2xx..6xx) can be sent. However, with
 * INVITE requests, a proxy can send a final 2xx reply even after an error
 * reply (3xx..6xx).
 * 
 * @section nta_100rel Reliable Provisional Responses - "100rel"
 * 
 * The <A href="../specs/rfc3262.txt"><B>100rel</B></A> SIP extension
 * provides reliable provisional responses, provisional responses that are
 * retransmitted until a special acknowledgement request, PRACK, is
 * received. In addition the PRACK method, the extension defines two
 * headers, @b RSeq and @b RAck, that are used to identify different
 * response messages. PRACK method is usable on INVITE requests only.
 * 
 * Using reliable responses is negotiated using the "100rel" option tag. The
 * UAC (party sending the INVITE) can include the option tag to the @b
 * Supported or @b Required header. In the first case, the UAC just
 * announces support for reliable responses, in the second case, the UAC
 * requires that the UAS (party responding to the call) always sends
 * provisional responses in reliable manner.
 *
 * When reliable responses are enabled with NTATAG_REL100() tag, the @b nta
 * engine automatically inserts the "100rel" option tag to the @b Supported
 * header in the INVITE requests.
 *
 * @subsection nta_reliable_t Responding Reliably
 *
 * When a UAS wants to respond reliably to a INVITE request, instead of
 * familiar nta_incoming_treply() or nta_incoming_mreply() it uses the
 * functions nta_reliable_treply() or nta_reliable_mreply(). These functions
 * return a pointer to a special object, nta_reliable_t, that is used to
 * keep track of unacknowledged responses and respond to the the PRACK
 * acknowledgement request. 
 * 
 * Both the functions nta_reliable_treply () and nta_reliable_mreply() take
 * a callback funtion pointer and an application context pointer as their
 * arguments. The callback function is similar to the leg callback function. 
 * The callback is invoked when a corresponding PRACK request is received,
 * or when there is a timeout.
 *
 * The @b nta takes care of assigning a serial number to each reliable
 * response and resending them if no PRACK request is received. It also
 * automatically adds the 100rel option tag to the @b Require header.
 *
 * Also, if a request with 100rel in Require header is responded with usual
 * nta_incoming_treply()/nta_incoming_mreply() functions, the @b nta creates
 * a reliable response object for each provisional response in behalf of
 * application. As the application can not provide a PRACK callback function
 * to @b nta, the PRACK requests are not delivered to the application. 
 *
 * @subsection early_dialog UAC Receives a Reliable Response
 *
 * When a UAC receives a provisional response with a @b RSeq header, it is
 * required to acknowledge it. In order to do that, it must establish an @e
 * early @e dialog with the UAS. In another view, a reliable response is
 * used to establish the early dialog. UAC establishes a leg object for the
 * early dialog by calling nta_leg_tcreate() with the parameters derived
 * from the response message. 
 *
 * @code
 * int invite_callback(call_t *call,
 * 		    nta_outgoing_t *orq,
 * 		    sip_t const *sip)
 * {
 *   int status = sip->sip_status->st_status;
 * 
 *   if (!call->has_dialog && 
 *       (status >= 200 || (status > 100 && sip->sip_rseq))) {
 *     nta_leg_t *early = 
 *       nta_leg_tcreate(call->nta_agent, mid_dialog_request, call,