voice-gateway/pjsip/include/pjsip-ua/sip_timer.h

/* 
 * 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__ */