osip.h

OSIP stack client source code

    osip_nict_t *nict_context;  /**@internal */
    osip_nist_t *nist_context;  /**@internal */

	osip_srv_record_t record;   /**@internal */
  };


/**
 * Enumeration for callback type.
 */
  typedef enum osip_message_callback_type
  {
    OSIP_ICT_INVITE_SENT = 0,               /**< INVITE MESSAGE SENT */
    OSIP_ICT_INVITE_SENT_AGAIN,             /**< INVITE MESSAGE RETRANSMITTED */
    OSIP_ICT_ACK_SENT,                      /**< ACK MESSAGE SENT */
    OSIP_ICT_ACK_SENT_AGAIN,                /**< ACK MESSAGE RETRANSMITTED */
    OSIP_ICT_STATUS_1XX_RECEIVED,           /**< 1XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_2XX_RECEIVED,           /**< 2XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_2XX_RECEIVED_AGAIN,     /**< 2XX FOR INVITE RECEIVED AGAIN */
    OSIP_ICT_STATUS_3XX_RECEIVED,           /**< 3XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_4XX_RECEIVED,           /**< 4XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_5XX_RECEIVED,           /**< 5XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_6XX_RECEIVED,           /**< 6XX FOR INVITE RECEIVED */
    OSIP_ICT_STATUS_3456XX_RECEIVED_AGAIN,  /**< RESPONSE RECEIVED AGAIN */

    OSIP_IST_INVITE_RECEIVED,               /**< INVITE MESSAGE RECEIVED */
    OSIP_IST_INVITE_RECEIVED_AGAIN,         /**< INVITE MESSAGE RECEIVED AGAN */
    OSIP_IST_ACK_RECEIVED,                  /**< ACK MESSAGE RECEIVED */
    OSIP_IST_ACK_RECEIVED_AGAIN,            /**< ACK MESSAGE RECEIVED AGAIN */
    OSIP_IST_STATUS_1XX_SENT,               /**< 1XX FOR INVITE SENT */
    OSIP_IST_STATUS_2XX_SENT,               /**< 2XX FOR INVITE SENT */
    OSIP_IST_STATUS_2XX_SENT_AGAIN,         /**< 2XX FOR INVITE RETRANSMITTED */
    OSIP_IST_STATUS_3XX_SENT,               /**< 3XX FOR INVITE SENT */
    OSIP_IST_STATUS_4XX_SENT,               /**< 4XX FOR INVITE SENT */
    OSIP_IST_STATUS_5XX_SENT,               /**< 5XX FOR INVITE SENT */
    OSIP_IST_STATUS_6XX_SENT,               /**< 6XX FOR INVITE SENT */
    OSIP_IST_STATUS_3456XX_SENT_AGAIN,      /**< RESPONSE RETRANSMITTED */

    OSIP_NICT_REGISTER_SENT,                /**< REGISTER MESSAGE SENT */
    OSIP_NICT_BYE_SENT,                     /**< BYE MESSAGE SENT */
    OSIP_NICT_OPTIONS_SENT,                 /**< OPTIONS MESSAGE SENT */
    OSIP_NICT_INFO_SENT,                    /**< INFO MESSAGE SENT */
    OSIP_NICT_CANCEL_SENT,                  /**< CANCEL MESSAGE SENT */
    OSIP_NICT_NOTIFY_SENT,                  /**< NOTIFY MESSAGE SENT */
    OSIP_NICT_SUBSCRIBE_SENT,               /**< SUBSCRIBE MESSAGE SENT */
    OSIP_NICT_UNKNOWN_REQUEST_SENT,         /**< UNKNOWN REQUEST MESSAGE SENT */
    OSIP_NICT_REQUEST_SENT_AGAIN,           /**< REQUEST MESSAGE RETRANMITTED */
    OSIP_NICT_STATUS_1XX_RECEIVED,          /**< 1XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_2XX_RECEIVED,          /**< 2XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_2XX_RECEIVED_AGAIN,    /**< 2XX FOR MESSAGE RECEIVED AGAIN */
    OSIP_NICT_STATUS_3XX_RECEIVED,          /**< 3XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_4XX_RECEIVED,          /**< 4XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_5XX_RECEIVED,          /**< 5XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_6XX_RECEIVED,          /**< 6XX FOR MESSAGE RECEIVED */
    OSIP_NICT_STATUS_3456XX_RECEIVED_AGAIN, /**< RESPONSE RECEIVED AGAIN */

    OSIP_NIST_REGISTER_RECEIVED,            /**< REGISTER RECEIVED */
    OSIP_NIST_BYE_RECEIVED,                 /**< BYE RECEIVED */
    OSIP_NIST_OPTIONS_RECEIVED,             /**< OPTIONS RECEIVED */
    OSIP_NIST_INFO_RECEIVED,                /**< INFO RECEIVED */
    OSIP_NIST_CANCEL_RECEIVED,              /**< CANCEL RECEIVED */
    OSIP_NIST_NOTIFY_RECEIVED,              /**< NOTIFY RECEIVED */
    OSIP_NIST_SUBSCRIBE_RECEIVED,           /**< SUBSCRIBE RECEIVED */

    OSIP_NIST_UNKNOWN_REQUEST_RECEIVED,     /**< UNKNWON REQUEST RECEIVED */
    OSIP_NIST_REQUEST_RECEIVED_AGAIN,       /**< UNKNWON REQUEST RECEIVED AGAIN */
    OSIP_NIST_STATUS_1XX_SENT,              /**< 1XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_2XX_SENT,              /**< 2XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_2XX_SENT_AGAIN,        /**< 2XX FOR MESSAGE RETRANSMITTED */
    OSIP_NIST_STATUS_3XX_SENT,              /**< 3XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_4XX_SENT,              /**< 4XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_5XX_SENT,              /**< 5XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_6XX_SENT,              /**< 6XX FOR MESSAGE SENT */
    OSIP_NIST_STATUS_3456XX_SENT_AGAIN,     /**< RESPONSE RETRANSMITTED */

    OSIP_ICT_STATUS_TIMEOUT,                /**< TIMER B EXPIRATION: NO REMOTE ANSWER  */
    OSIP_NICT_STATUS_TIMEOUT,               /**< TIMER F EXPIRATION: NO REMOTE ANSWER  */

    OSIP_MESSAGE_CALLBACK_COUNT             /**< END OF ENUM */
  } osip_message_callback_type_t;

