[asterisk-commits] mmichelson: branch mmichelson/caller_id r384822 - /team/mmichelson/caller_id/...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Fri Apr 5 14:38:46 CDT 2013
Author: mmichelson
Date: Fri Apr 5 14:38:43 2013
New Revision: 384822
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=384822
Log:
Add doxygen.
Modified:
team/mmichelson/caller_id/res/res_sip_caller_id.c
Modified: team/mmichelson/caller_id/res/res_sip_caller_id.c
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/caller_id/res/res_sip_caller_id.c?view=diff&rev=384822&r1=384821&r2=384822
==============================================================================
--- team/mmichelson/caller_id/res/res_sip_caller_id.c (original)
+++ team/mmichelson/caller_id/res/res_sip_caller_id.c Fri Apr 5 14:38:43 2013
@@ -32,6 +32,12 @@
#include "asterisk/module.h"
#include "asterisk/callerid.h"
+/*!
+ * \internal
+ * \brief Set an ast_party_id name and number based on an identity header.
+ * \param hdr From, P-Asserted-Identity, or Remote-Party-ID header on incoming message
+ * \param[out] id The ID to set data on
+ */
static void set_id_from_hdr(pjsip_fromto_hdr *hdr, struct ast_party_id *id)
{
char cid_name[AST_CHANNEL_NAME];
@@ -53,6 +59,19 @@
}
}
+/*!
+ * \internal
+ * \brief Get a P-Asserted-Identity or Remote-Party-ID header from an incoming message
+ *
+ * This function will parse the header as if it were a From header. This allows for us
+ * to easily manipulate the URI, as well as add, modify, or remove parameters from the
+ * header
+ *
+ * \param rdata The incoming message
+ * \param header_name The name of the ID header to find
+ * \retval NULL No ID header present or unable to parse ID header
+ * \retval non-NULL The parsed ID header
+ */
static pjsip_fromto_hdr *get_id_header(pjsip_rx_data *rdata, const pj_str_t *header_name)
{
static const pj_str_t from = { "From", 4 };
@@ -78,7 +97,19 @@
return parsed_hdr;
}
-static int get_id_from_pai(pjsip_rx_data *rdata, struct ast_party_id *id)
+/*!
+ * \internal
+ * \brief Set an ast_party_id structure based on data in a P-Asserted-Identity header
+ *
+ * This makes use of \ref set_id_from_hdr for setting name and number. It uses
+ * the contents of a Privacy header in order to set presentation information.
+ *
+ * \param rdata The incoming message
+ * \param[out] id The ID to set
+ * \retval 0 Successfully set the party ID
+ * \retval non-zero Could not set the party ID
+ */
+static int set_id_from_pai(pjsip_rx_data *rdata, struct ast_party_id *id)
{
static const pj_str_t pai_str = { "P-Asserted-Identity", 19 };
static const pj_str_t privacy_str = { "Privacy", 7 };
@@ -106,7 +137,19 @@
return 0;
}
-static int get_id_from_rpid(pjsip_rx_data *rdata, struct ast_party_id *id)
+/*!
+ * \internal
+ * \brief Set an ast_party_id structure based on data in a Remote-Party-ID header
+ *
+ * This makes use of \ref set_id_from_hdr for setting name and number. It uses
+ * the privacy and screen parameters in order to set presentation information.
+ *
+ * \param rdata The incoming message
+ * \param[out] id The ID to set
+ * \retval 0 Succesfully set the party ID
+ * \retval non-zero Could not set the party ID
+ */
+static int set_id_from_rpid(pjsip_rx_data *rdata, struct ast_party_id *id)
{
static const pj_str_t rpid_str = { "Remote-Party-ID", 15 };
static const pj_str_t privacy_str = { "privacy", 7 };
@@ -138,7 +181,20 @@
return 0;
}
-static int get_id_from_from(struct pjsip_rx_data *rdata, struct ast_party_id *id)
+/*!
+ * \internal
+ * \brief Set an ast_party_id structure based on data in a From
+ *
+ * This makes use of \ref set_id_from_hdr for setting name and number. It uses
+ * no information from the message in order to set privacy. It relies on endpoint
+ * configuration for privacy information.
+ *
+ * \param rdata The incoming message
+ * \param[out] id The ID to set
+ * \retval 0 Succesfully set the party ID
+ * \retval non-zero Could not set the party ID
+ */
+static int set_id_from_from(struct pjsip_rx_data *rdata, struct ast_party_id *id)
{
pjsip_fromto_hdr *from = pjsip_msg_find_hdr(rdata->msg_info.msg,
PJSIP_H_FROM, rdata->msg_info.msg->hdr.next);
@@ -157,6 +213,19 @@
return 0;
}
+/*!
+ * \internal
+ * \brief Determine if a connected line update should be queued
+ *
+ * This uses information about the session and the ID that would be queued
+ * in the connected line update in order to determine if we should queue
+ * a connected line update.
+ *
+ * \param session The session whose channel we wish to queue the connected line update on
+ * \param id The identification information that would be queued on the connected line update
+ * \retval 0 We should not queue a connected line update
+ * \retval non-zero We should queue a connected line update
+ */
static int should_queue_connected_line_update(const struct ast_sip_session *session, const struct ast_party_id *id)
{
/* Invalid number means no update */
@@ -197,6 +266,12 @@
return 0;
}
+/*!
+ * \internal
+ * \brief Queue a connected line update on a session's channel.
+ * \param session The session whose channel should have the connected line update queued upon.
+ * \param id The identification information to place in the connected line update
+ */
static void queue_connected_line_update(struct ast_sip_session *session, const struct ast_party_id *id)
{
struct ast_party_connected_line connected;
@@ -216,6 +291,17 @@
ast_party_connected_line_free(&connected);
}
+/*!
+ * \internal
+ * \brief Make updates to connected line information based on an incoming request.
+ *
+ * This will get identity information from an incoming request. Once the identification is
+ * retrieved, we will check if the new information warrants a connected line update and queue
+ * a connected line update if so.
+ *
+ * \param session The session on which we received an incoming request
+ * \param rdata The incoming request
+ */
static void update_incoming_connected_line(struct ast_sip_session *session, pjsip_rx_data *rdata)
{
struct ast_party_id id;
@@ -224,7 +310,7 @@
}
ast_party_id_init(&id);
- if (get_id_from_pai(rdata, &id) && get_id_from_rpid(rdata, &id)) {
+ if (set_id_from_pai(rdata, &id) && set_id_from_rpid(rdata, &id)) {
return;
}
if (should_queue_connected_line_update(session, &id)) {
@@ -234,19 +320,31 @@
ast_party_id_free(&id);
}
+/*!
+ * \internal
+ * \brief Session supplement callback on an incoming INVITE request
+ *
+ * If we are receiving an initial INVITE, then we will set the session's identity
+ * based on the INVITE or configured endpoint values. If we are receiving a reinvite,
+ * then we will potentially queue a connected line update via the \ref update_incoming_connected_line
+ * function
+ *
+ * \param session The session that has received an INVITE
+ * \param rdata The incoming INVITE
+ */
static int caller_id_incoming_request(struct ast_sip_session *session, pjsip_rx_data *rdata)
{
if (session->inv_session->state < PJSIP_INV_STATE_CONFIRMED) {
/* Initial inbound INVITE. Set the session ID directly */
if (session->endpoint->trust_id_inbound &&
- (!get_id_from_pai(rdata, &session->id) || !get_id_from_rpid(rdata, &session->id))) {
+ (!set_id_from_pai(rdata, &session->id) || !set_id_from_rpid(rdata, &session->id))) {
return 0;
}
if (session->endpoint->id.number.valid) {
/* Prefer configured caller-ID over From header. */
ast_party_id_copy(&session->id, &session->endpoint->id);
} else {
- get_id_from_from(rdata, &session->id);
+ set_id_from_from(rdata, &session->id);
}
} else {
/* Reinvite. Check for changes to the ID and queue a connected line
@@ -257,6 +355,15 @@
return 0;
}
+/*!
+ * \internal
+ * \brief Session supplement callback on INVITE response
+ *
+ * INVITE responses could result in queuing connected line updates.
+ *
+ * \param session The session on which communication is happening
+ * \param rdata The incoming INVITE response
+ */
static void caller_id_incoming_response(struct ast_sip_session *session, pjsip_rx_data *rdata)
{
if (!session->channel) {
@@ -266,6 +373,13 @@
update_incoming_connected_line(session, rdata);
}
+/*!
+ * \internal
+ * \brief Set name and number information on an identity header.
+ * \param pool Memory pool to use for string duplication
+ * \param id_hdr A From, P-Asserted-Identity, or Remote-Party-ID header to modify
+ * \param id The identity information to apply to the header
+ */
static void modify_id_header(pj_pool_t *pool, pjsip_fromto_hdr *id_hdr, const struct ast_party_id *id)
{
pjsip_name_addr *id_name_addr;
@@ -281,6 +395,14 @@
pj_strdup2(pool, &id_uri->user, id->number.str);
}
+/*!
+ * \internal
+ * \brief Create an identity header for an outgoing message
+ * \param hdr_name The name of the header to create
+ * \param tdata The message to place the header on
+ * \param id The identification information for the new header
+ * \return newly-created header
+ */
static pjsip_fromto_hdr *create_new_id_hdr(const pj_str_t *hdr_name, pjsip_tx_data *tdata, const struct ast_party_id *id)
{
pjsip_fromto_hdr *id_hdr;
@@ -308,6 +430,18 @@
return id_hdr;
}
+/*!
+ * \internal
+ * \brief Add a Privacy header to an outbound message
+ *
+ * When sending a P-Asserted-Identity header, if privacy is requested, then we
+ * will need to indicate such by adding a Privacy header. Similarly, if no
+ * privacy is requested, and a Privacy header already exists on the message,
+ * then the old Privacy header should be removed.
+ *
+ * \param tdata The outbound message to add the Privacy header to
+ * \param id The id information used to determine privacy
+ */
static void add_privacy_header(pjsip_tx_data *tdata, const struct ast_party_id *id)
{
static const pj_str_t pj_privacy_name = { "Privacy", 7 };
@@ -330,6 +464,12 @@
}
}
+/*!
+ * \internal
+ * \brief Add a P-Asserted-Identity header to an outbound message
+ * \param tdata The message to add the header to
+ * \param id The identification information used to populate the header
+ */
static void add_pai_header(pjsip_tx_data *tdata, const struct ast_party_id *id)
{
static const pj_str_t pj_pai_name = { "P-Asserted-Identity", 19 };
@@ -359,6 +499,18 @@
pjsip_msg_add_hdr(tdata->msg, (pjsip_hdr *)pai_hdr);
}
+/*!
+ * \internal
+ * \brief Add privacy and screen parameters to a Remote-Party-ID header.
+ *
+ * If privacy is requested, then the privacy and screen parameters need to
+ * reflect this. Similarly, if no privacy or screening is to be communicated,
+ * we need to make sure that any previously set values are updated.
+ *
+ * \param tdata The message where the Remote-Party-ID header is
+ * \param hdr The header on which the parameters are being added
+ * \param id The identification information used to determine privacy
+ */
static void add_privacy_params(pjsip_tx_data *tdata, pjsip_fromto_hdr *hdr, const struct ast_party_id *id)
{
static const pj_str_t privacy_str = { "privacy", 7 };
@@ -406,6 +558,12 @@
}
}
+/*!
+ * \internal
+ * \brief Add a Remote-Party-ID header to an outbound message
+ * \param tdata The message to add the header to
+ * \param id The identification information used to populate the header
+ */
static void add_rpid_header(pjsip_tx_data *tdata, const struct ast_party_id *id)
{
static const pj_str_t pj_rpid_name = { "Remote-Party-ID", 15 };
@@ -434,6 +592,17 @@
pjsip_msg_add_hdr(tdata->msg, (pjsip_hdr *)rpid_hdr);
}
+/*!
+ * \internal
+ * \brief Add any appropriate identification headers to an outbound SIP message
+ *
+ * This will determine if an outbound message should have identification headers and
+ * will add the appropriately configured headers
+ *
+ * \param session The session on which we will be sending the message
+ * \param tdata The outbound message
+ * \param The identity information to place on the message
+ */
static void add_id_headers(const struct ast_sip_session *session, pjsip_tx_data *tdata, const struct ast_party_id *id)
{
if (((id->name.presentation & AST_PRES_RESTRICTION) == AST_PRES_RESTRICTED ||
@@ -449,6 +618,18 @@
}
}
+/*!
+ * \internal
+ * \brief Session supplement callback for outgoing INVITE requests
+ *
+ * For an initial INVITE request, we may change the From header to appropriately
+ * reflect the identity information. On all INVITEs (initial and reinvite) we may
+ * add other identity headers such as P-Asserted-Identity and Remote-Party-ID based
+ * on configuration and privacy settings
+ *
+ * \param session The session on which the INVITE will be sent
+ * \param tdata The outbound INVITE request
+ */
static void caller_id_outgoing_request(struct ast_sip_session *session, pjsip_tx_data *tdata)
{
struct ast_party_id connected_id;
@@ -476,6 +657,15 @@
add_id_headers(session, tdata, &connected_id);
}
+/*!
+ * \internal
+ * \brief Session supplement for outgoing INVITE response
+ *
+ * This will add P-Asserted-Identity and Remote-Party-ID headers if necessary
+ *
+ * \param session The session on which the INVITE response is to be sent
+ * \param tdata The outbound INVITE response
+ */
static void caller_id_outgoing_response(struct ast_sip_session *session, pjsip_tx_data *tdata)
{
if (!session->channel) {
More information about the asterisk-commits
mailing list