osip.h

SIP协议栈实现

 * 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);

#ifndef DOXYGEN

/**
 * Set the socket for incoming message.
 * NOTE: THIS HAS NEVER TESTED! Please send feedback.
 * @param transaction The element to work on.
 * @param sock The socket for incoming message.
 */
  int osip_transaction_set_in_socket (osip_transaction_t * transaction, int sock);
/**
 * Set the socket for outgoing message.
 * NOTE: THIS HAS NEVER TESTED! Please send feedback.
 * @param transaction The element to work on.
 * @param sock The socket for outgoing message.
 */
  int osip_transaction_set_out_socket (osip_transaction_t * transaction, int sock);


#if 0


/**
 * Check if the first 2 parameters match the other ones.
 * NOTE: THIS IS AN INTERNAL METHOD ONLY
 * @param to1 The initial to header.
 * @param from1 The initial from header.
 * @param to2 The new to header.
 * @param from2 The new from header.
 */
  int callleg_match (osip_to_t * to1, osip_from_t * from1, osip_to_t * to2, osip_from_t * from2);

#endif

#endif				/* endif DOXYGEN */


/** 
 * Allocate an osip_t element.
 * @param osip the element to allocate.
 */
  int osip_init (osip_t ** osip);
/**
 * Free all resource in a osip_t element.
 * @param osip The element to release.
 */
  void osip_release (osip_t * osip);

/**
 * Set a pointer in a osip_t element.
 * This help to find your application layer in callbacks.
 * @param osip The element to work on.
 * @param pointer The element to set.
 */
  void osip_set_application_context (osip_t * osip, void *pointer);

/**
 * Get a pointer in a osip_t element.
 * This help to find your application layer in callbacks.
 * @param osip The element to work on.
 */
  void *osip_get_application_context (osip_t * osip);


/**
 * Remove a transaction from the osip stack.
 * @param osip The element to work on.
 * @param ict The transaction to add.
 */
  int osip_remove_transaction (osip_t * osip, osip_transaction_t * ict);


/**
 * Consume ALL pending osip_event_t previously added in the fifos of ict transactions.
 * @param osip The element to work on.
 */
  int osip_ict_execute (osip_t * osip);
/**
 * Consume ALL pending osip_event_t previously added in the fifos of ist transactions.
 * @param osip The element to work on.
 */
  int osip_ist_execute (osip_t * osip);
/**
 * Consume ALL pending osip_event_t previously added in the fifos of nict transactions.
 * @param osip The element to work on.
 */
  int osip_nict_execute (osip_t * osip);
/**
 * Consume ALL pending osip_event_t previously added in the fifos of nist transactions.
 * @param osip The element to work on.
 */
  int osip_nist_execute (osip_t * osip);

/**
 * Check if an ict transactions needs a timer event.
 * @param osip The element to work on.
 */
  void osip_timers_ict_execute (osip_t * osip);
/**
 * Check if an ist transactions needs a timer event.
 * @param osip The element to work on.
 */
  void osip_timers_ist_execute (osip_t * osip);
/**
 * Check if a nict transactions needs a timer event.
 * @param osip The element to work on.
 */
  void osip_timers_nict_execute (osip_t * osip);
/**
 * Check if a nist transactions needs a timer event.
 * @param osip The element to work on.
 */
  void osip_timers_nist_execute (osip_t * osip);

/* Take care of mutlithreading issuewhile using this method */
/**
 * Search for a transaction that match this event (MUST be a MESSAGE event).
 * @param transactions The list of transactions to work on.
 * @param evt The element representing the SIP MESSAGE.
 */
  osip_transaction_t *osip_transaction_find (osip_list_t * transactions,
					     osip_event_t * evt);
  

#ifndef DOXYGEN
/**
 * Some race conditions can happen in multi threaded applications.
 * Use this method carefully.
 * <BR>Search for a transaction that match this event (MUST be a MESSAGE event).
 * @param osip The element to work on.
 * @param evt The element representing the SIP MESSAGE.
 */
#ifndef OSIP_MT
  osip_transaction_t *osip_find_transaction (osip_t * osip, osip_event_t * evt);