/**
 * Enumeration for callback type used when transaction is over.
 */
  typedef enum osip_kill_callback_type
  {
    OSIP_ICT_KILL_TRANSACTION,      /**< end of Client INVITE transaction */
    OSIP_IST_KILL_TRANSACTION,      /**< end of Server INVITE transaction */
    OSIP_NICT_KILL_TRANSACTION,     /**< end of Client Non-INVITE transaction */
    OSIP_NIST_KILL_TRANSACTION,     /**< end of Server Non-INVITE transaction */

    OSIP_KILL_CALLBACK_COUNT        /**< END OF ENUM */
  } osip_kill_callback_type_t;

/**
 * Enumeration for callback type used when a transport error is detected.
 * @enum osip_transport_error_callback_type_t
 */
  typedef enum osip_transport_error_callback_type
  {
    OSIP_ICT_TRANSPORT_ERROR,             /**< transport error for ICT */
    OSIP_IST_TRANSPORT_ERROR,             /**< transport error for IST */
    OSIP_NICT_TRANSPORT_ERROR,            /**< transport error for NICT */
    OSIP_NIST_TRANSPORT_ERROR,            /**< transport error for NIST */

    OSIP_TRANSPORT_ERROR_CALLBACK_COUNT   /**< END OF ENUM */
  } osip_transport_error_callback_type_t;

/**
 * Callback definition for message announcements.
 * @var osip_message_cb_t
 */
  typedef void (*osip_message_cb_t) (int type, osip_transaction_t *,
                                     osip_message_t *);
/**
 * Callback definition for end of transaction announcements.
 * @var osip_kill_transaction_cb_t
 */
  typedef void (*osip_kill_transaction_cb_t) (int type, osip_transaction_t *);
