initial commit

pjproject-2.11.1/pjsip/include/pjsip-ua/sip_timer.h

@@ -0,0 +1,275 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2009-2011 Teluu Inc. (http://www.teluu.com)
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
+ */
+#ifndef __PJSIP_TIMER_H__
+#define __PJSIP_TIMER_H__
+
+
+/**
+ * @file sip_timer.h
+ * @brief SIP Session Timers support (RFC 4028 - Session Timer in SIP)
+ */
+
+#include <pjsip-ua/sip_inv.h>
+#include <pjsip/sip_msg.h>
+
+/**
+ * @defgroup PJSIP_TIMER SIP Session Timers support (RFC 4028 - Session Timers in SIP)
+ * @ingroup PJSIP_HIGH_UA
+ * @brief SIP Session Timers support (RFC 4028 - Session Timers in SIP)
+ * @{
+ *
+ * \section PJSIP_TIMER_REFERENCE References
+ *
+ * References:
+ *  - <A HREF="http://www.ietf.org/rfc/rfc4028.txt">RFC 4028: Session Timers 
+ *    in the Session Initiation Protocol (SIP)</A>
+ */
+
+PJ_BEGIN_DECL
+
+/**
+ * Opaque declaration of Session Timers.
+ */
+typedef struct pjsip_timer pjsip_timer;
+
+
+/**
+ * This structure describes Session Timers settings in an invite session.
+ */
+typedef struct pjsip_timer_setting
+{
+    /** 
+     * Specify minimum session expiration period, in seconds. Must not be
+     * lower than 90. Default is 90.
+     */
+    unsigned			 min_se;
+
+    /**
+     * Specify session expiration period, in seconds. Must not be lower than
+     * #min_se. Default is 1800.
+     */
+    unsigned			 sess_expires;	
+
+} pjsip_timer_setting;
+
+
+/**
+ * SIP Session-Expires header (RFC 4028).
+ */
+typedef struct pjsip_sess_expires_hdr
+{
+    /** Standard header field. */
+    PJSIP_DECL_HDR_MEMBER(struct pjsip_sess_expires_hdr);
+
+    /** Session expiration period */
+    unsigned	sess_expires;
+
+    /** Refresher */
+    pj_str_t	refresher;
+
+    /** Other parameters */
+    pjsip_param	other_param;
+
+} pjsip_sess_expires_hdr;
+
+
+/**
+ * SIP Min-SE header (RFC 4028).
+ */
+typedef struct pjsip_min_se_hdr
+{
+    /** Standard header field. */
+    PJSIP_DECL_HDR_MEMBER(struct pjsip_min_se_hdr);
+
+    /** Minimum session expiration period */
+    unsigned	min_se;
+
+    /** Other parameters */
+    pjsip_param	other_param;
+
+} pjsip_min_se_hdr;
+
+
+
+/**
+ * Initialize Session Timers module. This function must be called once during
+ * application initialization, to register this module to SIP endpoint.
+ *
+ * @param endpt		The SIP endpoint instance.
+ *
+ * @return		PJ_SUCCESS if module is successfully initialized.
+ */
+PJ_DECL(pj_status_t) pjsip_timer_init_module(pjsip_endpoint *endpt);
+
+
+/**
+ * Initialize Session Timers setting with default values.
+ *
+ * @param setting	Session Timers setting to be initialized.
+ *
+ * @return		PJ_SUCCESS on successful.
+ */
+PJ_DECL(pj_status_t) pjsip_timer_setting_default(pjsip_timer_setting *setting);
+
+
+/**
+ * Initialize Session Timers for an invite session. This function should be
+ * called by application to apply Session Timers setting, otherwise invite
+ * session will apply default setting to the Session Timers.
+ *
+ * @param inv		The invite session.
+ * @param setting	Session Timers setting, see @pjsip_timer_setting.
+ *			If setting is NULL, default setting will be applied.
+ *
+ * @return		PJ_SUCCESS on successful.
+ */
+PJ_DECL(pj_status_t) pjsip_timer_init_session(
+					pjsip_inv_session *inv,
+					const pjsip_timer_setting *setting);
+
+
+/**
+ * Create Session-Expires header.
+ *
+ * @param pool		Pool to allocate the header instance from.
+ *
+ * @return		An empty Session-Expires header instance.
+ */
+PJ_DECL(pjsip_sess_expires_hdr*) pjsip_sess_expires_hdr_create(
+							pj_pool_t *pool);
+
+
+/**
+ * Create Min-SE header.
+ *
+ * @param pool		Pool to allocate the header instance from.
+ *
+ * @return		An empty Min-SE header instance.
+ */
+PJ_DECL(pjsip_min_se_hdr*) pjsip_min_se_hdr_create(pj_pool_t *pool);
+
+
+/**
+ * Update outgoing request to insert Session Timers headers and also
+ * signal Session Timers capability in Supported and/or Require headers.
+ *
+ * This function will be called internally by the invite session if it 
+ * detects that the session needs Session Timers support.
+ *
+ * @param inv		The invite session.
+ * @param tdata		Outgoing INVITE or UPDATE request.
+ *
+ * @return		PJ_SUCCESS on successful.
+ */
+PJ_DECL(pj_status_t) pjsip_timer_update_req(pjsip_inv_session *inv,
+					    pjsip_tx_data *tdata);
+
+
+/**
+ * Process Session Timers headers in incoming response, this function
+ * will only process incoming response with status code 422 (Session
+ * Interval Too Small) or 2xx (final response).
+ *
+ * This function will be called internally by the invite session if it 
+ * detects that the session needs Session Timers support.
+ *
+ * @param inv		The invite session.
+ * @param rdata		Incoming response data.
+ * @param st_code	Output buffer to store corresponding SIP status code 
+ *			when function returning non-PJ_SUCCESS.
+ *
+ * @return		PJ_SUCCESS on successful.
+ */
+PJ_DECL(pj_status_t) pjsip_timer_process_resp(pjsip_inv_session *inv,
+					      const pjsip_rx_data *rdata,
+					      pjsip_status_code *st_code);
+
+/**
+ * Process Session Timers refresh error, this function will process
+ * error from refresh request. The error will be handle according the
+ * error code, i.e : BYE will be sent after error 503 (Transport Error).
+ *
+ * @param inv		 The invite session.
+ * @param event		 The event that trigger the error.
+ *
+ * @return		 PJ_SUCCESS on successful.
+ */
+PJ_DECL(pj_status_t)  pjsip_timer_handle_refresh_error(
+					    pjsip_inv_session *inv,
+					    pjsip_event *event);
+
+/**
+ * Process Session Timers headers in incoming request, this function
+ * will only process incoming INVITE and UPDATE request.
+ *
+ * This function will be called internally by the invite session if it 
+ * detects that the session needs Session Timers support.
+ *
+ * @param inv		The invite session.
+ * @param rdata		Incoming INVITE or UPDATE request.
+ * @param st_code	Output buffer to store corresponding SIP status code 
+ *			when function returning non-PJ_SUCCESS.
+ *
+ * @return		PJ_SUCCESS on successful.
+ */
+PJ_DECL(pj_status_t) pjsip_timer_process_req(pjsip_inv_session *inv,
+					     const pjsip_rx_data *rdata,
+					     pjsip_status_code *st_code);
+
+
+/**
+ * Update outgoing response to insert Session Timers headers and also
+ * signal Session Timers capability in Supported and/or Require headers.
+ * This function will only update outgoing response with status code 
+ * 422 (Session Interval Too Small) or 2xx (final response).
+ *
+ * This function will be called internally by the invite session if it 
+ * detects that the session needs Session Timers support.
+ *
+ * @param inv		The invite session.
+ * @param tdata		Outgoing 422/2xx response.
+ *
+ * @return		PJ_SUCCESS on successful.
+ */
+PJ_DECL(pj_status_t) pjsip_timer_update_resp(pjsip_inv_session *inv,
+					     pjsip_tx_data *tdata);
+
+/**
+ * End Session Timers in an invite session.
+ *
+ * This function will be called internally by the invite session if it 
+ * detects that the session needs Session Timers support.
+ *
+ * @param inv		The invite session.
+ *
+ * @return		PJ_SUCCESS on successful.
+ */
+PJ_DECL(pj_status_t) pjsip_timer_end_session(pjsip_inv_session *inv);
+
+
+
+PJ_END_DECL
+
+
+/**
+ * @}
+ */
+
+
+#endif	/* __PJSIP_TIMER_H__ */