#endif

  osip_transaction_t *__osip_find_transaction (osip_t * osip,
					       osip_event_t * evt,
					       int consume);
#endif

/**
 * Search for a transaction that match this event (MUST be a MESSAGE event)
 * and add this event if a transaction is found..
 * @param osip The element to work on.
 * @param evt The element representing the SIP MESSAGE.
 */
  int osip_find_transaction_and_add_event (osip_t * osip, osip_event_t * evt);

/**
 * Create a transaction for this event (MUST be a SIP REQUEST event).
 * @param osip The element to work on.
 * @param evt The element representing the new SIP REQUEST.
 */
  osip_transaction_t *osip_create_transaction (osip_t * osip, osip_event_t * evt);

/**
 * Create a sipevent from a SIP message string.
 * @param buf The SIP message as a string.
 */
  osip_event_t *osip_parse (char *buf);


#ifdef OSIP_RETRANSMIT_2XX

  void osip_retransmissions_execute(osip_t *osip);

/**
 * Start out of fsm 200 Ok retransmissions. This is usefull for user-agents.
 * @param osip The osip_t structure.
 * @param dialog The dialog the 200 Ok is part of.
 * @param msg200ok The 200 ok response.
 * @param sock The socket to be used to send the message. (optional).
 */
  void osip_start_200ok_retransmissions(osip_t *osip, struct osip_dialog *dialog, osip_message_t *msg200ok, int sock);

/**
 * Start out of fsm ACK retransmissions. This is usefull for user-agents.
 * @param osip The osip_t structure.
 * @param dialog The dialog the ACK is part of.
 * @param ack The ACK that has just been sent in response to a 200 Ok.
 * @param dest The destination host.
 * @param sock The destination port.
 * @param sock The socket to be used to send the message. (optional).
 */
  void osip_start_ack_retransmissions(osip_t *osip, struct osip_dialog *dialog, osip_message_t *ack, char *dest, int port, int sock);

/**
 * Stop the out of fsm 200 Ok retransmissions matching an incoming ACK.
 * @param osip The osip_t structure.
 * @param ack  The ack that has just been received.
 */
  void osip_stop_200ok_retransmissions(osip_t *osip, osip_message_t *ack);

/**
 * Stop out of fsm retransmissions (ACK or 200 Ok) associated to a given dialog.
 * This function must be called before freeing a dialog if out of fsm retransmissions
 * have been scheduled.
 * @param osip The osip_t structure
 * @param dialog The dialog.
 */
  void osip_stop_retransmissions_from_dialog(osip_t *osip, struct osip_dialog *dialog);

#endif

/**
 * Allocate a sipevent (we know this message is an OUTGOING SIP message).
 * @param sip The SIP message we want to send.
 */
  osip_event_t *osip_new_outgoing_sipmessage (osip_message_t * sip);

/**
 * Free all ressource in a sipevent.
 * @param event The event to free.
 */
  void osip_event_free( osip_event_t *event );

/**
 * Register the callback used to send SIP message.
 * @param cf The osip element attached to the transaction.
 * @param cb The method we want to register.
 */
  void osip_set_cb_send_message (osip_t * cf,
				 int (*cb) (osip_transaction_t *,
					    osip_message_t *, char *,
					    int, int));

/* FOR INCOMING TRANSACTION */
/**
 * Check if the sipevent is of type RCV_REQINVITE.
 * @param event the event to check.
 */
#define EVT_IS_RCV_INVITE(event)       (event->type==RCV_REQINVITE)
/**
 * Check if the sipevent is of type RCV_REQACK.
 * @param event the event to check.
 */
#define EVT_IS_RCV_ACK(event)          (event->type==RCV_REQACK)
/**
 * Check if the sipevent is of type RCV_REQUEST.
 * @param event the event to check.
 */
#define EVT_IS_RCV_REQUEST(event)      (event->type==RCV_REQUEST)
/**
 * Check if the sipevent is of type RCV_STATUS_1XX.
 * @param event the event to check.
 */
#define EVT_IS_RCV_STATUS_1XX(event)   (event->type==RCV_STATUS_1XX)
/**
 * Check if the sipevent is of type RCV_STATUS_2XX.
 * @param event the event to check.
 */
