Asterisk Project : Private Representation of Party Information This page last changed on Aug 20, 2012 by mjordan. This page was written by Thomas Arimont of DATUS AG, Germany Minor editing by Matt Jordan Private Representation of Caller, Connected and Redirecting Party IDs Feature implemented in Asterisk 11 by Thomas Arimont, DATUS AG, Germany # Overview Asterisk already offers a lot of techniques to set and modify party names and numbers of different kinds. There are a number of dialplan functions - CALLERID, CONNECTEDLINE, REDIRECTING - that allow you to read and write a wide range of parameters for Asterisk. However, prior to Asterisk 11 it is quite difficult to modify a party number or name which can only be seen by exactly one particular instantiated channel resp. 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 (has to copy) 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 involved call parties. Also in this case the provided party numbers or names are (have to be) taken from the Caller or Connected ID of the corresponding Asterisk channels. One major feature where a private representation of party names is essentially needed, i.e., where a party name shall exclusively be signalled 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. Asterisk 11 now provides a mechanism by which private party identification information can be signalled to a particular device.
| For more information on advanced manipulation of Party Identification in Asterisk, see Manipulating Party ID Information. Note that it is highly recommended that you are intimately familiar with manipulating party information in Asterisk before reading further.
This feature is supported in the following channel drivers: SIP (chan_sip) mISDN (chan_misdn) PRI (chan_dahdi). # Feature Description This feature defines additional private number and name elements for Caller ID, Connected ID, and Redirecting IDs inside Asterisk channels. The private number and private name elements can be read or set by the user using the respective Asterisk dialplan functions for those elements. When a channel initiates a call, if it receives an internal connected line update event or an internal redirecting update event, it first checks if there is a valid Connected ID or Redirecting ID private name or number element present. If this is the case it uses this private representation for protocol signalling. If there is no valid private name or number present, then the valid 'regular' non-private name or number element is used instead. ## Automatic Invalidation of Private Information Once a private name or number on a channel is set and (implicitly) made valid, it is generally used for any further protocol signalling 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 channels – receiving regarding protocol information - automatically trigger the invalidation of private IDs. This explicitly takes place when one of the following conditions occurs: An internal Asterisk channel masquerading is processed (blind and attended transfers, pickup, parking) Extra connected line update events are internally generated during a SIP specific attended transfer Extra connected line update events are generated during a call pickup Connected line update events are generated in the SIP channel due to receipt of corresponding SIP protocol elements (remote party id header, p-asserted-identity header) Redirecting update events are generated in the SIP channel due to receipt of corresponding SIP protocol elements (diversion header) Connected line update events are generated in the DAHDI/PRI or mISDN channel due to receipt of corresponding ISDN protocol elements (display IE, connected number IE) Redirecting update events are generated in the DAHDI/PRI or mISDN channel due to receipt of corresponding ISDN protocol elements (redirecting/redirection IE, divleginfo facility IE) ## Manual Invalidation of Private Information In some cases the invalidation of private IDs cannot be done automatically and therefore it is a job the user has to do by applying appropriate and explicit dialplan commands. This is done by setting the `priv-nam-valid` item to `0`. Example
    same =&gt; n,Set(CONNECTEDLINE(priv-name-valid)=0)