/**
 * Callback definition for transport error announcements.
 * @var osip_transport_error_cb_t
 */
  typedef void (*osip_transport_error_cb_t) (int type, osip_transaction_t *,
                                             int error);


  struct osip_dialog;

/**
 * Structure for 2XX retransmission management.
 * @var ixt_t
 */
  typedef struct ixt_t ixt_t;

/**
 * Structure for 2XX retransmission management.
 * @struct ixt
 */
  struct ixt_t
  {
    /* any ACK received that match this context will set counter to -1 */
    struct osip_dialog *dialog; /**< related dialog */
    osip_message_t *msg2xx;     /**< buffer to retransmit */
    osip_message_t *ack;        /**< ack message if needed */
    struct timeval start;       /**< Time of first retransmission */
    int interval;               /**< delay between retransmission, in ms */
    char *dest;                 /**< destination host */
    int port;                   /**< destination port */
    int sock;                   /**< socket to use */
    int counter;                /**< start at 7 */
  };


/**
 * Structure for osip handling.
 * In order to use osip, you have to manage at least one global instance
 * of an osip_t element. Then, you'll register a set of required callbacks
 * and a set of optional ones.
 * @var osip_t
 */
  typedef struct osip osip_t;

/**
 * Structure for osip handling.
 * @struct osip
 */
  struct osip
  {

    void *application_context;  /**< User defined Pointer */

    /* list of transactions for ict, ist, nict, nist */
    osip_list_t osip_ict_transactions;   /**< list of ict transactions */
    osip_list_t osip_ist_transactions;   /**< list of ist transactions */
    osip_list_t osip_nict_transactions;  /**< list of nict transactions */
    osip_list_t osip_nist_transactions;  /**< list of nist transactions */

    osip_list_t ixt_retransmissions;    /**< list of ixt elements */

    osip_message_cb_t msg_callbacks[OSIP_MESSAGE_CALLBACK_COUNT];        /**@internal */
    osip_kill_transaction_cb_t kill_callbacks[OSIP_KILL_CALLBACK_COUNT]; /**@internal */
    osip_transport_error_cb_t tp_error_callbacks[OSIP_TRANSPORT_ERROR_CALLBACK_COUNT];  /**@internal */

    int (*cb_send_message) (osip_transaction_t *, osip_message_t *, char *,
                            int, int);
                                        /**@internal */

#if defined(HAVE_DICT_DICT_H)
    dict *osip_ict_hastable;              /**< htable of ict transactions */
    dict *osip_ist_hastable;              /**< htable of ist transactions */
    dict *osip_nict_hastable;             /**< htable of nict transactions */
    dict *osip_nist_hastable;             /**< htable of nist transactions */
#endif
  };

/**
 * Set a callback for each transaction operation. 
 * @param osip The element to work on.
 * @param type The event type to hook on.
 * @param cb The method to be called upon the event.
 */
  int osip_set_message_callback (osip_t * osip, int type, osip_message_cb_t cb);

/**
 * Set a callback for transaction operation related to the end of transactions. 
 * @param osip The element to work on.
 * @param type The event type to hook on.
 * @param cb The method to be called upon the event.
 */
  int osip_set_kill_transaction_callback (osip_t * osip, int type,
                                          osip_kill_transaction_cb_t cb);

/**
 * Set a callback for each transaction operation related to network error.
 * @param osip The element to work on.
 * @param type The event type to hook on.
 * @param cb The method to be called upon the event.
 */
  int osip_set_transport_error_callback (osip_t * osip, int type,
                                         osip_transport_error_cb_t cb);

/**
 * Structure for osip event handling.
 * A osip_event_t element will have a type and will be related
 * to a transaction. In the general case, it is used by the
 * application layer to give SIP messages to the oSIP finite
 * state machine.
 * @var osip_event_t
 */
  typedef struct osip_event osip_event_t;

/**
 * Structure for osip event handling.
 * @struct osip_event
 */
  struct osip_event
  {
    type_t type;             /**< Event Type */
    int transactionid;       /**< identifier of the related osip transaction */
    osip_message_t *sip;     /**< SIP message (optional) */
  };



