<html>
<head>
    <base href="https://wiki.asterisk.org/wiki">
            <link rel="stylesheet" href="/wiki/s/en/2176/25/9/_/styles/combined.css?spaceKey=AST&amp;forWysiwyg=true" type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://wiki.asterisk.org/wiki/display/AST/res_sip_session+design">res_sip_session design</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://wiki.asterisk.org/wiki/display/~mmichelson">Mark Michelson</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h1. Startup procedure <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >When {{res_sip_session}} starts up, it registers itself with {{res_sip}} as a service. <span class="diff-added-words"style="background-color: #dfd;">This will cause {{res_sip}} to call into {{res_sip_session}} when new SIP messages come in. {{res_sip_session}} will handle those associated with sessions (i.e. INVITEs, in-dialog REFER and INFO, UPDATEs, and PRACKs).</span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h1. Public methods <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>This page is currently under construction. Please refrain from adding comments until this warning is removed</td></tr></table></div>

<h1><a name="res_sip_sessiondesign-Overview"></a>Overview</h1>

<p><tt>res_sip_session</tt> represents the "core" of SIP session operations. In the context of SIP, a "session" refers to a media session, such as a phone call. The SIP channel driver will be a consumer of the services provided by <tt>res_sip_session</tt>.</p>

<h1><a name="res_sip_sessiondesign-Startupprocedure"></a>Startup procedure</h1>

<p>When <tt>res_sip_session</tt> starts up, it registers itself with <tt>res_sip</tt> as a service. This will cause <tt>res_sip</tt> to call into <tt>res_sip_session</tt> when new SIP messages come in. <tt>res_sip_session</tt> will handle those associated with sessions (i.e. INVITEs, in-dialog REFER and INFO, UPDATEs, and PRACKs).</p>

<h1><a name="res_sip_sessiondesign-Publicmethods"></a>Public methods</h1>

<h2><a name="res_sip_sessiondesign-Structures"></a>Structures</h2>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: c; gutter: false">/*!
 * \brief A structure describing a SIP session
 */
struct ast_sip_session {
    /* The endpoint with which Asterisk is communicating */
    struct ast_sip_endpoint *endpoint;
    /* The PJSIP details of the session, which includes the dialog */
    struct pjsip_inv_session *inv_session;
    /* The Asterisk channel associated with the session */
    struct ast_channel *channel;
};

/*!
 * \brief An extension to SIP message processing
 *
 * These can be registered by any module in order to add
 * processing to incoming and outgoing SIP requests and responses
 */
struct ast_sip_session_extension {
    /*! Method on which to call the callbacks. If NULL, call on all methods */
    const char *method;
    /*! Called on incoming SIP request
     * This method can indicate a failure in processing in its return. If there
     * is a failure, it is required that this method sends a response to the request.
     */
    int (*incoming_request)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
    /*! Called on an incoming SIP response */
    void (*incoming_response)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
    /*! Called on an outgoing SIP request */
    void (*outgoing_request)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
    /*! Called on an outgoing SIP response */
    void (*outgoing_response)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
};

/*!
 * \brief A handler for SDP in SIP INVITEs
 *
 * An SDP handler is registered by a module that is interested in being the
 * responsible party for all aspects SDP.
 */
struct ast_sip_session_sdp_handler {
    /*!
     * \brief Set session details based on an incoming SDP
     */
    int (*handle_incoming_sdp)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
    /*!
     * \brief Create an SDP and add it to the outgoing request or response
     */
    void (*add_outgoing_sdp)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
};</pre>
</div></div>
<h2><a name="res_sip_sessiondesign-Extensibility"></a>Extensibility</h2>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: c; gutter: false">/*!
 * \brief Register an SDP handler
 *
 * An SDP handler is responsible for parsing incoming SDPs and ensuring that
 * Asterisk can cope with the contents. Similarly, the SDP handler will be
 * responsible for constructing outgoing SDPs.
 *
 * \param handler The SDP handler to register
 * \retval 0 Success
 * \retval -1 Failure
 */
int ast_sip_session_register_sdp_handler(const struct ast_sip_session_sdp_handler *handler);

/*!
 * \brief Unregister an SDP handler
 *
 * \param handler The SDP handler to unregister
 */
void ast_sip_session_unregister_sdp_handler(const struct ast_sip_session_sdp_handler *handler);

/*!
 * \brief Register an extension to SIP session processing
 *
 * This allows for someone to insert themselves in the processing of SIP
 * requests and responses. This, for example could allow for a module to
 * set channel data based on headers in an incoming message. Similarly,
 * a module could reject an incoming request if desired.
 *
 * \param extension The extension to register
 * \retval 0 Success
 * \retval -1 Failure
 */
int ast_sip_session_register_extension(struct ast_sip_session_extension *extension);

/*!
 * \brief Unregister a an extension to SIP session processing
 *
 * \param extension The extension to unregister
 */
void ast_sip_session_unregister_extension(struct ast_sip_session_extension *extension);</pre>
</div></div>
<h2><a name="res_sip_sessiondesign-CommonSIPmethods"></a>Common SIP methods</h2>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Confluence; brush: c; gutter: false">/*!
 * \brief Retrieve identifying information from an incoming request
 *
 * This will retrieve identifying information and place it in the
 * id parameter. The caller of the function can then apply this to
 * caller ID, connected line, or whatever else may be proper.
 *
 * \param rdata The incoming request or response
 * \param[out] id The collected identity information
 * \retval 0 Successfully found identifying information
 * \retval -1 Identifying information could not be found
 */
int ast_sip_session_get_identity(struct ast_party_id *id);

/*!
 * \brief Send a reinvite on a session
 *
 * This method will inspect the session in order to construct an appropriate
 * reinvite. As with any outgoing request in res_sip_session, this will
 * call into registered extensions in case they wish to add anything.
 * 
 * \param session The session on which the reinvite will be sent
 * \retval 0 Successfully sent reinvite
 * \retval -1 Failure to send reinvite
 */
int ast_sip_session_send_reinvite(struct ast_sip_session *session);

/*!
 * \brief Send a SIP response
 *
 * This will send a SIP response to the request specified in rdata. This will
 * call into any registered extensions' outgoing_response callback.
 *
 * \param session The session to which the current transaction belongs
 * \param response_code The response code to send for this response
 * \param rdata The response to which the response is being sent
 */
int ast_sip_session_send_response(struct ast_sip_session *session, int response_code, struct pjsip_rx_data *rdata);</pre>
</div></div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;" class="grey">
                        <a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
            <span style="padding: 0px 5px;">|</span>
                <a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
        <a href="https://wiki.asterisk.org/wiki/display/AST/res_sip_session+design">View Online</a>
        |
        <a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=22085841&revisedVersion=6&originalVersion=5">View Changes</a>
                |
        <a href="https://wiki.asterisk.org/wiki/display/AST/res_sip_session+design?showComments=true&amp;showCommentArea=true#addcomment">Add Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>