voice-gateway-service/pjproject/pjsip/include/pjsip-simple/dlg_event.h

/*
 * Copyright (C) 2024 Teluu Inc. (http://www.teluu.com)
 * Copyright (C) 2013 Maxim Kondratenko <max.kondr@gmail.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_SIMPLE_DLG_EVENT_H__
#define __PJSIP_SIMPLE_DLG_EVENT_H__

/**
 * @file dlg_event.h
 * @brief SIP Extension for INVITE-Initiated Dialog Event (RFC 4235)
 */
#include <pjsip-simple/evsub.h>
#include <pjsip-simple/dialog_info.h>

PJ_BEGIN_DECL


/**
 * @defgroup PJSIP_SIMPLE_DLG_EVENT SIP Extension for Dialog Event (RFC 4235)
 * @ingroup PJSIP_SIMPLE
 * @brief Support for SIP Extension for Dialog Event (RFC 4235)
 * @{
 *
 * This module contains the implementation of INVITE-Initiated Dialog Event
 * Package as described in RFC 4235. It uses the SIP Event Notification
 * framework (evsub.h) and extends the framework by implementing
 * "dialog-info+xml" event package. This could be useful for features such as
 * Busy Lamp Field (BLF).
 */


/**
 * Initialize the dialog event module and register it as endpoint module and
 * package to the event subscription module.
 *
 * @param endpt     The endpoint instance.
 * @param mod_evsub The event subscription module instance.
 *
 * @return          PJ_SUCCESS if the module is successfully
 *                  initialized and registered to both endpoint
 *                  and the event subscription module.
 */
PJ_DECL(pj_status_t) pjsip_dlg_event_init_module(pjsip_endpoint *endpt,
                                                 pjsip_module *mod_evsub);


/**
 * Get the dialog event module instance.
 *
 * @return          The dialog event module instance.
 */
PJ_DECL(pjsip_module*) pjsip_bdlg_event_instance(void);


/**
 * Maximum dialog event status info items which can handled by application.
 *
 */
#define PJSIP_DLG_EVENT_STATUS_MAX_INFO  8


/**
 * This structure describes dialog event status of an entity.
 */
struct pjsip_dlg_event_status
{
    unsigned        info_cnt;             /**< Number of info in the status */
    struct {

        pj_str_t    dialog_info_state;    /**< Dialog-Info state            */
        pj_str_t    dialog_info_entity;   /**< Dialog-Info entity           */
        pj_str_t    dialog_call_id;       /**< Dialog's call_id             */
        pj_str_t    dialog_remote_tag;    /**< Dialog's remote-tag          */
        pj_str_t    dialog_local_tag;     /**< Dialog's local-tag           */
        pj_str_t    dialog_direction;     /**< Dialog's direction           */
        pj_str_t    dialog_id;            /**< Dialog's id                  */
        pj_str_t    dialog_state;         /**< Dialog state                 */
        pj_str_t    dialog_duration;      /**< Dialog duration              */

        pj_xml_node *dialog_node;         /**< Pointer to tuple XML node of
                                               parsed dialog-info body received
                                               from remote agent. Only valid
                                               for client subscription. If the
                                               last received NOTIFY request
                                               does not contain any dialog-info
                                               body, this will be set to NULL*/
        pj_str_t    local_identity;
        pj_str_t    local_identity_display;
        pj_str_t    local_target_uri;

        pj_str_t    remote_identity;
        pj_str_t    remote_identity_display;
        pj_str_t    remote_target_uri;

    } info[PJSIP_DLG_EVENT_STATUS_MAX_INFO]; /**< Array of info.            */
};


/**
 * @see pjsip_dlg_event_status
 */
typedef struct pjsip_dlg_event_status pjsip_dlg_event_status;


/**
 * Create dialog event client subscription session.
 *
 * @param dlg       The underlying dialog to use.
 * @param user_cb   Pointer to callbacks to receive dialog events.
 * @param options   Option flags. Currently only PJSIP_EVSUB_NO_EVENT_ID
 *                  is recognized.
 * @param p_evsub   Pointer to receive the dialog event subscription
 *                  session.
 *
 * @return          PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t)
pjsip_dlg_event_create_uac(pjsip_dialog *dlg,
                           const pjsip_evsub_user *user_cb,
                           unsigned options,
                           pjsip_evsub **p_evsub );


/**
 * Forcefully destroy the dialog event subscription. This function should only
 * be called on special condition, such as when the subscription
 * initialization has failed. For other conditions, application MUST terminate
 * the subscription by sending the appropriate un(SUBSCRIBE) or NOTIFY.
 *
 * @param sub       The dialog event subscription.
 * @param notify    Specify whether the state notification callback
 *                  should be called.
 *
 * @return          PJ_SUCCESS if subscription session has been destroyed.
 */