As an example of where manual invalidation is necessary, consider the case when a private connected name is set towards a particular caller, and after this a blind transfer is executed by the callee to another target where only a 'regular' non-private connected name is set. Because of the priority of the still valid private connected name id on the caller's channel the 'regular' non-private connected name will not become visible to the caller. To solve this issue the user should in general explicitly invalidate the private connected name/number when setting a 'regular' non-private connected name/number.
| The user is advised to do the setting of private ids directly on the particular channel which is transmitting the corresponding protocol elements. Using the forward inheritance of the CALLERID, CONNECTLINE and REDIRECTING channel variables can lead to unexpected results.
# Recommended Mechanism for Setting Private Identity The setting of private calling party numbers or names shall be done by using the Pre-Dial CALLEE subroutine (Dial application option 'b'). The setting of private REDIRECTING ids towards the redirected-to party shall also be done using the Pre-Dial CALLEE subroutine. Since the setting of the private CALLERID in the Pre-Dial CALLEE subroutine has to be made by using the CONNECTEDLINE setter function, the setter function for CALLERID is not used at all in this scenario. The setting of any kind of private connected numbers or names as well as private `REDIRECTING` IDs towards a caller shall be done by using the system subroutines CONNECTED_LINE_SEND_SUB resp. REDIRECTING_SEND_SUB. If not using the private number and name representation feature at all, i.e., if using only the 'regular' CALLERID, CONNECTEDLINE and REDIRECTING related function datatypes, the current characteristics of Asterisk's manipulation of party identification is not affected by the new extended functionality. # Dialplan Manipulation To grant access to the private name and number representation out of the asterisk dialplan, the read and write functions of the three Asterisk defined functions CALLERID, CONNECTEDLINE and REDIRECTING are extended by the following datatypes. The formats of these additional datatypes are equivalent to the corresponding regular 'non-private' already existing datatypes: ### 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`
| Mixing of private and public id elements is valid.
| The presentation and the numbering plan datatypes of private ids become visible when a private id number or name is valid.
# Example Dialplans ### Setting the private calling name
    [incoming_context]
     ; (optionally) Setting the public calling name as usual
     exten =&gt; 10,1,ExecIf($[${CALLERID(num)}=20]?
     	 	 Set(CALLERID(name)=Peter Public):)
     exten =&gt; 10,n,ExecIf($[${CALLERID(num)}=30]?
     	 	 Set(CALLERID(name)=Mark Public):)

     ;using the Dial() b-option to execute a pre-dial subroutine on the target channel
     exten =&gt; 10,n,Dial(SIP/10, ,b(privatecallingname))
     exten =&gt; 10,n,Hangup()

     ; setting  the private calling name (on target/dialed-to channel only)
     ; Since the Pre-dial CALLEE subroutine is acting on the target channel the
     ; CONNECTEDLINE parameter has to be set instead of the CALLERID parameter
     ; This might look strange at first sight but the CALLERID of the dialing channel
     ; becomes the CONNECTEDLINE of the dialed-to channel since the the Dial()-
     ; application copies the caller id of the dialing channel to the connected id of the
     ; target channel
     exten =&gt; 10,n(privatecallingname), NoOp()
     exten =&gt; 10,n,ExecIf($[${CONNECTEDLINE(num}=20]?
     	 	 Set(CONNECTEDLINE(priv-name,i)=Peter Private):)
     exten =&gt; 10,n,ExecIf($[${CONNECTEDLINE(num}=30]?
     	 	 Set(CONNECTEDLINE(priv-name,i)=Mark Private):)

     ; Of course in a more general approach the private calling name should be determined
     ; by a database lookup instead. For this purpose the database would have to provide
     ; user-specific (identified by the called party number, i.e. ${EXTEN}) private party
     ; names of the calling party (identified by the calling party number,
     ; i.e. ${CONNECTEDLINE(num)})

     exten =&gt; 10,n,Return()
| The setting of a private redirecting-from name (if an internal diversion shall be indicated to the forwarded-to party) can be done similar in the same context.
### Setting the private connected name
    [globals]
      CONNECTED_LINE_SEND_SUB = connectedline,s,1
     CONNECTED_LINE_SEND_SUB_ARGS =,

     [incoming context]
     ; Setting the public connected name or/and number as usual
     exten =&gt; 10,1,Set(CONNECTEDLINE(name,i)=Donald Public)
     exten =&gt; 10,1,Set(CONNECTEDLINE(num,i)=10)

     ; Generally invalidate the private connected name and number in case it is not
     ; explicitly set somewhere later. This prevents the technology channel which is
     ; receiving the internal connectedline update event from using a former set private
     ; connected id representation

     exten =&gt; 10,n,Set(CONNECTEDLINE(priv-name-valid,i)=0)
     exten =&gt; 10,n,Set(CONNECTEDLINE(priv-num-valid,i)=0)
     exten =&gt; 10,n,Set(CONNECTEDLINE(source)=answer)

     exten =&gt; 10,n,Dial(SIP/10, ,)
     exten =&gt; 10,n,Hangup()

     [connectedline]
     exten =&gt; s,1, NoOp()
     exten =&gt; s,n,GotoIf($[${CHANNEL(channeltype)}=Local]?out:)
     ; The following setting is done on the technology channel which signals
     ; the connected name by its corresponding protocol elements

     ; e.g., only signal the private connected name of callee '10' to caller '20'
     exten =&gt; s,n,GotoIf($[${CALLERID(num)}!=20]?out:)
     exten =&gt; s,n,GotoIf($[${CONNECTEDLINE(num)}!=10]?out:)
     exten =&gt; s,n,Set(CONNECTEDLINE(priv-name)=Donald Private)

     ; Of course in a more general approach the private connected name should be
     ; determined by a database lookup instead. For this purpose the database would have
     ; to provide user-specific (identified by the destination of the connectedline update
     ; event, i.e. ${CALLERID(num)}) private party names which represents the
     ; originator of the connectedline update event (i.e. identified by
     ; ${CONNECTEDLINE(num)})

     exten =&gt; s,n(out),Return()
| Setting the private `redirecting-from` or `redirecting-to` names (if an internal diversion shall be indicated to the `forwarded-to` party or a diversion signalling shall be manipulated towards an involved subscriber) can be done similar using the `REDIRECTING_SEND_SUB` subroutine.
## Attachments: Feature_private_representation_of caller_connected_and_redirecting_party_ids_revision_2.odt (application/vnd.oasis.opendocument.text)

Document generated by Confluence on Nov 02, 2012 17:42