FRRD FR18949 - SIP OPTIONS Ping.doc
Version | Author | Date | State | Description of Changes |
---|---|---|---|---|
0.1 | Gregory Trogani | 08/11/2015 | Working Draft | Initial version. |
0.2 | Gregory Trogani | 09/11/2015 | Final Draft | Incorporated comments from document review.
|
0.3 | Gregory Trogani | 09/24/2015 | Final draft | Modified requirements to specify new BFV API function instead of existing BfvBoardNotify() function for SIP Gateway status notifications. |
Terminology
The verb "shall" indicates the requirement is mandatory for implementation. The verb "may," "might" and "should" indicate the text is recommendation and/or optional for implementation. The verb "will" expresses a future expectation of a requirement, or is used to reference details provided for informational purposes h8.Acronyms
Acronym | Description |
---|---|
API | Application Programming Interface. |
BFV | Boston Fax and Voice API. |
SIP | Session Initiation Protocol |
TCP | Transmission Control Protocol |
UDP | User Datagram Protocol |
Product Issue Description
In order to build efficient and robust SIP networks, it’s sometimes necessary for one SIP endpoint to know the status of another SIP endpoint. Having this knowledge can better enable intelligent routing of messages when establishing a dialog. This knowledge may also be used to alert network administrators to potential problems with SIP endpoints so that corrective action can be taken to maintain a healthy SIP infrastructure with expected service performance.
The SIP specification defines the REGISTER method that enables a SIP user agent to register with a registrar and to send periodic registration (“refresh”) messages. The purpose for the REGISTER message is to add and remove bindings, though it may also serve as a type of "keep-alive" mechanism to assist in determining whether a user agent is presently available. However, a REGISTER message is not the appropriate method to communicate SIP endpoint status between any two SIP endpoints, such as between two SIP proxy servers or between a Back-to-Back User Agent (B2BUA) and any number of peer B2BUAs that help facilitate communication between administrative domains.
One use of the SIP OPTIONS method is to enable a SIP endpoint to query for the capabilities of a remote SIP endpoint in advance of establishing a dialog, which may help in selecting an appropriate target user agent. By extending the scope of this method it’s possible to enable any SIP endpoint to query for the operational status of another SIP endpoint, thereby achieving the objective of equipping SIP endpoints with more knowledge about the operational status of peer endpoints.
The use of SIP OPTIONS to determine the operational status of peer SIP endpoints is widely used today by numerous equipment manufacturers and is informally referred to as an “OPTIONS ping”.
Overall Feature Description
FR18949 will provide SIP OPTIONS Ping feature support that will allow a user to configure up to four SIP Gateways for the Dialogic Brooktrout SIP stack. The Dialogic Brooktrout SIP stack will periodically transmit SIP OPTIONS requests (i.e. ping) each of these SIP Gateways to determine their operational status. When the highest priority SIP Gateway is determined to be “DOWN” or unavailable to process SIP calls, then the Dialogic Brooktrout SIP stack will automatically route all new outbound SIP calls to the next SIP Gateway in the priority list whose current status is “UP”.
A new Dialogic Brooktrout BFV API function will be introduced as part of this feature to allow BFV applications to receive notification of SIP Gateway status changes along with the most recent responses to SIP OPTIONS Ping requests transmitted by the Dialogic Brooktrout SIP stack. This new function can be passed a pointer to a callback function that will be invoked whenever an operational status change is detected on any of the SIP Gateways that are configured in the callctrl.cfg configuration file. In addition to this, if a value of NULL is specified for the callback function pointer when the new BFV API function is called, the current status of all the configured SIP Gateways will be immediately returned to the application.
Assumptions
- None
Feature Limitations, Caveats, or Restrictions
- None
Customer Use-Case
- The callctrl.cfg configuration file is populated with 4 SIP Gateway entries and the Boston Host Service is initialized.
- SIP OPTIONS Ping requests are transmitted to each of the SIP Gateways with a periodic interval defined by the “UP” interval timer parameter specified in the callctrl.cfg configuration file.
- Each of the SIP Gateways respond to the SIP OPTIONS Ping requests with SIP 200 OKs.
- A Dialogic Brooktrout BFV application calls the new BFV API function specifying that it wants to be notified of SIP Gateway status changes and passing in a pointer to a callback function.
- Outbound SIP gateway calls are routed to the SIP Gateway specified by the sip_default_gateway parameter in the callctrl.cfg configuration file.
- After some time, the SIP Gateway referenced by sip_default_gateway stops responding to the SIP OPTIONS Ping requests.
- The callback function passed to the new BFV API function is invoked and information is passed to it that indicates that the first SIP Gateway is DOWN but the remaining three SIP Gateways are still UP.
- SIP OPTIONS Ping requests are transmitted to the SIP Gateway referenced by sip_default_gateway with a periodic interval defined by the “DOWN” interval timer parameter specified in the callctrl.cfg configuration file
- SIP OPTIONS Ping requests are transmitted to each of the remaining SIP Gateways with a periodic interval defined by the “UP” interval timer parameter.
- All new outbound SIP gateway calls are now routed to SIP Gateway #2 (the next highest priority SIP Gateway) as specified in the callctrl.cfg configuration file.
- After some time, the SIP Gateway referenced by sip_default_gateway resumes responding to the SIP OPTIONS Ping requests with SIP 200 OK responses.
- The callback function passed to the new BFV API function is invoked and information is passed to it that now indicates that all four of the SIP Gateways are “UP”.
- All new outbound SIP gateway calls are now routed to the SIP Gateway referenced by sip_default_gateway.
- SIP OPTIONS Ping requests are now transmitted to all of the SIP Gateways with a periodic interval defined by the “UP” interval timer parameter.
Architectural Description
N/A
Requirements
RID# | Description |
---|---|
1 | FR18949 (SIP OPTIONS Ping) feature support shall be available on all versions of operating systems supported by the Dialogic Brooktrout SDK 6.7mnt release. |
2 | FR18949 shall introduce support for up to a maximum of four SIP Gateways to be specified in the callctrl.cfg configuration file. |
3 | FR18949 (SIP OPTIONS Ping) functionality shall be enabled whenever multiple SIP Gateways are specified in the callctrl.cfg configuration file. |
4 | If only one SIP Gateway is configured in the callctrl.cfg configuration file, then FR18949 (SIP OPTIONS Ping) functionality shall not be enabled and no SIP OPTIONS Ping requests will be transmitted to determine the status of the SIP Gateway. |
5 | The existing sip_default_gateway parameter in the callctrl.cfg configuration file used to specify the default SIP gateway shall remain a valid and supported parameter. |
6 | A new parameter shall be added to the SIP [host_module.x/parameters] section of the callctrl.cfg configuration file for each of the newly supported SIP Gateways specified in requirement RID#2. |
7 | The default value for each of the parameters used to specify the SIP Gateways shall be blank. In other words, nothing will be specified for the default value for these parameters. |
8 | The SIP Gateways specified in requirement RID#2 shall be configurable on the Windows operating system via the configtool.exe configuration tool as standard IP Parameters for the SIP IP Call Control Module. |
9 | The priority of the SIP Gateways referenced in requirement RID#2 shall be in descending order with the sip_default_gateway as the highest priority, SIP Gateway #2 as the second highest priority, SIP Gateway #3 as the third highest priority and SIP Gateway #4 as the lowest priority. |
10 | A new parameter shall be added to the SIP [host_module.x/parameters] section of the callctrl.cfg configuration file to allow a SIP OPTIONS Ping "UP" interval timer to be specified for the interval time to send periodic SIP OPTIONS requests when the status of a gateway is "UP". |
11 | The SIP OPTIONS Ping "UP" interval timer parameter specified in requirement RID#10 shall be configurable on the Windows operating system via the configtool.exe configuration tool in the Advanced Settings section of the IP Parameters for the SIP IP Call Control Module. |
12 | A new parameter shall be added to the SIP [host_module.x/parameters] section of the callctrl.cfg configuration file to allow a SIP OPTIONS Ping "DOWN" interval timer to be specified for the interval time to send periodic SIP OPTIONS requests when the status of a gateway is "DOWN". |
13 | The SIP OPTIONS Ping "DOWN" interval timer parameter specified in requirement RID#12 shall be configurable on the Windows operating system via the configtool.exe configuration tool in the Advanced Settings section of the IP Parameters for the SIP IP Call Control Module. |
14 | When the Boston Host Service first initializes, all SIP Gateways specified in the callctrl.cfg configuration file shall default to the "UP" status. |
15 | Once the Boston Host Service has completed its initialization processing, if multiple SIP Gateways are configured in the callctrl.cfg configuration file, SIP OPTIONS requests shall be transmitted to each of the configured SIP Gateways at a periodic interval specified by the SIP OPTIONS Ping "UP" interval timer specified in RID#10. |
16 | A SIP Gateway shall be determined to be "DOWN" when any of the following occurs or is received in response to a transmitted SIP OPTIONS Ping request:
|
17 | Once the status of a SIP Gateway is determined to be "DOWN", SIP OPTIONS requests shall be transmitted to it at a periodic interval specified by the SIP OPTIONS Ping "DOWN" interval timer specified in RID#12. |
18 | All responses (including SIP 4xx responses) to a transmitted SIP OPTIONS Ping request with the exception of those identified in RID#16 shall be considered valid and will result in a SIP Gateway status value of "UP". |
19 | Any response to a SIP OPTIONS Ping request that includes a Retry-After SIP header shall be honored and will override the value of the SIP OPTIONS Ping interval timer currently in use for the specific SIP Gateway when the value of the interval timer is less than the value of the Retry-After SIP header. |
20 | When multiple SIP Gateways are configured in the callctrl.cfg configuration file, all outbound SIP calls shall be directed to the highest priority SIP Gateway (see RID#9) whose current status is "UP". |
21 | The BFV API BfvBoardNotify() function shall be modified to support notification of SIP Gateway status changes. |
22 | When FR18949 functionality determines that the status of a SIP Gateway has changed (either the status has changed from "UP" to "DOWN" or vice versa, any callback function currently configured by the BfvBoardNotify() BFV API function shall be invoked to receive notification of the SIP Gateway status change. |
23 | The information returned by the BFV API BfvBoardNotify() function regarding a SIP Gateway status change notification shall include the current status of all SIP Gateways configured in the callctrl.cfg configuration file along with the most recent response to a SIP OPTIONS Ping request. |
24 | If the status of all SIP Gateways configured in the callctrl.cfg configuration file are currently "DOWN" at the time that an outbound SIP call is initiated, then the call attempt will immediately fail with no SIP INVITE transmitted for the call attempt and an appropriate error returned to the BFV API application in the RES results structure. |
25 | SIP OPTIONS requests transmitted as part of the FR18949 functionality shall only be transmitted using the UDP transport protocol. |
26 | If a SIP Gateway is determined to be "DOWN" by the FR18949 (SIP OPTIONS Ping) processing, any SIP calls currently in progress that are routed to the gateway shall continue with their normal call processing and will not automatically be terminated. |
27 | If a value of NULL is specified for the callback function pointer when the BFV API BfvBoardNotify() function is called, the current status of all SIP Gateways configured in the callctrl.cfg configuration file along with the most recent responses to SIP OPTIONS Ping requests shall be immediately returned to the application via the args_board_notify structure parameter. |
MRD/FR Requirements/Mapping
N/A
Reference List
RFC 3261 - SIP: Session Initiation Protocol (http://www.ietf.org/rfc/rfc3261.txt)
Packetizer Open Community Specification POCS-1 – Using OPTIONS to Query for Operational Status in the Session Initiation Protocol (SIP) (http://hive1.hive.packetizer.com/users/packetizer/pocs/POCS-1.pdf)
Product Areas Affected
- This feature will only affect the SIP protocol.
API/Library Change(s):
- A new BFV API function will be introduced for this feature to allow enabling SIP Gateway Status change notifications as well as reporting information regarding the SIP Gateway status changes.
- New #defines will be added for use with the new BFV API function.
- A new structure will be added for use with the new BFV API function.
- No changes to any 3rd party components are required for this feature request.
Documentation Change(s)
- The Dialogic Brooktrout Bfv APIs Reference Manual will be updated to document the new BFV API function introduced for this feature and will illustrate how to enable SIP Gateway status change notifications and also how to interpret data returned for a SIP Gateway status change notification.
Configuration Change(s)
The following configuration file changes required to support this feature are as follows:
- New parameter settings in the callctrl.cfg file to allow users to specify multiple SIP Gateways.
- A new parameter setting in the callctrl.cfg file to allow users to specify the interval time to send periodic SIP OPTIONS requests when the status of a gateway is “UP”.
- A new parameter setting in the callctrl.cfg file to allow users to specify the interval time to send periodic SIP OPTIONS requests when the status of a gateway is “DOWN”.
For each of the parameters listed above, there are four items that will be defined in order to provide CONFIGTOOL.EXE support:
- The name of the parameter that is in the callctrl.cfg file.
- The long description that goes into the help file for the item.
(Most of the time the help file is the API documentation) - The short description that goes into the ConfigTool form.
- The tooltip text that's shown when the cursor is over the input or selection box for the item.
The specific information defined for each of the parameters listed above will be defined in the High Level Design document for this feature.
Build and Installation Change(s)
- None
Specific Product Deliverables
File | Windows | Linux | Solaris* |
bostdlld.dll |
|
| |
brktsip.dll |
|
| |
| |||
|
*This feature will be implemented on the Windows Linux and Solaris Operating Systems (OSs). However, testing of this feature will be limited to Windows and Linux OSs. Testing of this feature on the Solaris OS will not be performed.
Required Purchases
- None
Product SKUs and Materials
- None
Test Scenario(s)
The developer test plan will document the full description of the test cases below along with the results of the developer testing. This testing shall, at a minimum, contain the following test cases:
- Single SIP Gateway Configured:
This test case verifies that when a user configures the Dialogic Brooktrout SIP Stack with a single SIP Gateway, FR18949 functionality is not enabled and no SIP OPTIONS Ping requests are transmitted. In addition to this, this test verifies that outbound SIP Gateway calls can be successfully established with the configured SIP Gateway.
- Multiple SIP Gateways Configured: All Gateways “UP”
This test case verifies that when a user configures the Dialogic Brooktrout SIP Stack with multiple SIP Gateways, FR18949 functionality is enabled and SIP OPTIONS Ping requests are successfully transmitted to each of the configured SIP Gateways at the specified “UP” interval in the callctrl.cfg configuration file. In addition to this, this test verifies that the new BFV API function introduced for this feature can be used to successfully return the current status of each of the configured SIP Gateways and that outbound SIP Gateway calls can be successfully established with the highest priority SIP Gateway whose status is “UP”.
- Multiple SIP Gateways Configured: Some Gateways “DOWN”
This test case verifies that when a user configures the Dialogic Brooktrout SIP Stack with multiple SIP Gateways, FR18949 functionality is enabled and SIP OPTIONS Ping requests are successfully transmitted to each of the configured SIP Gateways at the specified “UP” or “DOWN” intervals in the callctrl.cfg configuration file, as appropriate. In addition to this, this test verifies that the new BFV API function introduced for this feature can be used to successfully return the current status of each of the configured SIP Gateways and that outbound SIP Gateway calls can be successfully established with the highest priority SIP Gateway whose status is “UP”.
- Multiple SIP Gateways Configured: All Gateways “DOWN”
This test case verifies that when a user configures the Dialogic Brooktrout SIP Stack with multiple SIP Gateways, FR18949 functionality is enabled and that, once the status of all of the SIP Gateways is “DOWN”, SIP OPTIONS Ping requests are successfully transmitted to each of the configured SIP Gateways at the specified “DOWN” interval in the callctrl.cfg configuration file. In addition to this, this test verifies that the new BFV API function introduced for this feature can be used to successfully return the current status of each of the configured SIP Gateways and that outbound SIP Gateway calls immediately fail with an appropriate error returned in the BFV API RES results structure.
Planning Information
Deliverables required during planning
The following development or management process artifacts are required for this feature during planning and Implementation. This should be taken into consideration when developing estimates.
Deliverable | Required | Notes |
Work Breakdown Spreadsheet (or SW Implementation Plan) | No |
|
Developer Test Plan | Yes |
|
QA Test Plan | No |
|
High Level Design Document | Yes |
|
Feasibility Study | No |
|
mIPA Presentation | Yes |
|
Certification of Origin revision | No |
|
Patent Submission | No |
|
Target Release: SDK 6.7mnt
Backward propagation Release(s): None
Risks: None
Add Comment