PJ_DECL(pj_status_t) pjsip_dlg_event_terminate(pjsip_evsub *sub,
                                               pj_bool_t notify );



/**
 * Call this function to create request to initiate dialog event subscription,
 * to refresh subcription, or to request subscription termination.
 *
 * @param sub       Client subscription instance.
 * @param expires   Subscription expiration. If the value is set to zero,
 *                  this will request unsubscription.
 * @param p_tdata   Pointer to receive the request.
 *
 * @return          PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjsip_dlg_event_initiate(pjsip_evsub *sub,
                                              pj_int32_t expires,
                                              pjsip_tx_data **p_tdata);


/**
 * Add a list of headers to the subscription instance. The list of headers
 * will be added to outgoing dialog event subscription requests.
 *
 * @param sub       Subscription instance.
 * @param hdr_list  List of headers to be added.
 *
 * @return          PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjsip_dlg_event_add_header(pjsip_evsub *sub,
                                                const pjsip_hdr *hdr_list);


/**
 * Accept the incoming subscription request by sending 2xx response to
 * incoming SUBSCRIBE request.
 *
 * @param sub       Server subscription instance.
 * @param rdata     The incoming subscription request message.
 * @param st_code   Status code, which MUST be final response.
 * @param hdr_list  Optional list of headers to be added in the response.
 *
 * @return          PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjsip_dlg_event_accept(pjsip_evsub *sub,
                                            pjsip_rx_data *rdata,
                                            int st_code,
                                            const pjsip_hdr *hdr_list );

/**
 * Send request message. Application may also send request created with other
 * functions, e.g. authentication. But the request MUST be either request
 * that creates/refresh subscription or NOTIFY request.
 *
 * @param sub       The subscription object.
 * @param tdata     Request message to be sent.
 *
 * @return          PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pjsip_dlg_event_send_request(pjsip_evsub *sub,
                                                  pjsip_tx_data *tdata);


/**
 * Get the dialog event status. Client normally would call this function
 * after receiving NOTIFY request from server.
 *
 * @param sub       The client or server subscription.
 * @param status    The structure to receive dialog event status.
 *
 * @return          PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t)
pjsip_dlg_event_get_status(pjsip_evsub *sub, pjsip_dlg_event_status *status);


/**
 * This is a utility function to parse XML body into PJSIP dialog event status.
 *
 * @param rdata     The incoming SIP message containing the XML body.
 * @param pool      Pool to allocate memory to copy the strings into
 *                  the dialog event status structure.
 * @param status    The dialog event status to be initialized.
 *
 * @return          PJ_SUCCESS on success.
 *
 * @see pjsip_dlg_event_parse_dialog_info()
 */
PJ_DECL(pj_status_t)
pjsip_dlg_event_parse_dialog_info(pjsip_rx_data *rdata,
                                  pj_pool_t *pool,
                                  pjsip_dlg_event_status *dlg_status);


/**
 * This is a utility function to parse XML body into PJSIP dialog event status.
 *
 * @param body          Text body, with one extra space at the end to place
 *                      NULL character temporarily during parsing.
 * @param body_len      Length of the body, not including the NULL termination
 *                      character.
 * @param pool          Pool to allocate memory to copy the strings into
 *                      the dialog event status structure.
 * @param status        The dialog event status to be initialized.
 *
 * @return              PJ_SUCCESS on success.
 *
 * @see pjsip_dlg_event_parse_dialog_info2()
 */
PJ_DECL(pj_status_t)
pjsip_dlg_event_parse_dialog_info2(char *body, unsigned body_len,
                                   pj_pool_t *pool,
                                   pjsip_dlg_event_status *dlg_status);


/**
 * @}
 */

PJ_END_DECL


#endif  /* __PJSIP_SIMPLE_DLG_EVENT_H__ */