userapps/opensource/libosip2/include/osip2/osip.h

   1 /*
   2   The oSIP library implements the Session Initiation Protocol (SIP -rfc2543-)
   3   Copyright (C) 2001  Aymeric MOIZARD jack@atosc.org
   4
   5   This library is free software; you can redistribute it and/or
   6   modify it under the terms of the GNU Lesser General Public
   7   License as published by the Free Software Foundation; either
   8   version 2.1 of the License, or (at your option) any later version.
   9
  10   This library is distributed in the hope that it will be useful,
  11   but WITHOUT ANY WARRANTY; without even the implied warranty of
  12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13   Lesser General Public License for more details.
  14
  15   You should have received a copy of the GNU Lesser General Public
  16   License along with this library; if not, write to the Free Software
  17   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18 */
  19
  20
  21 #ifndef _OSIP_H_
  22 #define _OSIP_H_
  23
  24 #include <osipparser2/osip_const.h>
  25
  26 #include <time.h>
  27
  28 #ifdef WIN32
  29 #include <Winsock.h>
  30 #endif
  31
  32 #ifdef __sun
  33 #include <sys/types.h>
  34 #endif
  35
  36 #include <osipparser2/osip_parser.h>
  37 #include <osip2/osip_fifo.h>
  38
  39 /**
  40  * @file osip.h
  41  * @brief oSIP fsm Routines
  42  *
  43  * <H2>Introduction.</H2>
  44  * fsm stands for 'finite state machine'. The possible STATE of the state
  45  * machines are defined in the enum state. In oSIP, you can actually find
  46  * 4 different state machines. Those state machines definitions are directly
  47  * related to the definitions of transactions from the SIP specifications.
  48  * (See section: 17.1.1,  17.1.2,  17.2.1,  17.2.2). In the 4 drawings shown
  49  * in those sections, you'll find the possible STATES and the possible EVENTS
  50  * (osip_event_t) that can occur. EVENTS can be either TIMEOUT events and
  51  * SIP message (incoming and outgoing) events.
  52  * <H2>Why 4 finite state machines.</H2>
  53  * <BR>SIP has two different kind of transaction: INVITE and NON-INVITE ones.
  54  * Also, a SIP User Agent can act as a server and as a client. This simply
  55  * leads to 4 transactions state machines.
  56  * <BR>
  57  * <H2>Step 1: oSIP initialisation</H2>
  58  * <BR>To use oSIP, a program MUST first initialise internal elements in the
  59  * stack. The initialisation is shown below:
  60  * <pre><code>
  61  * osip_t *osip;
  62  * // allocate a global osip element.
  63  * if (0!=osip_init(&osip))
  64  *   return -1;
  65  *
  66  * // the next step is the initialisation of the callbacks used by the
  67  * // oSIP stack to announce events (when a transition occurs in the fsm)
  68  *
  69  * // This callback is somewhat special and is used by oSIP to inform
  70  * // the application that a message has to be sent. The message is
  71  * // sent by your application! oSIP has no ways to send it alone.
  72  * // Also, the method you supply will be called with default values where
  73  * // you should send the SIP message. You are not mandated to send the
  74  * // SIP message by using those default values.
  75  * // the callback MUST return 0 on success, 1 on ECONNREFUSED, -1 on error.
  76  *  osip_set_cb_send_message(osip, &application_cb_snd_message);
  77  *
  78  * // here is the long list of callback that you can register. Some
  79  * // of this callbacks are very useless (announcing a retransmission,
  80  * // or announcing that you have sent a SIP message which you may already
  81  * // know...).
  82  *
  83  * // those callbacks are mandatory. They are called when oSIP has decided
  84  * // that this transaction MUST no longer be handled by oSIP. (This is
  85  * // called in both successful or error cases scenario)
  86   osip_set_kill_transaction_callback(osip ,OSIP_ICT_KILL_TRANSACTION,
  87                                  &cb_ict_kill_transaction);
  88   osip_set_kill_transaction_callback(osip ,OSIP_NIST_KILL_TRANSACTION,
  89                                  &cb_ist_kill_transaction);
  90   osip_set_kill_transaction_callback(osip ,OSIP_NICT_KILL_TRANSACTION,
  91                                  &cb_nict_kill_transaction);
  92   osip_set_kill_transaction_callback(osip ,OSIP_NIST_KILL_TRANSACTION,
  93                                  &cb_nist_kill_transaction);
  94  *
  95  * // those callbacks are optional. The purpose is to announce retransmissions
  96  * // of SIP message decided by the oSIP stack. (They can be used for statistics?)
  97   osip_set_message_callback(osip ,OSIP_ICT_STATUS_2XX_RECEIVED_AGAIN,
  98                         &cb_rcvresp_retransmission);
  99   osip_set_message_callback(osip ,OSIP_ICT_STATUS_3456XX_RECEIVED_AGAIN,
 100                         &cb_rcvresp_retransmission);
 101   osip_set_message_callback(osip ,OSIP_ICT_INVITE_SENT_AGAIN,
 102                         &cb_sndreq_retransmission);
 103   osip_set_message_callback(osip ,OSIP_IST_STATUS_2XX_SENT_AGAIN,
 104                         &cb_sndresp_retransmission);
 105   osip_set_message_callback(osip ,OSIP_IST_STATUS_3456XX_SENT_AGAIN,
 106                         &cb_sndresp_retransmission);
 107   osip_set_message_callback(osip ,OSIP_IST_INVITE_RECEIVED_AGAIN,
 108                         &cb_rcvreq_retransmission);
 109   osip_set_message_callback(osip ,OSIP_NICT_STATUS_2XX_RECEIVED_AGAIN,
 110                         &cb_rcvresp_retransmission);
 111   osip_set_message_callback(osip ,OSIP_NICT_STATUS_3456XX_RECEIVED_AGAIN,
 112                         &cb_rcvresp_retransmission);
 113   osip_set_message_callback(osip ,OSIP_NICT_REQUEST_SENT_AGAIN,
 114                         &cb_sndreq_retransmission);
 115   osip_set_message_callback(osip ,OSIP_NIST_STATUS_2XX_SENT_AGAIN,
 116                         &cb_sndresp_retransmission);
 117   osip_set_message_callback(osip ,OSIP_NIST_STATUS_3456XX_SENT_AGAIN,
 118                         &cb_sndresp_retransmission);
 119   osip_set_message_callback(osip ,OSIP_NIST_REQUEST_RECEIVED_AGAIN,
 120                         &cb_rcvreq_retransmission);
 121  *
 122  * // those callbacks are mandatory. They are used to announce network related
 123  * // errors (the return code of the network callback if it was not 0)
 124   osip_set_transport_error_callback(osip ,OSIP_ICT_TRANSPORT_ERROR,
 125                                     &cb_transport_error);
 126   osip_set_transport_error_callback(osip ,OSIP_IST_TRANSPORT_ERROR,
 127                                     &cb_transport_error);
 128   osip_set_transport_error_callback(osip ,OSIP_NICT_TRANSPORT_ERROR,
 129                                     &cb_transport_error);
 130   osip_set_transport_error_callback(osip ,OSIP_NIST_TRANSPORT_ERROR,
 131                                     &cb_transport_error);
 132  *
 133  * // those callbacks are optional. They are used to announce the initial
 134  * // request sent for a newly created transaction.
 135   osip_set_message_callback(osip ,OSIP_ICT_INVITE_SENT,     &cb_sndinvite);
 136   osip_set_message_callback(osip ,OSIP_ICT_ACK_SENT,        &cb_sndack);
 137   osip_set_message_callback(osip ,OSIP_NICT_REGISTER_SENT,  &cb_sndregister);
 138   osip_set_message_callback(osip ,OSIP_NICT_BYE_SENT,       &cb_sndbye);
 139   osip_set_message_callback(osip ,OSIP_NICT_CANCEL_SENT,    &cb_sndcancel);
 140   osip_set_message_callback(osip ,OSIP_NICT_INFO_SENT,      &cb_sndinfo);
 141   osip_set_message_callback(osip ,OSIP_NICT_OPTIONS_SENT,   &cb_sndoptions);
 142   osip_set_message_callback(osip ,OSIP_NICT_SUBSCRIBE_SENT, &cb_sndsubscribe);
 143   osip_set_message_callback(osip ,OSIP_NICT_NOTIFY_SENT,    &cb_sndnotify);
 144   osip_set_message_callback(osip ,OSIP_NICT_UNKNOWN_REQUEST_SENT, &cb_sndunkrequest);
 145  *
 146  * // those callbacks are mandatory. They are used to announce the initial
 147  * // response received for a transaction. (for SIP response between 100 and 199,
 148  * // all responses are announced because this is not a retransmission case)
 149   osip_set_message_callback(osip ,OSIP_ICT_STATUS_1XX_RECEIVED, &cb_rcv1xx);
 150   osip_set_message_callback(osip ,OSIP_ICT_STATUS_2XX_RECEIVED, &cb_rcv2xx);
 151   osip_set_message_callback(osip ,OSIP_ICT_STATUS_3XX_RECEIVED, &cb_rcv3xx);
 152   osip_set_message_callback(osip ,OSIP_ICT_STATUS_4XX_RECEIVED, &cb_rcv4xx);
 153   osip_set_message_callback(osip ,OSIP_ICT_STATUS_5XX_RECEIVED, &cb_rcv5xx);
 154   osip_set_message_callback(osip ,OSIP_ICT_STATUS_6XX_RECEIVED, &cb_rcv6xx);
 155  *
 156  * // those callbacks are optional. They are used to announce the initial
 157  * // response sent for a transaction. (for SIP response between 100 and 199,
 158  * // all responses are announced because this is not a retransmission case)
 159
 160   osip_set_message_callback(osip ,OSIP_IST_STATUS_1XX_SENT, &cb_snd1xx);
 161   osip_set_message_callback(osip ,OSIP_IST_STATUS_2XX_SENT, &cb_snd2xx);
 162   osip_set_message_callback(osip ,OSIP_IST_STATUS_3XX_SENT, &cb_snd3xx);
 163   osip_set_message_callback(osip ,OSIP_IST_STATUS_4XX_SENT, &cb_snd4xx);
 164   osip_set_message_callback(osip ,OSIP_IST_STATUS_5XX_SENT, &cb_snd5xx);
 165   osip_set_message_callback(osip ,OSIP_IST_STATUS_6XX_SENT, &cb_snd6xx);
 166  *
 167  * // those callbacks are mandatory. They are used to announce the initial
 168  * // response received for a transaction. (for SIP response between 100 and 199,
 169  * // all responses are announced because this is not a retransmission case)
 170   osip_set_message_callback(osip ,OSIP_NICT_STATUS_1XX_RECEIVED, &cb_rcv1xx);
 171   osip_set_message_callback(osip ,OSIP_NICT_STATUS_2XX_RECEIVED, &cb_rcv2xx);
 172   osip_set_message_callback(osip ,OSIP_NICT_STATUS_3XX_RECEIVED, &cb_rcv3xx);
 173   osip_set_message_callback(osip ,OSIP_NICT_STATUS_4XX_RECEIVED, &cb_rcv4xx);
 174   osip_set_message_callback(osip ,OSIP_NICT_STATUS_5XX_RECEIVED, &cb_rcv5xx);
 175   osip_set_message_callback(osip ,OSIP_NICT_STATUS_6XX_RECEIVED, &cb_rcv6xx);
 176  *
 177  * // those callbacks are optional. They are used to announce the initial
 178  * // response sent for a transaction. (for SIP response between 100 and 199,
 179  * // all responses are announced because this is not a retransmission case)
 180   osip_set_message_callback(osip ,OSIP_NIST_STATUS_1XX_SENT, &cb_snd1xx);
 181   osip_set_message_callback(osip ,OSIP_NIST_STATUS_2XX_SENT, &cb_snd2xx);
 182   osip_set_message_callback(osip ,OSIP_NIST_STATUS_3XX_SENT, &cb_snd3xx);
 183   osip_set_message_callback(osip ,OSIP_NIST_STATUS_4XX_SENT, &cb_snd4xx);
 184   osip_set_message_callback(osip ,OSIP_NIST_STATUS_5XX_SENT, &cb_snd5xx);
 185   osip_set_message_callback(osip ,OSIP_NIST_STATUS_6XX_SENT, &cb_snd6xx);
 186  *
 187  * // those callbacks are mandatory. They are used to announce the initial
 188  * // request received for a transaction. It is not useless to notice that
 189  * // a special behaviour exist for the 200 OK and the ACK in the case of
 190  * // a successful INVITE transaction. This will be discussed later.
 191   osip_set_message_callback(osip ,OSIP_IST_INVITE_RECEIVED,     &cb_rcvinvite);
 192   osip_set_message_callback(osip ,OSIP_IST_ACK_RECEIVED,        &cb_rcvack);
 193   osip_set_message_callback(osip ,OSIP_IST_ACK_RECEIVED_AGAIN,  &cb_rcvack2);
 194   osip_set_message_callback(osip ,OSIP_NIST_REGISTER_RECEIVED,  &cb_rcvregister);
 195   osip_set_message_callback(osip ,OSIP_NIST_BYE_RECEIVED,       &cb_rcvbye);
 196   osip_set_message_callback(osip ,OSIP_NIST_CANCEL_RECEIVED,    &cb_rcvcancel);
 197   osip_set_message_callback(osip ,OSIP_NIST_INFO_RECEIVED,      &cb_rcvinfo);
 198   osip_set_message_callback(osip ,OSIP_NIST_OPTIONS_RECEIVED,   &cb_rcvoptions);
 199   osip_set_message_callback(osip ,OSIP_NIST_SUBSCRIBE_RECEIVED, &cb_rcvsubscribe);
 200   osip_set_message_callback(osip ,OSIP_NIST_NOTIFY_RECEIVED,    &cb_rcvnotify);
 201   osip_set_message_callback(osip ,OSIP_NIST_UNKNOWN_REQUEST_RECEIVED, &cb_sndunkrequest);
 202  *
 203  * </code></pre>
 204  * <P>
 205  * <H2>Step 2: Initialising a new transaction.</H2>
 206  * <BR>Let's assume you want to implement a User Agent and you want to
 207  * start a REGISTER transaction. Using the parser library, you will first
 208  * have to build a SIP compliant message. (oSIP, as a low layer library
 209  * provides an interface to build SIP messages, but it's up to you to
 210  * correctly fill all the required fields.)
 211  * As soon as you have build the SIP message, you are ready to start a new
 212  * transaction. Here is the code:
 213  * <BR><pre><code>
 214  * osip_t *osip       = your_global_osip_context;
 215  * osip_transaction_t *transaction;
 216  * osip_message_t     *sip_register_message;
 217  * osip_event_t       *sipevent;
 218  *
 219  * application_build_register(&sip_register_message);
 220  * osip_transaction_init(&transaction,
 221  *                 NICT, //a REGISTER is a Non-Invite-Client-Transaction
 222  *                 osip,
 223  *                 sip_register_message);
 224  *
 225  * // If you have a special context that you want to associate to that
 226  * // transaction, you can use a special method that associate your context
 227  * // to the transaction context.
 228  *
 229  * osip_transaction_set_your_instance(transaction, any_pointer);
 230  *
 231  * // at this point, the transaction context exists in oSIP but you still have
 232  * // to give the SIP message to the finite state machine.
 233  * sipevent = osip_new_outgoing_sipmessage(msg);
 234  * sipevent->transactionid =  transaction->transactionid;
 235  * osip_transaction_add_event(transaction, sipevent);
 236  * // at this point, the event will be handled by oSIP. (The memory resource will
 237  * // also be handled by oSIP). Note that no action is taken there.
 238  * </pre></code>
 239  * <P>Adding new events in the fsm is made with similar code.
 240  * <P>
 241  * <H2>Step 3: Consuming events.</H2>
 242  * <BR>The previous step show how to create a transaction and one possible way
 243  * to add a new event. (Note, that some events -the TIMEOUT_* ones- will be
 244  * added by oSIP not by the application). In this step, we describe how the
 245  * oSIP stack will consume events. In fact, this is very simple, but you
 246  * should be aware that it's not always allowed to consume an event at any time!
 247  * The fsm MUST consume events sequentially within a transaction. This means
 248  * that when your are calling osip_transaction_execute(), it is forbidden to call
 249  * this method again with the same transaction context until the first call
 250  * has returned. In a multi threaded application, if one thread handles one
 251  * transaction, the code will be the following:
 252  * <BR><pre><code>
 253  *   while (1)
 254  *     {
 255  *       se = (osip_event_t *)osip_fifo_get(transaction->transactionff);
 256  *       if (se==NULL)
 257  *        osip_thread_exit();
 258  *       if (osip_transaction_execute(transaction,se)<1)  // deletion asked
 259  *        osip_thread_exit();
 260  *   }
 261  * </pre></code>
 262  * <P>
 263  * <H2>Step 4: How the stack will announce the events</H2>
 264  * Looking at the case of a usual outgoing REGISTER transaction, this behaviour
 265  * is expected.
 266  * <BR>When an event is seen as useful for the fsm, it means that a transition
 267  * from one state to another has to be done on the transaction context. If the
 268  * event is SND_REQUEST (this is the case for an outgoing REGISTER), the
 269  * callback previously registered to announce this action will be called. This
 270  * callback is useless for the application as no action has to be taken at this
 271  * step. A more interesting announcement will be made when consuming the
 272  * first final response received. If the callbacks associated to 2xx message
 273  * is called, then the transaction has succeeded. Inside this callback, you
 274  * will probably inform the user of the success of the registration if you want
 275  * to do so...
 276  * If the final response is not a 2xx, or the network callback is called, you'll
 277  * probably want to take some actions. For example, if you receive a 302, you'll
 278  * probably want to retry a registration at the new location. All that decision
 279  * is up to you.
 280  */
 281
 282 /**
 283  * @defgroup oSIP_FSM oSIP fsm Handling
 284  * @ingroup oSIP
 285  * @{
 286  */
 287
 288 #ifdef __cplusplus
 289 extern "C"
 290 {
 291 #endif
 292
 293
 294 /**
 295  * Enumeration for transaction state.
 296  * Those states are extracted from the diagram found in rfc3261.txt
 297  *
 298  */
 299   typedef enum _state_t
 300   {
 301     /* STATES for invite client transaction */
 302     ICT_PRE_CALLING,
 303     ICT_CALLING,
 304     ICT_PROCEEDING,
 305     ICT_COMPLETED,
 306     ICT_TERMINATED,
 307
 308     /* STATES for invite server transaction */
 309     IST_PRE_PROCEEDING,
 310     IST_PROCEEDING,
 311     IST_COMPLETED,
 312     IST_CONFIRMED,
 313     IST_TERMINATED,
 314
 315     /* STATES for NON-invite client transaction */
 316     NICT_PRE_TRYING,
 317     NICT_TRYING,
 318     NICT_PROCEEDING,
 319     NICT_COMPLETED,
 320     NICT_TERMINATED,
 321
 322     /* STATES for NON-invite server transaction */
 323     NIST_PRE_TRYING,
 324     NIST_TRYING,
 325     NIST_PROCEEDING,
 326     NIST_COMPLETED,
 327     NIST_TERMINATED,
 328
 329 #ifndef DOXYGEN
 330     DIALOG_EARLY,
 331     DIALOG_CONFIRMED,
 332     DIALOG_CLOSE                /* ?? */
 333 #endif
 334   }
 335   state_t;
 336
 337 /**
 338  * Enumeration for event type.
 339  * <BR>The list of values that you need to know is reduced to this:
 340  * <BR> RCV_REQINVITE,
 341  * <BR> RCV_REQACK,
 342  * <BR> RCV_REQUEST,
 343  * <BR> RCV_STATUS_1XX,
 344  * <BR> RCV_STATUS_2XX,
 345  * <BR> RCV_STATUS_3456XX,
 346  *<BR>
 347  * <BR> SND_REQINVITE,
 348  * <BR> SND_REQACK,
 349  * <BR> SND_REQUEST,
 350  * <BR> SND_STATUS_1XX,
 351  * <BR> SND_STATUS_2XX,
 352  * <BR> SND_STATUS_3456XX,
 353  */
 354   typedef enum type_t
 355   {
 356     /* TIMEOUT EVENTS for ICT */
 357     TIMEOUT_A,   /**< Timer A */
 358     TIMEOUT_B,   /**< Timer B */
 359     TIMEOUT_D,   /**< Timer D */
 360
 361     /* TIMEOUT EVENTS for NICT */
 362     TIMEOUT_E,   /**< Timer E */
 363     TIMEOUT_F,   /**< Timer F */
 364     TIMEOUT_K,   /**< Timer K */
 365
 366     /* TIMEOUT EVENTS for IST */
 367     TIMEOUT_G,   /**< Timer G */
 368     TIMEOUT_H,   /**< Timer H */
 369     TIMEOUT_I,   /**< Timer I */
 370
 371     /* TIMEOUT EVENTS for NIST */
 372     TIMEOUT_J,   /**< Timer J */
 373
 374     /* FOR INCOMING MESSAGE */
 375     RCV_REQINVITE,    /**< Event is an incoming INVITE request */
 376     RCV_REQACK,       /**< Event is an incoming ACK request */
 377     RCV_REQUEST,      /**< Event is an incoming NON-INVITE and NON-ACK request */
 378     RCV_STATUS_1XX,   /**< Event is an incoming informational response */
 379     RCV_STATUS_2XX,   /**< Event is an incoming 2XX response */
 380     RCV_STATUS_3456XX,/**< Event is an incoming final response (not 2XX) */
 381
 382     /* FOR OUTGOING MESSAGE */
 383     SND_REQINVITE,    /**< Event is an outgoing INVITE request */
 384     SND_REQACK,       /**< Event is an outgoing ACK request */
 385     SND_REQUEST,      /**< Event is an outgoing NON-INVITE and NON-ACK request */
 386     SND_STATUS_1XX,   /**< Event is an outgoing informational response */
 387     SND_STATUS_2XX,   /**< Event is an outgoing 2XX response */
 388     SND_STATUS_3456XX,/**< Event is an outgoing final response (not 2XX) */
 389
 390     KILL_TRANSACTION, /**< Event to 'kill' the transaction before termination */
 391     UNKNOWN_EVT
 392   }
 393   type_t;
 394
 395 /**
 396  * Enumeration for transaction type.
 397  * A transaction can be either of:
 398  *  ICT,
 399  *  IST,
 400  *  NICT,
 401  *  NIST,
 402  */
 403   typedef enum osip_fsm_type_t
 404   {
 405     ICT, /**< Invite Client (outgoing) Transaction */
 406     IST, /**< Invite Server (incoming) Transaction */
 407     NICT,/**< Non-Invite Client (outgoing) Transaction */
 408     NIST /**< Non-Invite Server (incoming) Transaction */
 409   }
 410   osip_fsm_type_t;
 411
 412 #ifndef DEFAULT_T1
 413 /**
 414  * You can re-define the default value for T1. (T1 is defined in rfcxxxx)
 415  * The default value is 500ms.
 416  */
 417 #define DEFAULT_T1 500          /* 500 ms */
 418 #endif
 419 #ifndef DEFAULT_T2
 420 /**
 421  * You can re-define the default value for T2. (T2 is defined in rfcxxxx)
 422  * The default value is 4000ms.
 423  */
 424 #define DEFAULT_T2 4000         /* 4s */
 425 #endif
 426 #ifndef DEFAULT_T4
 427 /**
 428  * You can re-define the default value for T4. (T1 is defined in rfcxxxx)
 429  * The default value is 5000ms.
 430  */
 431 #define DEFAULT_T4 5000         /* 5s */
 432 #endif
 433
 434
 435 /**
 436  * Structure for INVITE CLIENT TRANSACTION (outgoing INVITE transaction).
 437  * @defvar osip_ict_t
 438  */
 439   typedef struct osip_ict osip_ict_t;
 440
 441   struct osip_ict
 442   {
 443     /* state machine is implied... */
 444     int timer_a_length;         /* A=T1, A=2xT1... (unreliable tr only)  */
 445     struct timeval timer_a_start;
 446     int timer_b_length;         /* B = 64* T1                            */
 447     struct timeval timer_b_start;       /* fire when transaction timeouts        */
 448     int timer_d_length;         /* D >= 32s for unreliable tr (or 0)     */
 449     struct timeval timer_d_start;       /* should be equal to timer H            */
 450     char *destination;          /* url used to send requests         */
 451     int port;                   /* port of next hop                  */
 452
 453   };
 454
 455 /**
 456  * Structure for NON-INVITE CLIENT TRANSACTION (outgoing NON-INVITE transaction).
 457  * @defvar osip_nict_t
 458  */
 459   typedef struct osip_nict osip_nict_t;
 460
 461   struct osip_nict
 462   {
 463     /* state machine is implied... */
 464
 465     int timer_e_length;         /* A=T1, A=2xT1... (unreliable tr. only) */
 466     struct timeval timer_e_start;       /*  (else = -1) not active               */
 467     int timer_f_length;         /* B = 64* T1                            */
 468     struct timeval timer_f_start;       /* fire when transaction timeouts        */
 469     int timer_k_length;         /* K = T4 (else = 0)                     */
 470     struct timeval timer_k_start;
 471     char *destination;          /* url used to send requests         */
 472     int port;                   /* port of next hop                  */
 473
 474   };
 475
 476 /**
 477  * Structure for INVITE SERVER TRANSACTION (incoming INVITE transaction).
 478  * @defvar osip_ist_t
 479  */
 480   typedef struct osip_ist osip_ist_t;
 481
 482   struct osip_ist
 483   {
 484     int timer_g_length;         /* G=MIN(T1*2,T2) for unreliable trans.  */
 485     struct timeval timer_g_start;       /* 0 when reliable transport is used!    */
 486     int timer_h_length;         /* H = 64* T1                            */
 487     struct timeval timer_h_start;       /* fire when if no ACK is received       */
 488     int timer_i_length;         /* I = T4 for unreliable transport (or 0) */
 489     struct timeval timer_i_start;       /* absorb all ACK                        */
 490   };
 491
 492 /**
 493  * Structure for NON-INVITE SERVER TRANSACTION (incoming SERVER transaction).
 494  * @defvar osip_nist_t
 495  */
 496   typedef struct osip_nist osip_nist_t;
 497
 498   struct osip_nist
 499   {
 500     int timer_j_length;         /* J = 64*T1 (else 0) */
 501     struct timeval timer_j_start;
 502   };
 503
 504 /**
 505  * Structure for transaction handling.
 506  * @defvar osip_transaction_t
 507  */
 508   typedef struct osip_transaction osip_transaction_t;
 509
 510   struct osip_transaction
 511   {
 512
 513     void *your_instance;        /* add whatever you want here.       */
 514     int transactionid;          /* simple id used to identify the tr. */
 515     osip_fifo_t *transactionff; /* events must be added in this fifo */
 516
 517     osip_via_t *topvia;         /* CALL-LEG definition */
 518     osip_from_t *from;          /* CALL-LEG definition */
 519     osip_to_t *to;
 520     osip_call_id_t *callid;
 521     osip_cseq_t *cseq;
 522
 523     osip_message_t *orig_request;       /* last request sent                 */
 524     osip_message_t *last_response;      /* last response received            */
 525     osip_message_t *ack;        /* ack request sent                  */
 526
 527     state_t state;              /* state of transaction              */
 528
 529     time_t birth_time;          /* birth_date of transaction         */
 530     time_t completed_time;      /* end   date of transaction         */
 531
 532     /* RESPONSE are received on this socket */
 533     int in_socket;
 534     /* REQUESTS are sent on this socket */
 535     int out_socket;
 536
 537     void *config;               /* transaction is managed by config  */
 538
 539     osip_fsm_type_t ctx_type;
 540     osip_ict_t *ict_context;
 541     osip_ist_t *ist_context;
 542     osip_nict_t *nict_context;
 543     osip_nist_t *nist_context;
 544   };
 545
 546
 547 /**
 548  * Enumeration for callback type.
 549  */
 550   typedef enum osip_message_callback_type
 551   {
 552     OSIP_ICT_INVITE_SENT = 0,               /**< INVITE MESSAGE SENT */
 553     OSIP_ICT_INVITE_SENT_AGAIN,             /**< INVITE MESSAGE RETRANSMITTED */
 554     OSIP_ICT_ACK_SENT,                      /**< ACK MESSAGE SENT */
 555     OSIP_ICT_ACK_SENT_AGAIN,                /**< ACK MESSAGE RETRANSMITTED */
 556     OSIP_ICT_STATUS_1XX_RECEIVED,           /**< 1XX FOR INVITE RECEIVED */
 557     OSIP_ICT_STATUS_2XX_RECEIVED,           /**< 2XX FOR INVITE RECEIVED */
 558     OSIP_ICT_STATUS_2XX_RECEIVED_AGAIN,     /**< 2XX FOR INVITE RECEIVED AGAIN */
 559     OSIP_ICT_STATUS_3XX_RECEIVED,           /**< 3XX FOR INVITE RECEIVED */
 560     OSIP_ICT_STATUS_4XX_RECEIVED,           /**< 4XX FOR INVITE RECEIVED */
 561     OSIP_ICT_STATUS_5XX_RECEIVED,           /**< 5XX FOR INVITE RECEIVED */
 562     OSIP_ICT_STATUS_6XX_RECEIVED,           /**< 6XX FOR INVITE RECEIVED */
 563     OSIP_ICT_STATUS_3456XX_RECEIVED_AGAIN,  /**< RESPONSE RECEIVED AGAIN */
 564
 565     OSIP_IST_INVITE_RECEIVED,               /**< INVITE MESSAGE RECEIVED */
 566     OSIP_IST_INVITE_RECEIVED_AGAIN,         /**< INVITE MESSAGE RECEIVED AGAN */
 567     OSIP_IST_ACK_RECEIVED,                  /**< ACK MESSAGE RECEIVED */
 568     OSIP_IST_ACK_RECEIVED_AGAIN,            /**< ACK MESSAGE RECEIVED AGAIN */
 569     OSIP_IST_STATUS_1XX_SENT,               /**< 1XX FOR INVITE SENT */
 570     OSIP_IST_STATUS_2XX_SENT,               /**< 2XX FOR INVITE SENT */
 571     OSIP_IST_STATUS_2XX_SENT_AGAIN,         /**< 2XX FOR INVITE RETRANSMITTED */
 572     OSIP_IST_STATUS_3XX_SENT,               /**< 3XX FOR INVITE SENT */
 573     OSIP_IST_STATUS_4XX_SENT,               /**< 4XX FOR INVITE SENT */
 574     OSIP_IST_STATUS_5XX_SENT,               /**< 5XX FOR INVITE SENT */
 575     OSIP_IST_STATUS_6XX_SENT,               /**< 6XX FOR INVITE SENT */
 576     OSIP_IST_STATUS_3456XX_SENT_AGAIN,      /**< RESPONSE RETRANSMITTED */
 577
 578     OSIP_NICT_REGISTER_SENT,                /**< REGISTER MESSAGE SENT */
 579     OSIP_NICT_BYE_SENT,                     /**< BYE MESSAGE SENT */
 580     OSIP_NICT_OPTIONS_SENT,                 /**< OPTIONS MESSAGE SENT */
 581     OSIP_NICT_INFO_SENT,                    /**< INFO MESSAGE SENT */
 582     OSIP_NICT_CANCEL_SENT,                  /**< CANCEL MESSAGE SENT */
 583     OSIP_NICT_NOTIFY_SENT,                  /**< NOTIFY MESSAGE SENT */
 584     OSIP_NICT_SUBSCRIBE_SENT,               /**< SUBSCRIBE MESSAGE SENT */
 585     OSIP_NICT_UNKNOWN_REQUEST_SENT,         /**< UNKNOWN REQUEST MESSAGE SENT */
 586     OSIP_NICT_REQUEST_SENT_AGAIN,           /**< REQUEST MESSAGE RETRANMITTED */
 587     OSIP_NICT_STATUS_1XX_RECEIVED,          /**< 1XX FOR MESSAGE RECEIVED */
 588     OSIP_NICT_STATUS_2XX_RECEIVED,          /**< 2XX FOR MESSAGE RECEIVED */
 589     OSIP_NICT_STATUS_2XX_RECEIVED_AGAIN,    /**< 2XX FOR MESSAGE RECEIVED AGAIN */
 590     OSIP_NICT_STATUS_3XX_RECEIVED,          /**< 3XX FOR MESSAGE RECEIVED */
 591     OSIP_NICT_STATUS_4XX_RECEIVED,          /**< 4XX FOR MESSAGE RECEIVED */
 592     OSIP_NICT_STATUS_5XX_RECEIVED,          /**< 5XX FOR MESSAGE RECEIVED */
 593     OSIP_NICT_STATUS_6XX_RECEIVED,          /**< 6XX FOR MESSAGE RECEIVED */
 594     OSIP_NICT_STATUS_3456XX_RECEIVED_AGAIN, /**< RESPONSE RECEIVED AGAIN */
 595
 596     OSIP_NIST_REGISTER_RECEIVED,            /**< REGISTER RECEIVED */
 597     OSIP_NIST_BYE_RECEIVED,                 /**< BYE RECEIVED */
 598     OSIP_NIST_OPTIONS_RECEIVED,             /**< OPTIONS RECEIVED */
 599     OSIP_NIST_INFO_RECEIVED,                /**< INFO RECEIVED */
 600     OSIP_NIST_CANCEL_RECEIVED,              /**< CANCEL RECEIVED */
 601     OSIP_NIST_NOTIFY_RECEIVED,              /**< NOTIFY RECEIVED */
 602     OSIP_NIST_SUBSCRIBE_RECEIVED,           /**< SUBSCRIBE RECEIVED */
 603
 604     OSIP_NIST_UNKNOWN_REQUEST_RECEIVED,     /**< UNKNWON REQUEST RECEIVED */
 605     OSIP_NIST_REQUEST_RECEIVED_AGAIN,       /**< UNKNWON REQUEST RECEIVED AGAIN */
 606     OSIP_NIST_STATUS_1XX_SENT,              /**< 1XX FOR MESSAGE SENT */
 607     OSIP_NIST_STATUS_2XX_SENT,              /**< 2XX FOR MESSAGE SENT */
 608     OSIP_NIST_STATUS_2XX_SENT_AGAIN,        /**< 2XX FOR MESSAGE RETRANSMITTED */
 609     OSIP_NIST_STATUS_3XX_SENT,              /**< 3XX FOR MESSAGE SENT */
 610     OSIP_NIST_STATUS_4XX_SENT,              /**< 4XX FOR MESSAGE SENT */
 611     OSIP_NIST_STATUS_5XX_SENT,              /**< 5XX FOR MESSAGE SENT */
 612     OSIP_NIST_STATUS_6XX_SENT,              /**< 6XX FOR MESSAGE SENT */
 613     OSIP_NIST_STATUS_3456XX_SENT_AGAIN,     /**< RESPONSE RETRANSMITTED */
 614
 615     OSIP_MESSAGE_CALLBACK_COUNT             /**< END OF ENUM */
 616   } osip_message_callback_type_t;
 617
 618 /**
 619  * Enumeration for callback type used when transaction is over.
 620  */
 621   typedef enum osip_kill_callback_type
 622   {
 623     OSIP_ICT_KILL_TRANSACTION,      /**< end of Client INVITE transaction */
 624     OSIP_IST_KILL_TRANSACTION,      /**< end of Server INVITE transaction */
 625     OSIP_NICT_KILL_TRANSACTION,     /**< end of Client Non-INVITE transaction */
 626     OSIP_NIST_KILL_TRANSACTION,     /**< end of Server Non-INVITE transaction */
 627
 628     OSIP_KILL_CALLBACK_COUNT        /**< END OF ENUM */
 629   } osip_kill_callback_type_t;
 630
 631 /**
 632  * Enumeration for callback type used when a transport error is detected.
 633  */
 634   typedef enum osip_transport_error_callback_type
 635   {
 636     OSIP_ICT_TRANSPORT_ERROR,             /**< transport error for ICT */
 637     OSIP_IST_TRANSPORT_ERROR,             /**< transport error for IST */
 638     OSIP_NICT_TRANSPORT_ERROR,            /**< transport error for NICT */
 639     OSIP_NIST_TRANSPORT_ERROR,            /**< transport error for NIST */
 640
 641     OSIP_TRANSPORT_ERROR_CALLBACK_COUNT   /**< END OF ENUM */
 642   } osip_transport_error_callback_type_t;
 643
 644   typedef void (*osip_message_cb_t) (int type, osip_transaction_t *,
 645                                      osip_message_t *);
 646   typedef void (*osip_kill_transaction_cb_t) (int type, osip_transaction_t *);
 647   typedef void (*osip_transport_error_cb_t) (int type, osip_transaction_t *,
 648                                              int error);
 649
 650
 651 #ifdef OSIP_RETRANSMIT_2XX
 652   struct osip_dialog;
 653
 654   typedef struct ixt_t ixt_t;
 655
 656   struct ixt_t
 657   {
 658     /* any ACK received that match this context will set counter to -1 */
 659     struct osip_dialog *dialog;
 660     osip_message_t *msg2xx;     /* copy of string to retransmit */
 661     osip_message_t *ack;        /* useless for ist */
 662     time_t start;
 663     int interval;               /* between each retransmission, in ms */
 664     char *dest;
 665     int port;
 666     int sock;
 667     int counter;                /* start at 7 */
 668   };
 669
 670 #endif
 671
 672 /**
 673  * Structure for osip handling.
 674  * In order to use osip, you have to manage at least one global instance
 675  * of an osip_t element. Then, you'll register a set of required callbacks
 676  * and a set of optional ones.
 677  * @defvar osip_t
 678  */
 679   typedef struct osip osip_t;
 680
 681   struct osip
 682   {
 683
 684     void *application_context;  /* a pointer for your personnal usage */
 685
 686     /* list of transactions for ict, ist, nict, nist */
 687     osip_list_t *osip_ict_transactions;
 688     osip_list_t *osip_ist_transactions;
 689     osip_list_t *osip_nict_transactions;
 690     osip_list_t *osip_nist_transactions;
 691
 692     osip_list_t *ixt_retransmissions;   /* for retransmission of 2xx & ACK for INVITE */
 693
 694     osip_message_cb_t msg_callbacks[OSIP_MESSAGE_CALLBACK_COUNT];
 695     osip_kill_transaction_cb_t kill_callbacks[OSIP_KILL_CALLBACK_COUNT];
 696     osip_transport_error_cb_t
 697       tp_error_callbacks[OSIP_TRANSPORT_ERROR_CALLBACK_COUNT];
 698
 699     /* callbacks for sending messages */
 700     int (*cb_send_message) (osip_transaction_t *, osip_message_t *, char *,
 701                             int, int);
 702   };
 703
 704 /**
 705  * Set a callback for each transaction operation.
 706  * @param osip The element to work on.
 707  * @param type The event type to hook on.
 708  * @param cb The method to be called upon the event.
 709  */
 710   int osip_set_message_callback (osip_t *osip, int type, osip_message_cb_t cb);
 711
 712 /**
 713  * Set a callback for transaction operation related to the end of transactions.
 714  * @param osip The element to work on.
 715  * @param type The event type to hook on.
 716  * @param cb The method to be called upon the event.
 717  */
 718   int osip_set_kill_transaction_callback (osip_t *osip, int type,
 719                                           osip_kill_transaction_cb_t cb);
 720
 721 /**
 722  * Set a callback for each transaction operation related to network error.
 723  * @param osip The element to work on.
 724  * @param type The event type to hook on.
 725  * @param cb The method to be called upon the event.
 726  */
 727   int osip_set_transport_error_callback (osip_t *osip, int type,
 728                                          osip_transport_error_cb_t cb);
 729
 730 /**
 731  * Structure for sipevent handling.
 732  * A osip_event_t element will have a type and will be related
 733  * to a transaction. In the general case, it is used by the
 734  * application layer to give SIP messages to the oSIP finite
 735  * state machine.
 736  * @defvar osip_event_t
 737  */
 738   typedef struct osip_event osip_event_t;
 739
 740   struct osip_event
 741   {
 742     type_t type;
 743     int transactionid;
 744     osip_message_t *sip;
 745   };
 746
 747
 748
 749 /**
 750  * Allocate an osip_transaction_t element.
 751  * @param transaction The element to allocate.
 752  * @param ctx_type The type of transaction. (ICT, IST, NICT, NIST)
 753  * @param osip The global instance of oSIP.
 754  * @param request The SIP request that initiate the transaction.
 755  */
 756   int osip_transaction_init (osip_transaction_t ** transaction,
 757                              osip_fsm_type_t ctx_type, osip_t * osip,
 758                              osip_message_t * request);
 759 /**
 760  * Free all resource in a osip_transaction_t element.
 761  * @param transaction The element to free.
 762  */
 763   int osip_transaction_free (osip_transaction_t * transaction);
 764 /**
 765  * Free all resource in a osip_transaction_t element.
 766  * This method does the same than osip_transaction_free() but it assumes
 767  * that the transaction is already removed from the list of transaction
 768  * in the osip stack. (to remove it use osip_xixt_remove(osip, transaction);
 769  * @param transaction The element to free.
 770  */
 771   int osip_transaction_free2 (osip_transaction_t * transaction);
 772
 773 /**
 774  * Set the host and port destination used for sending the SIP message.
 775  * This can be useful for an application with 'DIRECT ROOTING MODE'
 776  * NOTE: Instead, you should use the 'Route' header facility which
 777  * leads to the same behaviour.
 778  * @param ict The element to work on.
 779  * @param destination The destination host.
 780  * @param port The destination port.
 781  */
 782   int osip_ict_set_destination (osip_ict_t * ict, char *destination,
 783                                 int port);
 784
 785 /**
 786  * Set the host and port destination used for sending the SIP message.
 787  * This can be useful for an application with 'DIRECT ROOTING MODE'
 788  * NOTE: Instead, you should use the 'Route' header facility which
 789  * leads to the same behaviour.
 790  * @param nict The element to work on.
 791  * @param destination The destination host.
 792  * @param port The destination port.
 793  */
 794   int osip_nict_set_destination (osip_nict_t * nict, char *destination,
 795                                  int port);
 796
 797 /**
 798  * Add a SIP event in the fifo of a osip_transaction_t element.
 799  * @param transaction The element to work on.
 800  * @param evt The event to add.
 801  */
 802   int osip_transaction_add_event (osip_transaction_t * transaction,
 803                                   osip_event_t * evt);
 804 /**
 805  * Consume one osip_event_t element previously added in the fifo.
 806  * NOTE: This method MUST NEVER be called within another call
 807  * of this method. (For example, you can't call osip_transaction_execute()
 808  * in a callback registered in the osip_t element.)
 809  * @param transaction The element to free.
 810  * @param evt The element to consume.
 811  */
 812   int osip_transaction_execute (osip_transaction_t * transaction,
 813                                 osip_event_t * evt);
 814 /**
 815  * Set a pointer to your personal context associated with this transaction.
 816  * NOTE: this is a very useful method that allow you to avoid searching
 817  * for your personal context inside the registered callbacks.
 818  * You can initialise this pointer to your context right after
 819  * the creation of the osip_transaction_t element. Then, you'll be
 820  * able to get the address of your context by calling
 821  * osip_transaction_get_your_instance().
 822  * @param transaction The element to work on.
 823  * @param instance The address of your context.
 824  */
 825   int osip_transaction_set_your_instance (osip_transaction_t * transaction,
 826                                           void *instance);
 827 /**
 828  * Get a pointer to your personal context associated with this transaction.
 829  * @param transaction The element to work on.
 830  */
 831   void *osip_transaction_get_your_instance (osip_transaction_t * transaction);
 832
 833 /**
 834  * Get target ip and port for this request.
 835  * (automaticly set by osip_transaction_init() for ict and nict)
 836  * @param transaction The element to work on.
 837  * @param ip The ip of host where to send initial request.
 838  * @param port The port where to send initial request.
 839  */
 840   int osip_transaction_get_destination (osip_transaction_t * transaction,
 841                                         char **ip, int *port);
 842
 843 #ifndef DOXYGEN
 844
 845 /**
 846  * Set the socket for incoming message.
 847  * NOTE: THIS HAS NEVER TESTED! Please send feedback.
 848  * @param transaction The element to work on.
 849  * @param sock The socket for incoming message.
 850  */
 851   int osip_transaction_set_in_socket (osip_transaction_t * transaction,
 852                                       int sock);
 853 /**
 854  * Set the socket for outgoing message.
 855  * NOTE: THIS HAS NEVER TESTED! Please send feedback.
 856  * @param transaction The element to work on.
 857  * @param sock The socket for outgoing message.
 858  */
 859   int osip_transaction_set_out_socket (osip_transaction_t * transaction,
 860                                        int sock);
 861
 862
 863 #if 0
 864
 865
 866 /**
 867  * Check if the first 2 parameters match the other ones.
 868  * NOTE: THIS IS AN INTERNAL METHOD ONLY
 869  * @param to1 The initial to header.
 870  * @param from1 The initial from header.
 871  * @param to2 The new to header.
 872  * @param from2 The new from header.
 873  */
 874   int callleg_match (osip_to_t * to1, osip_from_t * from1, osip_to_t * to2,
 875                      osip_from_t * from2);
 876
 877 #endif
 878
 879 #endif                          /* endif DOXYGEN */
 880
 881
 882 /**
 883  * Allocate an osip_t element.
 884  * @param osip the element to allocate.
 885  */
 886   int osip_init (osip_t ** osip);
 887 /**
 888  * Free all resource in a osip_t element.
 889  * @param osip The element to release.
 890  */
 891   void osip_release (osip_t * osip);
 892
 893 /**
 894  * Set a pointer in a osip_t element.
 895  * This help to find your application layer in callbacks.
 896  * @param osip The element to work on.
 897  * @param pointer The element to set.
 898  */
 899   void osip_set_application_context (osip_t * osip, void *pointer);
 900
 901 /**
 902  * Get a pointer in a osip_t element.
 903  * This help to find your application layer in callbacks.
 904  * @param osip The element to work on.
 905  */
 906   void *osip_get_application_context (osip_t * osip);
 907
 908
 909 /**
 910  * Remove a transaction from the osip stack.
 911  * @param osip The element to work on.
 912  * @param ict The transaction to add.
 913  */
 914   int osip_remove_transaction (osip_t * osip, osip_transaction_t * ict);
 915
 916
 917 /**
 918  * Consume ALL pending osip_event_t previously added in the fifos of ict transactions.
 919  * @param osip The element to work on.
 920  */
 921   int osip_ict_execute (osip_t * osip);
 922 /**
 923  * Consume ALL pending osip_event_t previously added in the fifos of ist transactions.
 924  * @param osip The element to work on.
 925  */
 926   int osip_ist_execute (osip_t * osip);
 927 /**
 928  * Consume ALL pending osip_event_t previously added in the fifos of nict transactions.
 929  * @param osip The element to work on.
 930  */
 931   int osip_nict_execute (osip_t * osip);
 932 /**
 933  * Consume ALL pending osip_event_t previously added in the fifos of nist transactions.
 934  * @param osip The element to work on.
 935  */
 936   int osip_nist_execute (osip_t * osip);
 937
 938 /**
 939  * Retreive the minimum timer value to be used by an application
 940  * so that the osip_timer_*_execute method don't have to be called
 941  * often.
 942  *
 943  * @param osip The element to work on.
 944  * @param lower_tv The minimum timer when the application should wake up.
 945  */
 946   void osip_timers_gettimeout (osip_t * osip, struct timeval *lower_tv);
 947
 948 /**
 949  * Check if an ict transactions needs a timer event.
 950  * @param osip The element to work on.
 951  */
 952   void osip_timers_ict_execute (osip_t * osip);
 953 /**
 954  * Check if an ist transactions needs a timer event.
 955  * @param osip The element to work on.
 956  */
 957   void osip_timers_ist_execute (osip_t * osip);
 958 /**
 959  * Check if a nict transactions needs a timer event.
 960  * @param osip The element to work on.
 961  */
 962   void osip_timers_nict_execute (osip_t * osip);
 963 /**
 964  * Check if a nist transactions needs a timer event.
 965  * @param osip The element to work on.
 966  */
 967   void osip_timers_nist_execute (osip_t * osip);
 968
 969 /* Take care of mutlithreading issuewhile using this method */
 970 /**
 971  * Search for a transaction that match this event (MUST be a MESSAGE event).
 972  * @param transactions The list of transactions to work on.
 973  * @param evt The element representing the SIP MESSAGE.
 974  */
 975   osip_transaction_t *osip_transaction_find (osip_list_t * transactions,
 976                                              osip_event_t * evt);
 977
 978
 979 #ifndef DOXYGEN
 980 /**
 981  * Some race conditions can happen in multi threaded applications.
 982  * Use this method carefully.
 983  * <BR>Search for a transaction that match this event (MUST be a MESSAGE event).
 984  * @param osip The element to work on.
 985  * @param evt The element representing the SIP MESSAGE.
 986  */
 987 #ifndef OSIP_MT
 988   osip_transaction_t *osip_find_transaction (osip_t * osip,
 989                                              osip_event_t * evt);
 990 #endif
 991
 992   osip_transaction_t *__osip_find_transaction (osip_t * osip,
 993                                                osip_event_t * evt,
 994                                                int consume);
 995 #endif
 996
 997 /**
 998  * Search for a transaction that match this event (MUST be a MESSAGE event)
 999  * and add this event if a transaction is found..
1000  * @param osip The element to work on.
1001  * @param evt The element representing the SIP MESSAGE.
1002  */
1003   int osip_find_transaction_and_add_event (osip_t * osip, osip_event_t * evt);
1004
1005 /**
1006  * Create a transaction for this event (MUST be a SIP REQUEST event).
1007  * @param osip The element to work on.
1008  * @param evt The element representing the new SIP REQUEST.
1009  */
1010   osip_transaction_t *osip_create_transaction (osip_t * osip,
1011                                                osip_event_t * evt);
1012
1013 /**
1014  * Create a sipevent from a SIP message string.
1015  * @param buf The SIP message as a string.
1016  */
1017   osip_event_t *osip_parse (char *buf);
1018
1019
1020 #ifdef OSIP_RETRANSMIT_2XX
1021
1022   void osip_retransmissions_execute (osip_t * osip);
1023
1024 /**
1025  * Start out of fsm 200 Ok retransmissions. This is usefull for user-agents.
1026  * @param osip The osip_t structure.
1027  * @param dialog The dialog the 200 Ok is part of.
1028  * @param msg200ok The 200 ok response.
1029  * @param sock The socket to be used to send the message. (optional).
1030  */
1031   void osip_start_200ok_retransmissions (osip_t * osip,
1032                                          struct osip_dialog *dialog,
1033                                          osip_message_t * msg200ok, int sock);
1034
1035 /**
1036  * Start out of fsm ACK retransmissions. This is usefull for user-agents.
1037  * @param osip The osip_t structure.
1038  * @param dialog The dialog the ACK is part of.
1039  * @param ack The ACK that has just been sent in response to a 200 Ok.
1040  * @param dest The destination host.
1041  * @param sock The destination port.
1042  * @param sock The socket to be used to send the message. (optional).
1043  */
1044   void osip_start_ack_retransmissions (osip_t * osip,
1045                                        struct osip_dialog *dialog,
1046                                        osip_message_t * ack, char *dest,
1047                                        int port, int sock);
1048
1049 /**
1050  * Stop the out of fsm 200 Ok retransmissions matching an incoming ACK.
1051  * @param osip The osip_t structure.
1052  * @param ack  The ack that has just been received.
1053  */
1054   void osip_stop_200ok_retransmissions (osip_t * osip, osip_message_t * ack);
1055
1056 /**
1057  * Stop out of fsm retransmissions (ACK or 200 Ok) associated to a given dialog.
1058  * This function must be called before freeing a dialog if out of fsm retransmissions
1059  * have been scheduled.
1060  * @param osip The osip_t structure
1061  * @param dialog The dialog.
1062  */
1063   void osip_stop_retransmissions_from_dialog (osip_t * osip,
1064                                               struct osip_dialog *dialog);
1065
1066 #endif
1067
1068 /**
1069  * Allocate a sipevent (we know this message is an OUTGOING SIP message).
1070  * @param sip The SIP message we want to send.
1071  */
1072   osip_event_t *osip_new_outgoing_sipmessage (osip_message_t * sip);
1073
1074 /**
1075  * Free all ressource in a sipevent.
1076  * @param event The event to free.
1077  */
1078   void osip_event_free (osip_event_t * event);
1079
1080 /**
1081  * Register the callback used to send SIP message.
1082  * @param cf The osip element attached to the transaction.
1083  * @param cb The method we want to register.
1084  */
1085   void osip_set_cb_send_message (osip_t * cf,
1086                                  int (*cb) (osip_transaction_t *,
1087                                             osip_message_t *, char *,
1088                                             int, int));
1089
1090 /* FOR INCOMING TRANSACTION */
1091 /**
1092  * Check if the sipevent is of type RCV_REQINVITE.
1093  * @param event the event to check.
1094  */
1095 #define EVT_IS_RCV_INVITE(event)       (event->type==RCV_REQINVITE)
1096 /**
1097  * Check if the sipevent is of type RCV_REQACK.
1098  * @param event the event to check.
1099  */
1100 #define EVT_IS_RCV_ACK(event)          (event->type==RCV_REQACK)
1101 /**
1102  * Check if the sipevent is of type RCV_REQUEST.
1103  * @param event the event to check.
1104  */
1105 #define EVT_IS_RCV_REQUEST(event)      (event->type==RCV_REQUEST)
1106 /**
1107  * Check if the sipevent is of type RCV_STATUS_1XX.
1108  * @param event the event to check.
1109  */
1110 #define EVT_IS_RCV_STATUS_1XX(event)   (event->type==RCV_STATUS_1XX)
1111 /**
1112  * Check if the sipevent is of type RCV_STATUS_2XX.
1113  * @param event the event to check.
1114  */
1115 #define EVT_IS_RCV_STATUS_2XX(event)   (event->type==RCV_STATUS_2XX)
1116 /**
1117  * Check if the sipevent is of type RCV_STATUS_3456XX.
1118  * @param event the event to check.
1119  */
1120 #define EVT_IS_RCV_STATUS_3456XX(event)   (event->type==RCV_STATUS_3456XX)
1121
1122
1123 /* FOR OUTGOING TRANSACTION */
1124 /**
1125  * Check if the sipevent is of type SND_REQINVITE.
1126  * @param event the event to check.
1127  */
1128 #define EVT_IS_SND_INVITE(event)       (event->type==SND_REQINVITE)
1129 /**
1130  * Check if the sipevent is of type SND_REQACK.
1131  * @param event the event to check.
1132  */
1133 #define EVT_IS_SND_ACK(event)          (event->type==SND_REQACK)
1134 /**
1135  * Check if the sipevent is of type SND_REQUEST.
1136  * @param event the event to check.
1137  */
1138 #define EVT_IS_SND_REQUEST(event)      (event->type==SND_REQUEST)
1139 /**
1140  * Check if the sipevent is of type SND_STATUS_1XX.
1141  * @param event the event to check.
1142  */
1143 #define EVT_IS_SND_STATUS_1XX(event)   (event->type==SND_STATUS_1XX)
1144 /**
1145  * Check if the sipevent is of type SND_STATUS_2XX.
1146  * @param event the event to check.
1147  */
1148 #define EVT_IS_SND_STATUS_2XX(event)   (event->type==SND_STATUS_2XX)
1149 /**
1150  * Check if the sipevent is of type SND_STATUS_3456XX.
1151  * @param event the event to check.
1152  */
1153 #define EVT_IS_SND_STATUS_3456XX(event)   (event->type==SND_STATUS_3456XX)
1154 /**
1155  * Check if the sipevent is of an incoming SIP MESSAGE.
1156  * @param event the event to check.
1157  */
1158 #define EVT_IS_INCOMINGMSG(event)      (event->type>=RCV_REQINVITE \
1159                                        &&event->type<=RCV_STATUS_3456XX)
1160 /**
1161  * Check if the sipevent is of an incoming SIP REQUEST.
1162  * @param event the event to check.
1163  */
1164 #define EVT_IS_INCOMINGREQ(event)      (EVT_IS_RCV_INVITE(event) \
1165                                        ||EVT_IS_RCV_ACK(event) \
1166                                        ||EVT_IS_RCV_REQUEST(event))
1167 /**
1168  * Check if the sipevent is of an incoming SIP RESPONSE.
1169  * @param event the event to check.
1170  */
1171 #define EVT_IS_INCOMINGRESP(event)     (EVT_IS_RCV_STATUS_1XX(event) \
1172                                        ||EVT_IS_RCV_STATUS_2XX(event) \
1173                                        ||EVT_IS_RCV_STATUS_3456XX(event))
1174 /**
1175  * Check if the sipevent is of an outgoing SIP MESSAGE.
1176  * @param event the event to check.
1177  */
1178 #define EVT_IS_OUTGOINGMSG(event)      (event->type>=SND_REQINVITE \
1179                                        &&event->type<=SND_STATUS_3456XX)
1180 /**
1181  * Check if the sipevent is of an outgoing SIP REQUEST.
1182  * @param event the event to check.
1183  */
1184 #define EVT_IS_OUTGOINGREQ(event)      (EVT_IS_SND_INVITE(event) \
1185                                        ||EVT_IS_SND_ACK(event) \
1186                                        ||EVT_IS_SND_REQUEST(event))
1187 /**
1188  * Check if the sipevent is of an outgoing SIP RESPONSE.
1189  * @param event the event to check.
1190  */
1191 #define EVT_IS_OUTGOINGRESP(event)     (EVT_IS_SND_STATUS_1XX(event) \
1192                                        ||EVT_IS_SND_STATUS_2XX(event) \
1193                                        ||EVT_IS_SND_STATUS_3456XX(event))
1194
1195 /**
1196  * Check if the sipevent is a SIP MESSAGE.
1197  * @param event the event to check.
1198  */
1199 #define EVT_IS_MSG(event)              (event->type>=RCV_REQINVITE \
1200                                        &&event->type<=SND_STATUS_3456XX)
1201 /**
1202  * Check if the sipevent is of type KILL_TRANSACTION.
1203  * NOTE: THIS IS AN INTERNAL METHOD ONLY
1204  * @param event the event to check.
1205  */
1206 #define EVT_IS_KILL_TRANSACTION(event) (event->type==KILL_TRANSACTION)
1207
1208 #ifdef __cplusplus
1209 }
1210 #endif
1211
1212
1213 /** @} */
1214
1215 #endif