userapps/opensource/libosip2/include/osip2/osip_dialog.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 #ifndef _DIALOG_H_
  21 #define _DIALOG_H_
  22
  23 #include <osip2/osip.h>
  24
  25 /**
  26  * @file osip_dialog.h
  27  * @brief oSIP dialog Routines
  28  *
  29  * Dialog management is a powerful facility given by oSIP. This feature is
  30  * needed by SIP end point who has the capability to answer calls. (i.e.
  31  * answering 200 OK to an INVITE).
  32  * <BR>
  33  * A Dialog is a context for a call establishment in oSIP. It's not useless
  34  * to say that ONE invite request can lead to several call establishment.
  35  * This can happen if your call has been forked by a proxy and several
  36  * user agent was contacted and replied at the same time. It is true that
  37  * this case won't probably happen several times a month...
  38  * <BR>
  39  * There is two ways of creating a dialog. In one case, you are the CALLER
  40  * and in the other case, you will be the CALLEE.
  41  * <UL>
  42  * <LI>Creating a dialog as a CALLER
  43  * <BR>In this case, you have to create a dialog each time you receive
  44  * an answer with a code between 101 and 299. The best place in oSIP to
  45  * actually create a dialog is of course in the callback that announce
  46  * such SIP messages. Of course, each time you receive a response, you have
  47  * to check for an existing dialog associated to this INVITE that can have
  48  * been created by earlier SIP answer coming from the same User Agent. The
  49  * code in the callback will look like the following:
  50  * <BR> void cb_rcv1xx(osip_transaction_t *tr,osip_message_t *sip)
  51  * <BR> {
  52  * <BR>   osip_dialog_t *dialog;
  53  * <BR>   if (MSG_IS_RESPONSEFOR(sip, "INVITE")&&!MSG_TEST_CODE(sip, 100)) {
  54  * <BR>     dialog = my_application_search_existing_dialog(sip);
  55  * <BR>     if (dialog==NULL) //NO EXISTING DIALOG
  56  * <BR>       {
  57  * <BR>        i = osip_dialog_init_as_uac(&dialog, sip);
  58  * <BR>        my_application_add_existing_dialog(dialog);
  59  * <BR>       }
  60  * <BR>   } else {
  61  * <BR>     // no dialog establishment for other REQUEST
  62  * <BR> }
  63  * </LI>
  64  * <LI>Creating a dialog as a CALLEE
  65  * <BR>In this case, you will have to create a dialog upon receiving the first
  66  * transmission of the INVITE request. The correct place to do that is inside
  67  * the callback previously registered to announce new INVITE. First, you will
  68  * build a SIP answer like 180 or 200 and you'll be able to create a dialog
  69  * by calling the following code:
  70  * <BR>osip_dialog_t *dialog;
  71  * <BR>osip_dialog_init_as_uas(&dialog, original_invite, response_that_you_build);
  72  * <BR>To make things working, you MUST create a VALID response: do not
  73  * forget to create a new tag and put it in the 'To' header. The dialog
  74  * management heavily depends on this tag.
  75  * </LI>
  76  * </UL>
  77  * <P>The dialog management is compliant with the latest SIP draft
  78  * (rfc2543bis-09). It should handle successfully most cases where
  79  * a remote UA is not compliant (no tag in the To of a final response!)
  80  * But for example, if you receive 2 answers from 2 uncompliant
  81  * UA, they will be detected as being related to the same dialog...
  82  * Do not change any code in oSIP or in your application... instead, you
  83  * should boycott such implementation. :-
  84  */
  85
  86 /**
  87  * @defgroup oSIP_DIALOG oSIP dialog Handling
  88  * @ingroup oSIP
  89  * @{
  90  */
  91
  92 #ifdef __cplusplus
  93 extern "C"
  94 {
  95 #endif
  96
  97
  98 #ifndef DOXYGEN
  99   typedef enum _osip_dialog_type_t
 100   {
 101     CALLER,
 102     CALLEE
 103   }
 104   osip_dialog_type_t;
 105 #endif
 106
 107
 108 /**
 109  * Structure for referencing a dialog.
 110  * @var osip_dialog_t
 111  */
 112   typedef struct osip_dialog osip_dialog_t;
 113
 114
 115 /**
 116  * Structure for referencing a dialog.
 117  */
 118   struct osip_dialog
 119   {
 120     /*  char *dialog_id; ***implied*** *//* call-id:local_tag:remote-tag */
 121     char *call_id;
 122     char *local_tag;
 123     char *remote_tag;
 124     osip_list_t *route_set;
 125     int local_cseq;
 126     int remote_cseq;
 127     osip_to_t *remote_uri;
 128     osip_from_t *local_uri;
 129     osip_contact_t *remote_contact_uri;
 130     int secure;
 131
 132     /* type of dialog (CALLEE or CALLER) */
 133     osip_dialog_type_t type;
 134     state_t state;              /* DIALOG_EARLY || DIALOG_CONFIRMED || DIALOG_CLOSED */
 135   };
 136
 137 /**
 138  * Allocate a osip_dialog_t element as a UAC.
 139  * <UL><LI>NOTE1: Only INVITE transactions can create a dialog.</LI>
 140  * <LI>NOTE2: The dialog should be created when the first response is received.
 141  *        (except for a 100 Trying)</LI>
 142  * <LI>NOTE3: Remote UA should be compliant! If not (not tag in the to header?)
 143  *        the old mechanism is used to match the request but if 2 uncompliant
 144  *        UA both answer 200 OK for the same transaction, they won't be detected.
 145  *        This is a major BUG in the old rfc.</LI></UL>
 146  * @param dialog The element to allocate.
 147  * @param response The response containing the informations.
 148  */
 149   int osip_dialog_init_as_uac (osip_dialog_t ** dialog,
 150                                osip_message_t * response);
 151 /**
 152  * Allocate a osip_dialog_t element as a UAC.
 153  * <UL><LI>This could be used to initiate dialog with a NOTIFY coming
 154  * before the answer for a subscribe has reached us.</LI>
 155  * @param dialog The element to allocate.
 156  * @param next_request The response containing the informations.
 157  * @param local_cseq The local cseq
 158  */
 159   int osip_dialog_init_as_uac_with_remote_request (osip_dialog_t ** dialog,
 160                                                    osip_message_t *
 161                                                    next_request,
 162                                                    int local_cseq);
 163
 164 /**
 165  * Allocate a osip_dialog_t element as a UAS.
 166  * NOTE1: Only INVITE transactions can create a dialog.
 167  * NOTE2: The dialog should be created when the first response is sent.
 168  *        (except for a 100 Trying)
 169  * @param dialog The element to allocate.
 170  * @param invite The INVITE request containing some informations.
 171  * @param response The response containing other informations.
 172  */
 173   int osip_dialog_init_as_uas (osip_dialog_t ** dialog,
 174                                osip_message_t * invite,
 175                                osip_message_t * response);
 176 /**
 177  * Free all resource in a osip_dialog_t element.
 178  * @param dialog The element to free.
 179  */
 180   void osip_dialog_free (osip_dialog_t * dialog);
 181 /**
 182  * Set the state of the dialog.
 183  * This is useful to keep information on who is the initiator of the call.
 184  * @param dialog The element to work on.
 185  * @param type The type of dialog (CALLEE or CALLER).
 186  */
 187   void osip_dialog_set_state (osip_dialog_t * dialog, state_t type);
 188 /**
 189  * Update the Route-Set as UAS of a dialog.
 190  * NOTE: bis-09 says that only INVITE transactions can update the route-set.
 191  * NOTE: bis-09 says that updating the route-set means: update the contact
 192  *       field only (AND NOT THE ROUTE-SET). This method follow this behaviour.
 193  * NOTE: This method should be called for each request (except 100 Trying)
 194  *       received for a dialog.
 195  * @param dialog The element to work on.
 196  * @param invite The invite received.
 197  */
 198   int osip_dialog_update_route_set_as_uas (osip_dialog_t * dialog,
 199                                            osip_message_t * invite);
 200 /**
 201  * Update the CSeq (remote cseq) during a UAS transaction of a dialog.
 202  * NOTE: All INCOMING transactions MUST update the remote CSeq.
 203  * @param dialog The element to work on.
 204  * @param request The request received.
 205  */
 206   int osip_dialog_update_osip_cseq_as_uas (osip_dialog_t * dialog,
 207                                            osip_message_t * request);
 208
 209 /**
 210  * Match a response received with a dialog.
 211  * @param dialog The element to work on.
 212  * @param response The response received.
 213  */
 214   int osip_dialog_match_as_uac (osip_dialog_t * dialog,
 215                                 osip_message_t * response);
 216 /**
 217  * Update the tag as UAC of a dialog?. (this could be needed if the 180
 218  * does not contains any tag, but the 200 contains one.
 219  * @param dialog The element to work on.
 220  * @param response The response received.
 221  */
 222   int osip_dialog_update_tag_as_uac (osip_dialog_t * dialog,
 223                                      osip_message_t * response);
 224 /**
 225  * Update the Route-Set as UAC of a dialog.
 226  * NOTE: bis-09 says that only INVITE transactions can update the route-set.
 227  * NOTE: bis-09 says that updating the route-set means: update the contact
 228  *       field only (AND NOT THE ROUTE-SET). This method follow this behaviour.
 229  * NOTE: This method should be called for each request (except 100 Trying)
 230  *       received for a dialog.
 231  * @param dialog The element to work on.
 232  * @param response The response received.
 233  */
 234   int osip_dialog_update_route_set_as_uac (osip_dialog_t * dialog,
 235                                            osip_message_t * response);
 236
 237 /**
 238  * Match a request (response sent??) received with a dialog.
 239  * @param dialog The element to work on.
 240  * @param request The request received.
 241  */
 242   int osip_dialog_match_as_uas (osip_dialog_t * dialog,
 243                                 osip_message_t * request);
 244
 245 #ifndef DOXYGEN
 246   int osip_dialog_is_originator (osip_dialog_t * dialog);
 247   int osip_dialog_is_callee (osip_dialog_t * dialog);
 248 #endif
 249
 250
 251 #ifdef __cplusplus
 252 }
 253 #endif
 254
 255 /** @} */
 256
 257
 258 #endif