Add private representation of caller, connected and redirecting party ids.

This patch adds the feature "Private representation of caller, connected
and redirecting party ids", as previously discussed with us (DATUS) and
Digium.

1. Feature motivation

Until now it is quite difficult to modify a party number or name which can
only be seen by exactly one particular instantiated technology channel
subscriber.  One example where a modified party number or name on one
channel is spread over several channels are supplementary services like
call transfer or pickup.  To implement these features Asterisk internally
copies caller and connected ids from one channel to another.  Another
example are extension subscriptions.  The monitoring entities (watchers)
are notified of state changes and - if desired - of party numbers or names
which represent the involving call parties.  One major feature where a
private representation of party names is essentially needed, i.e.  where a
party name shall be exclusively signaled to only one particular user, is a
private user-specific name resolution for party numbers.  A lookup in a
private destination-dependent telephone book shall provide party names
which cannot be seen by any other user at any time.

2. Feature Description

This feature comes along with the implementation of additional private
party id elements for caller id, connected id and redirecting ids inside
Asterisk channels.

The private party id elements can be read or set by the user using
Asterisk dialplan functions.

When a technology channel is initiating a call, receives an internal
connected-line update event, or receives an internal redirecting update
event, it merges the corresponding public id with the private id to create
an effective party id.  The effective party id is then used for protocol
signaling.

The channel technologies which initially support the private id
representation with this patch are SIP (chan_sip), mISDN (chan_misdn) and
PRI (chan_dahdi).

Once a private name or number on a channel is set and (implicitly) made
valid, it is generally used for any further protocol signaling until it is
rewritten or invalidated.

To simplify the invalidation of private ids all internally generated
connected/redirecting update events and also all connected/redirecting
update events which are generated by technology channels -- receiving
regarding protocol information - automatically trigger the invalidation of
private ids.

If not using the private party id representation feature at all, i.e.  if
using only the 'regular' caller-id, connected and redirecting related
functions, the current characteristic of Asterisk is not affected by the
new extended functionality.

3. User interface Description

To grant access to the private name and number representation from the
Asterisk dialplan, the CALLERID, CONNECTEDLINE and REDIRECTING dialplan
functions are extended by the following data types.  The formats of these
data types are equal to the corresponding regular 'non-private' already
existing data types:

CALLERID:
priv-all
priv-name priv-name-valid priv-name-charset priv-name-pres
priv-num priv-num-valid priv-num-plan priv-num-pres
priv-subaddr priv-subaddr-valid priv-subaddr-type priv-subaddr-odd
priv-tag

CONNECTEDLINE:
priv-name priv-name-valid priv-name-pres priv-name-charset
priv-num priv-num-valid priv-num-pres priv-num-plan
priv-subaddr priv-subaddr-valid priv-subaddr-type priv-subaddr-odd
priv-tag

REDIRECTING:
priv-orig-name priv-orig-name-valid priv-orig-name-pres priv-orig-name-charset
priv-orig-num priv-orig-num-valid priv-orig-num-pres priv-orig-num-plan
priv-orig-subaddr priv-orig-subaddr-valid priv-orig-subaddr-type priv-orig-subaddr-odd
priv-orig-tag

priv-from-name priv-from-name-valid priv-from-name-pres priv-from-name-charset
priv-from-num priv-from-num-valid priv-from-num-pres priv-from-num-plan
priv-from-subaddr priv-from-subaddr-valid priv-from-subaddr-type priv-from-subaddr-odd
priv-from-tag

priv-to-name priv-to-name-valid priv-to-name-pres priv-to-name-charset
priv-to-num priv-to-num-valid priv-to-num-pres priv-to-num-plan
priv-to-subaddr priv-to-subaddr-valid priv-to-subaddr-type priv-to-subaddr-odd
priv-to-tag

Reported by: Thomas Arimont

Review: https://reviewboard.asterisk.org/r/2030/


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@371120 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 99 insertions, 0 deletions

diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index c9d13187c..abfe18139 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -380,6 +380,9 @@ struct ast_party_caller {
 	 */
 	struct ast_party_id ani;
 
+	/*! \brief Private caller party ID */
+	struct ast_party_id priv;
+
 	/*! \brief Automatic Number Identification 2 (Info Digits) */
 	int ani2;
 };
@@ -393,6 +396,8 @@ struct ast_set_party_caller {
 	struct ast_set_party_id id;
 	/*! What ANI id information to set. */
 	struct ast_set_party_id ani;
+	/*! What private caller id information to set. */
+	struct ast_set_party_id priv;
 };
 
 /*!
@@ -413,6 +418,9 @@ struct ast_party_connected_line {
 	 */
 	struct ast_party_id ani;
 
+	/*! \brief Private connected party ID */
+	struct ast_party_id priv;
+
 	/*!
 	 * \brief Automatic Number Identification 2 (Info Digits)
 	 * \note Not really part of connected line data but needed to
@@ -437,6 +445,8 @@ struct ast_set_party_connected_line {
 	struct ast_set_party_id id;
 	/*! What ANI id information to set. */
 	struct ast_set_party_id ani;