#define EVT_IS_RCV_STATUS_2XX(event)   (event->type==RCV_STATUS_2XX)
/**
 * Check if the sipevent is of type RCV_STATUS_3456XX.
 * @param event the event to check.
 */
#define EVT_IS_RCV_STATUS_3456XX(event)   (event->type==RCV_STATUS_3456XX)


/* FOR OUTGOING TRANSACTION */
/**
 * Check if the sipevent is of type SND_REQINVITE.
 * @param event the event to check.
 */
#define EVT_IS_SND_INVITE(event)       (event->type==SND_REQINVITE)
/**
 * Check if the sipevent is of type SND_REQACK.
 * @param event the event to check.
 */
#define EVT_IS_SND_ACK(event)          (event->type==SND_REQACK)
/**
 * Check if the sipevent is of type SND_REQUEST.
 * @param event the event to check.
 */
#define EVT_IS_SND_REQUEST(event)      (event->type==SND_REQUEST)
/**
 * Check if the sipevent is of type SND_STATUS_1XX.
 * @param event the event to check.
 */
#define EVT_IS_SND_STATUS_1XX(event)   (event->type==SND_STATUS_1XX)
/**
 * Check if the sipevent is of type SND_STATUS_2XX.
 * @param event the event to check.
 */
#define EVT_IS_SND_STATUS_2XX(event)   (event->type==SND_STATUS_2XX)
/**
 * Check if the sipevent is of type SND_STATUS_3456XX.
 * @param event the event to check.
 */
#define EVT_IS_SND_STATUS_3456XX(event)   (event->type==SND_STATUS_3456XX)
/**
 * Check if the sipevent is of an incoming SIP MESSAGE.
 * @param event the event to check.
 */
#define EVT_IS_INCOMINGMSG(event)      (event->type>=RCV_REQINVITE \
                	               &&event->type<=RCV_STATUS_3456XX)
/**
 * Check if the sipevent is of an incoming SIP REQUEST.
 * @param event the event to check.
 */
#define EVT_IS_INCOMINGREQ(event)      (EVT_IS_RCV_INVITE(event) \
                                       ||EVT_IS_RCV_ACK(event) \
                                       ||EVT_IS_RCV_REQUEST(event))
/**
 * Check if the sipevent is of an incoming SIP RESPONSE.
 * @param event the event to check.
 */
#define EVT_IS_INCOMINGRESP(event)     (EVT_IS_RCV_STATUS_1XX(event) \
                                       ||EVT_IS_RCV_STATUS_2XX(event) \
				       ||EVT_IS_RCV_STATUS_3456XX(event))
/**
 * Check if the sipevent is of an outgoing SIP MESSAGE.
 * @param event the event to check.
 */
#define EVT_IS_OUTGOINGMSG(event)      (event->type>=SND_REQINVITE \
                	               &&event->type<=SND_STATUS_3456XX)
/**
 * Check if the sipevent is of an outgoing SIP REQUEST.
 * @param event the event to check.
 */
#define EVT_IS_OUTGOINGREQ(event)      (EVT_IS_SND_INVITE(event) \
                                       ||EVT_IS_SND_ACK(event) \
                                       ||EVT_IS_SND_REQUEST(event))
/**
 * Check if the sipevent is of an outgoing SIP RESPONSE.
 * @param event the event to check.
 */
#define EVT_IS_OUTGOINGRESP(event)     (EVT_IS_SND_STATUS_1XX(event) \
                                       ||EVT_IS_SND_STATUS_2XX(event) \
				       ||EVT_IS_SND_STATUS_3456XX(event))

/**
 * Check if the sipevent is a SIP MESSAGE.
 * @param event the event to check.
 */
#define EVT_IS_MSG(event)              (event->type>=RCV_REQINVITE \
                	               &&event->type<=SND_STATUS_3456XX)
/**
 * Check if the sipevent is of type KILL_TRANSACTION.
 * NOTE: THIS IS AN INTERNAL METHOD ONLY
 * @param event the event to check.
 */
#define EVT_IS_KILL_TRANSACTION(event) (event->type==KILL_TRANSACTION)

#ifdef __cplusplus
}
#endif


/** @} */

#endif