<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2176/25/9/_/styles/combined.css?spaceKey=AST&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 (35)</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" > <br>h2. Extensibility <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{newcode:language=c} <br>/*! <br> * \brief Register an SDP handler <br> * <br> * An SDP handler is responsible for parsing incoming SDPs and ensuring that <br> * Asterisk can cope with the contents. Similarly, the SDP handler will be <br> * responsible for constructing outgoing SDPs. <br> * <br> * \param handler The SDP handler to register <br> * \retval 0 Success <br> * \retval -1 Failure <br> */ <br>int ast_sip_session_register_sdp_handler(const struct ast_sip_session_sdp_handler *handler); <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{{res_sip_session}} will strive to be as extensible as possible. Since people constantly wish to make tweaks to how SIP behaves, the best way to do this is to provide an API so that a module can insert itself into the processing of requests/responses. The following methods provide such capabilities. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">/*! <br> * \brief Unregister an SDP handler <br> * <br> * \param handler The SDP handler to unregister <br> */ <br>void ast_sip_session_unregister_sdp_handler(const struct ast_sip_session_sdp_handler *handler); <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. {{int ast_sip_session_register_sdp_handler(const struct ast_sip_session_sdp_handler)}} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">struct ast_sip_session_extension { <br> /*! Method on which to call the callbacks. If NULL, call on all methods */ <br> const char *method; <br> /*! Called on incoming SIP request */ <br> int (*incoming_request)(struct ast_sip_session *session, struct pjsip_rx_data *rdata); <br> /*! Called on an incoming SIP response */ <br> void (*incoming_response)(struct ast_sip_session *session, struct pjsip_rx_data *rdata); <br> /*! Called on an outgoing SIP request */ <br> void (*outgoing_request)(struct ast_sip_session *session, struct pjsip_tx_data *tdata); <br> /*! Called on an outgoing SIP response */ <br> void (*outgoing_response)(struct ast_sip_session *session, struct pjsip_tx_data *tdata); <br>}; <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">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. <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">/*!</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. {{int ast_sip_session_register_extension_incoming(const char *method, int (*handler)(struct ast_sip_session *session, struct pjsip_rx_data *rdata)}} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * \brief Register an extension to SIP session processing <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">*</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">This allows for a module to insert itself into the processing of an incoming request or response. The {{method}} parameter can be used in order to restrict the callback from being called only for requests or responses of a particular SIP method. Possible uses for this would be to set values on a channel based on headers present in a SIP request or response. Other uses could be to reject an incoming request due to some criteria. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * This allows for someone to insert themselves in the processing of SIP <br> * requests and responses. This, for example could allow for a module to <br> * set channel data based on headers in an incoming message. Similarly, <br> * a module could reject an incoming request if desired. <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">*</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. {{int ast_sip_session_register_extension_outgoing(const char *method, int (*handler)(struct ast_sip_session *session, struct pjsip_tx_data *tdata)}} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * \param extension The extension to register <br> * \retval 0 Success <br> * \retval -1 Failure <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">*/</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">This allows for a module to insert itself into the processing of an outgoing request or response. The {{method}} parameter can be used in order to restrict the callback from being called only for requests or responses of a particular SIP method. Possible uses for this would be to add headers to an outgoing SIP request or response based on local policy. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">int ast_sip_session_register_extension(struct ast_sip_session_extension *extension); <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">{newcode}</span> <br></td></tr>
<tr><td class="diff-unchanged" >h2. Common SIP methods <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{newcode:language=c} <br>/*! <br> * \brief Retrieve identifying information from an incoming request <br> * <br> * This will retrieve identifying information and place it in the <br> * id parameter. The caller of the function can then apply this to <br> * caller ID, connected line, or whatever else may be proper. <br> * <br> * \param rdata The incoming request or response <br> * \param[out] id The collected identity information <br> * \retval 0 Successfully found identifying information <br> * \retval -1 Identifying information could not be found <br> */ <br>int ast_sip_session_get_identity(struct ast_party_id *id); <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. {{int ast_sip_session_get_identity(struct ast_party_id *id)}} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">/*! <br> * \brief Send a reinvite on a session <br> * <br> * This method will inspect the session in order to construct an appropriate <br> * reinvite. As with any outgoing request in res_sip_session, this will <br> * call into registered extensions in case they wish to add anything. <br> * <br> * \param session The session on which the reinvite will be sent <br> * \retval 0 Successfully sent reinvite <br> * \retval -1 Failure to send reinvite <br> */ <br>int ast_sip_session_send_reinvite(struct ast_sip_session *session); <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">This will retrieve identity information from a SIP message and place the information in the {{id}} parameter. The caller of the function can then apply this identity to caller ID, connected line, or whatever is relevant. <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">/*!</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. {{int ast_sip_session_send_reinvite(struct ast_sip_session *session)}} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * \brief Send a SIP response <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">*</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Send a reinvite on a SIP session. The method will inspect session details and construct the reinvite accordingly. This will call into registered outgoing extensions in case they wish to add anything to the outgoing reinvite. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * This will send a SIP response to the request specified in rdata. This will <br> * call into any registered extensions' outgoing_response callback. <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">*</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3. {{int ast_sip_session_send_response(struct ast_sip_session *session, int response_code, struct pjsip_rx_data *rdata)}} <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> * \param session The session to which the current transaction belongs <br> * \param response_code The response code to send for this response <br> * \param rdata The response to which the response is being sent <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;"> </span> <span class="diff-added-words"style="background-color: #dfd;">*/</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Send a response to a request on a SIP session. This will inspect session details and construct the response accordingly with the indicated {{response_code}}. This iwll call into registered outgoing extensions in case they wish to add anything to the response. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">int ast_sip_session_send_response(struct ast_sip_session *session, int response_code, struct pjsip_rx_data *rdata); <br>{newcode} <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.</p>
<h1><a name="res_sip_sessiondesign-Publicmethods"></a>Public methods</h1>
<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);
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 */
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 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);</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=4&originalVersion=3">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/res_sip_session+design?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>