How Does 'display', 'from', and 'to' parameter values work in PKX_CALL_Make for SIP

[agauthier]

[Pika Support >>> Note: This explanation applies to HMP 2.8 ]

The purpose of this post is to clarify how the ‘display’, ‘from’, and ‘to’ parameter values in the PKX_CALL_Make API are used to make SIP calls along with the user configuration parameters. Assume the following GP configuration is used (this is the default configuration generated by GPConfig) and that the SIP “From” field is built as follows: “callerid” <sip:”username”@”host/ipaddress”>


Assuming the GP Configuration Files would be set as follows:

[sip]
sip0=SIP_DEFAULT

[SIP_DEFAULT]
interface=192.168.68.19:5060
audio.portrange=24000-24008
channels=4
rport=enable
;userid_override=disabled

[sip_users]
user0=USER_DEFAULT
user1=PROXY_USER

[USER_DEFAULT]
group=sip0
default=yes
user_name=GP_SIP_USER
display_name=GP_SIP_USER
;password=password
;proxy.address=127.0.0.1
;proxy.port=5060
;proxy.registration=enabled
;proxy.outbound=disabled
;expires=3600
codecs=g711u|g711a

[PROXY_USER]
group=sip0
user_name=PROXY_USER
display_name=ProxyUser
password=password
proxy.address=192.168.78.133
;proxy.port=5060
;proxy.registration=enabled
;proxy.outbound=disabled
expires=3600
codecs=g711u|g711a

Case 1: PKX_CALL_Make(display=””, from=””, to=”192.168.68.78”)

INVITE From: “GP_SIP_USER” <sip:GP_SIP_USER@192.168.68.19>
To: <sip:192.168.68.78>

In this case the user does not provide the ‘display’ or ‘from’ values, so GP assumes that the default user agent information is to be used.

Case 2: PKX_CALL_Make(display=”Hello World”, from=””, to=”192.168.68.78”)

INVITE From: “Hello World” <sip:GP_SIP_USER@192.168.68.19>
To: <sip:192.168.68.78>

In this case the user does not provide the ‘from’ value, so GP assumes that the default user agent is to be used. However, the callerid information provided by the user is included in the SIP INVITE message.

Case 3: PKX_CALL_Make(display=”Hello World”, from=”GP_SIP_USER”, to=”192.168.68.78”)

INVITE From: “Hello World” <sip:GP_SIP_USER@192.168.68.19>
To: <sip:192.168.68.78>

Case 4: PKX_CALL_Make(display=”Hello World”, from=”GP_SIP_USER@192.168.68.19”, to=”192.168.68.78”)

INVITE From: “Hello World” <sip:GP_SIP_USER@192.168.68.19>
To: <sip:192.168.68.78>


Case 3 & 4 will have the same result as case 2.

Case 5: PKX_CALL_Make(display=”Hello World”, from=”PROXY_USER”, to=”192.168.68.78”)

INVITE From: “Hello World” <sip: PROXY_USER@192.168.78.133>
To: <sip:192.168.68.78>

In this case, GP looks for the “PROXY_USER” agent and uses the information provided in the configuration file to establish the call. Note that the SIP “From” field now contains the IP address of the SIP proxy server.

Case 6: PKX_CALL_Make(display=””, from=”PROXY_USER@192.168.78.133”, to=”192.168.68.78”)

INVITE From: “ProxyUser” <sip: PROXY_USER@192.168.78.133>
To: <sip:192.168.68.78>

Case 7: PKX_CALL_Make(display=””, from=”PROXY_USER@192.168.68.19”, to=”192.168.68.78”)

INVITE From: “ProxyUser” <sip: PROXY_USER@192.168.78.133>
To: <sip:192.168.68.78>

Case 6 & 7 will have the same result as case 5. However, the callerid information used is the one in the configuration file.

Case 8: PKX_CALL_Make(display=””, from=”Testing”, to=”192.168.68.78”)

Case 8 will fail. The “Testing” user agent has not been configured and the ‘userid_override’ parameter is disabled. However, if the ‘userid_override’ parameter was enabled, GP would replace the username portion of the sip “From” field with the information provided. Note that the default user agent information (codecs, dtmf_mode, etc) would be used to establish the call.

The ‘userid_override’ option was created to allow the user to make SIP calls using various usernames without the need to have an agent configured.

Case 9: PKX_CALL_Make(display=””, from=””, to=”192.168.68.78:5090”)

INVITE From: “GP_SIP_USER” <sip:GP_SIP_USER@192.168.68.19>
To: <sip:192.168.68.78>

Case 9 would behave the same way as case 1, however the INVITE message would be sent to SIP port 5090 instead.

Case 10: PKX_CALL_Make(display=””, from=””, to=”pika@192.168.68.78:5090”)

INVITE From: “GP_SIP_USER” <sip:GP_SIP_USER@192.168.68.19>
To: <sipika@192.168.68.78>

Case 10 would behave the same way as case 9, however the INVITE message would be sent to SIP user ‘pika’.