+	/*! What private connected line id information to set. */
+	struct ast_set_party_id priv;
 };
 
 /*!
@@ -458,6 +468,15 @@ struct ast_party_redirecting {
 	/*! \brief Call is redirecting to a new party (Sent to the caller) */
 	struct ast_party_id to;
 
+	/*! \brief Who originally redirected the call (Sent to the party the call is redirected toward) - private representation */
+	struct ast_party_id priv_orig;
+
+	/*! \brief Who is redirecting the call (Sent to the party the call is redirected toward) - private representation */
+	struct ast_party_id priv_from;
+
+	/*! \brief Call is redirecting to a new party (Sent to the caller)  - private representation */
+	struct ast_party_id priv_to;
+
 	/*! \brief Number of times the call was redirected */
 	int count;
 
@@ -479,6 +498,12 @@ struct ast_set_party_redirecting {
 	struct ast_set_party_id from;
 	/*! What redirecting-to id information to set. */
 	struct ast_set_party_id to;
+	/*! What private redirecting-orig id information to set. */
+	struct ast_set_party_id priv_orig;
+	/*! What private redirecting-from id information to set. */
+	struct ast_set_party_id priv_from;
+	/*! What private redirecting-to id information to set. */
+	struct ast_set_party_id priv_to;
 };
 
 /*!
@@ -2864,6 +2889,16 @@ void ast_party_subaddress_set(struct ast_party_subaddress *dest, const struct as
 void ast_party_subaddress_free(struct ast_party_subaddress *doomed);
 
 /*!
+ * \brief Set the update marker to update all information of a corresponding party id.
+ * \since 11.0
+ *
+ * \param update_id The update marker for a corresponding party id.
+ *
+ * \return Nothing
+ */
+void ast_set_party_id_all(struct ast_set_party_id *update_id);
+
+/*!
  * \brief Initialize the given party id structure.
  * \since 1.8
  *
@@ -2936,6 +2971,66 @@ void ast_party_id_free(struct ast_party_id *doomed);
 int ast_party_id_presentation(const struct ast_party_id *id);
 
 /*!
+ * \brief Invalidate all components of the given party id.
+ * \since 11.0
+ *
+ * \param id The party id to invalidate.
+ *
+ * \return Nothing
+ */
+void ast_party_id_invalidate(struct ast_party_id *id);
+
+/*!
+ * \brief Destroy and initialize the given party id structure.
+ * \since 11.0
+ *
+ * \param id The party id to reset.
+ *
+ * \return Nothing
+ */
+void ast_party_id_reset(struct ast_party_id *id);
+
+/*!
+ * \brief Merge a given party id into another given party id.
+ * \since 11.0
+ *
+ * \details
+ * This function will generate an effective party id.
+ * 
+ * Each party id component of the party id 'base' is overwritten
+ * by components of the party id 'overlay' if the overlay
+ * component is marked as valid.  However the component 'tag' of
+ * the base party id remains untouched.
+ *
+ * \param base The party id which is merged.
+ * \param overlay The party id which is used to merge into.
+ *
+ * \return The merged party id as a struct, not as a pointer.
+ * \note The merged party id returned is a shallow copy and must not be freed.
+ */
+struct ast_party_id ast_party_id_merge(struct ast_party_id *base, struct ast_party_id *overlay);
+
+/*!
+ * \brief Copy a merge of a given party id into another given party id to a given destination party id.
+ * \since 11.0
+ *
+ * \details
+ * Each party id component of the party id 'base' is overwritten by components
+ * of the party id 'overlay' if the 'overlay' component is marked as valid.
+ * However the component 'tag' of the 'base' party id remains untouched.
+ * The result is copied into the given party id 'dest'.
+ *
+ * \note The resulting merged party id is a real copy and has to be freed.
+ *
+ * \param dest The resulting merged party id.
+ * \param base The party id which is merged.
+ * \param overlay The party id which is used to merge into.
+ *
+ * \return Nothing
+ */
+void ast_party_id_merge_copy(struct ast_party_id *dest, struct ast_party_id *base, struct ast_party_id *overlay);
+
+/*!
  * \brief Initialize the given dialed structure.
  * \since 1.8
  *
@@ -3778,8 +3873,12 @@ struct ast_frame *ast_channel_dtmff(struct ast_channel *chan);
 struct ast_jb *ast_channel_jb(struct ast_channel *chan);
 struct ast_party_caller *ast_channel_caller(struct ast_channel *chan);
 struct ast_party_connected_line *ast_channel_connected(struct ast_channel *chan);
+struct ast_party_id ast_channel_connected_effective_id(struct ast_channel *chan);
 struct ast_party_dialed *ast_channel_dialed(struct ast_channel *chan);
 struct ast_party_redirecting *ast_channel_redirecting(struct ast_channel *chan);
+struct ast_party_id ast_channel_redirecting_effective_orig(struct ast_channel *chan);
+struct ast_party_id ast_channel_redirecting_effective_from(struct ast_channel *chan);
+struct ast_party_id ast_channel_redirecting_effective_to(struct ast_channel *chan);
 struct timeval *ast_channel_dtmf_tv(struct ast_channel *chan);
 struct timeval *ast_channel_whentohangup(struct ast_channel *chan);
 struct varshead *ast_channel_varshead(struct ast_channel *chan);