/**
 * Allocate an osip_transaction_t element.
 * @param transaction The element to allocate.
 * @param ctx_type The type of transaction. (ICT, IST, NICT, NIST)
 * @param osip The global instance of oSIP.
 * @param request The SIP request that initiate the transaction.
 */
  int osip_transaction_init (osip_transaction_t ** transaction,
                             osip_fsm_type_t ctx_type, osip_t * osip,
                             osip_message_t * request);
/**
 * Free all resource in a osip_transaction_t element.
 * @param transaction The element to free.
 */
  int osip_transaction_free (osip_transaction_t * transaction);
/**
 * Free all resource in a osip_transaction_t element.
 * This method does the same than osip_transaction_free() but it assumes
 * that the transaction is already removed from the list of transaction
 * in the osip stack. (to remove it use osip_xixt_remove(osip, transaction);
 * @param transaction The element to free.
 */
  int osip_transaction_free2 (osip_transaction_t * transaction);

/**
 * Search in a SIP response the destination where the message
 * should be sent.
 * @param response the message to work on.
 * @param address a pointer to receive the allocated host address.
 * @param portnum a pointer to receive the host port.
 */
  void osip_response_get_destination (osip_message_t * response,
                                      char **address, int *portnum);
/**
 * Set the host and port destination used for sending the SIP message.
 * This can be useful for an application with 'DIRECT ROOTING MODE'
 * NOTE: Instead, you should use the 'Route' header facility which
 * leads to the same behaviour.
 * @param ict The element to work on.
 * @param destination The destination host.
 * @param port The destination port.
 */
  int osip_ict_set_destination (osip_ict_t * ict, char *destination, int port);

/**
 * Set the host and port destination used for sending the SIP message.
 * This can be useful for an application with 'DIRECT ROOTING MODE'
 * NOTE: Instead, you should use the 'Route' header facility which
 * leads to the same behaviour.
 * @param nict The element to work on.
 * @param destination The destination host.
 * @param port The destination port.
 */
  int osip_nict_set_destination (osip_nict_t * nict, char *destination, int port);

/**
 * Add a SIP event in the fifo of a osip_transaction_t element.
 * @param transaction The element to work on.
 * @param evt The event to add.
 */
  int osip_transaction_add_event (osip_transaction_t * transaction,
                                  osip_event_t * evt);
/**
 * Consume one osip_event_t element previously added in the fifo.
 * NOTE: This method MUST NEVER be called within another call
 * of this method. (For example, you can't call osip_transaction_execute()
 * in a callback registered in the osip_t element.)
 * @param transaction The element to free.
 * @param evt The element to consume.
 */
  int osip_transaction_execute (osip_transaction_t * transaction,
                                osip_event_t * evt);
/**
 * Set a pointer to your personal context associated with this transaction.
 * NOTE: this is a very useful method that allow you to avoid searching
 * for your personal context inside the registered callbacks.
 * You can initialise this pointer to your context right after
 * the creation of the osip_transaction_t element. Then, you'll be
 * able to get the address of your context by calling
 * osip_transaction_get_your_instance().
 * @param transaction The element to work on.
 * @param instance The address of your context.
 */
  int osip_transaction_set_your_instance (osip_transaction_t * transaction,
                                          void *instance);
/**
 * Get a pointer to your personal context associated with this transaction.
 * @param transaction The element to work on.
 */
  void *osip_transaction_get_your_instance (osip_transaction_t * transaction);

/**
 * Get target ip and port for this request.
 * (automaticly set by osip_transaction_init() for ict and nict)
 * @param transaction The element to work on.
 * @param ip The ip of host where to send initial request.
 * @param port The port where to send initial request.
 */
  int osip_transaction_get_destination (osip_transaction_t * transaction,
                                        char **ip, int *port);


/**
 * Set SRV lookup information to be used by state machine.
 *
 * @param transaction The element to work on.
 * @param record The SRV lookup results for this transaction.
 */
  int osip_transaction_set_srv_record(osip_transaction_t *transaction, osip_srv_record_t *record);