Case 11: PKX_CALL_Make(display=””, from=”PROXY_USER”, to="sipura”)

INVITE From: “ProxyUser” <sip: PROXY_USER@192.168.78.133>
To: <sip:sipura>

Case 11 would behave the same as case 6 & 7 if ‘sipura’ resolves to 192.168.68.78. This is because GP sends a DNS request out to resolve the “To” parameter. If the DNS request fails to provide a valid IP address, the call would failed. Note that for case 11, the new ‘proxy.outbound’ parameter is disabled as well. If ‘proxy.outbound’ was enabled, GP would not send a DNS request and instead assume this is a username or extension and use the ‘proxy.address’ value to build the SIP “To” field as follows: To: <sip:sipura@192.168.78.133>

The “proxy.address”, “proxy.port”, “proxy.registration”, and “proxy.outbound” are new configuration parameters introduced in this release to replace the “proxy_name” and “proxy_port” parameters.

The “proxy.address” should contain the IP address of the remote SIP proxy. The “proxy.port” should contain the port number. The “proxy.registration” parameter allows the customer to specify if GP should send a registration message to the SIP proxy. The “proxy.outbound” parameter allows the customer to specify that if the PKX_CALL_Make “To” parameter does not contain a valid IP address or username/IP address combination to assume that it is a username and use the proxy info to build the SIP “To” field.

Note that cases 1-10 did not involve a SIP proxy, these were all peer-to-peer connections (even when I use the PROXY_USER agent).

[pikasupport]

HMP 3.0 - Enhanced Dial By Name

• This enhancement allows the user to perform call processing without the specific need for user configuration.
• GP will no longer have a default user. User defaults will be configured under the group section.
• The "userid_override" configuration key is deprecated.
• The addressing rules are as follows:
  
  • Outgoing Calls
    
    • The “to” field is used to identify the destination of the call. This information affects the routing of the call and the actual information put into the “TO” header.
    • The “from” field is used to identify the originator (user) of the call. This information affects the routing of the call and the actual information put into the “TO”, “FROM” & “CONTACT” headers.
    • If the user cannot be determined from the “from” field, group defaults are used. The “userid_override” key has been deprecated, and this is now the hard-coded behavior. NOTE that this means a call will never fail to an improper “from” field. Also NOTE that there is no longer the concept of a specific “default” user. User defaults are now configured against the group.
    • The “from” field can be NULL, but if it is non-NULL it MUST contain at least a username (which may or may not be valid). An IP address or hostname by itself is not allowed. The idea is to simplify having to distinguish between them and Usernames, and having to search all users for a matching hostname/address.
    • The following is s list of valid “from” strings:
      
      • username
      • username@IP addres
      • username@IP address:Port
      • username@hostname
      • username@hostname:Port
      • NULL
    • Finding a valid user means that the complete string must match configured data. If the username indicated does not have a matching IP address or hostname configured in user or group data, then the match fails (and group defaults are used).
    • When determining the “configured address”, a match is checked against either “external_IP”, or “proxy.address”, or “interface”. This means that configured address could contain a hostname (if configured for “external_IP”).
    • The “FROM” header will simply contain the string provided in the “from” field.
      
      • if NULL is provided, the configured data will be used. If there is no configured username, sip:configured address is used.
      • If only username is provided, the configured address will be appended
    • The “CONTACT” header will contain username@configured address. If there is no configured username, sip:configured address is used. Here, the configured address must be the “external_IP” or the “interface” value.
    • The “to” field cannot be NULL. It MUST contain at least a username or extension
    • The following is s list of valid “to” strings:
      
      • username
      • username@IP address
      • username@IP address:Port
      • username@hostname
      • username@hostname:Port
      • extension
      • extension@IP address
      • extension@IP address:Port
      • extension@hostname
      • extension@hostname:Port
      • IP address
      • IP address:Port
      • hostname
      • hostname:Port
    • Since “username” and “extension” are just strings, they are treated the same.
    • The “to” field is checked for the presence of an IP address or hostname. The check is to look for the presence of the “@” or “:” characters in the string, or for an IP address (a.b.c.d). If found, no further manipulation is done.
    • Since GP cannot distinguish between username/extensions and hostnames, the “proxy.outbound” config key is used to control behavior.
      
      • If the IP address/hostname check fails and if the “proxy.outbound” config key is enabled, the “proxy.address” is appended to the “to” field. i.e treat the “to” as a username/extension. Otherwise, GP assumes that a hostname is being used.
    • The “TO” header will simply contain the string provided in the “to” field if an IP address/hostname is found. If not found, the “proxy.address” will be appended if required.
  • Incoming Calls
    
    • The ‘from” field is simply a string that is provided to the application in the CallInfo.
    • The “to” field is used to identify the destination of the call. The same matching rules as above will apply. The determined configuration data will impact how the call is processed. The field is also simply provided as a string to the application in the CallInfo.
    • The “CONTACT” header in response messages will contain username@configured address. If there is no configured username, sip:configured address is used.