Versions Compared

Old Version 1

changes.mady.by.user John Shaheen

Saved on

compared with

New Version Current

changes.mady.by.user Stephen Hoogerhyde

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Repair Jira Macros
Page Properties
Target release6.7.4FRRD FR18949 - SIP OPTIONS Ping.doc
Epic
Jira Legacy
serverDialogic System JIRA
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId8f70d0a49d998c43-20dab14a-363f37e0-81e294cb-5b2706a93a6ae776ac9fe88f
keyBRKT-255
JIRA FR
Jira Legacy
serverDialogic System JIRA
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId8f70d0a49d998c43-20dab14a-363f37e0-81e294cb-5b2706a93a6ae776ac9fe88f
keyBRKT-338
Document status
Status
colourGreen
titleDRAFTApproved
Document owner

Greg Trogani (Deactivated)

Designer
Developers
QA

 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.

  • Updated Use Case description to clarify SIP OPTIONS interval after GW status transitions from "DOWN" to "UP".
  • Added extra requirement to define the BfvBoardNotify() functionality when NULL is specified for the callback function pointer parameter.

0.3

 

Terminology

...

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

...

In order to build efficient and robust SIP networks, it's 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"“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 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"“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 Anchor_Hlk427011108_Hlk427011108 the Anchor_Hlk427011198_Hlk427011198 Dialogic Brooktrout 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" “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"“UP”. The

A new Dialogic Brooktrout Anchor_Hlk427011425_Hlk427011425 BfvBoardNotify() BFV API function will be modified introduced as part of this feature to allow BFV applications to receive notification of SIP Gateway status changes . The BfvBoardNotify() 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
    • Anchor_Hlk427005675_Hlk427005675
    • callctrl.cfg configuration file is populated with 4 SIP Gateway entries and the Boston Host Service is initialized.
    • Anchor_Hlk427008480_Hlk427008480
    • SIP OPTIONS Ping requests are transmitted to each of the SIP Gateways with a periodic interval defined by the
    • "UP" interval
    • “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
    • Anchor_Hlk427007968_Hlk427007968 the BfvBoardNotify()
    • the new BFV APIfunction specifying that it wants to be notified of SIP Gateway status changes and passing in a pointer to a callback function.
    • Anchor_Hlk427008427_Hlk427008427
    • 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
    • Anchor_Hlk427007419_Hlk427007419
    • SIP Gateway referenced by sip_default_gateway stops responding to the SIP OPTIONS Ping requests.
    • Anchor_Hlk427008784_Hlk427008784
    • The callback function passed to the
    • BfvBoardNotify()
    • new BFV APIfunction 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.
    • anchor_Hlk427008579
    • _Hlk427008579
    • SIP OPTIONS Ping requests are transmitted to the SIP Gateway referenced by sip_default_gateway with a periodic interval defined by the
    • "DOWN"
    • “DOWN” interval timer parameter specified in the callctrl.cfg configuration file
    • SIP OPTIONS Ping requests are transmitted to each of the remaining SIP Gateways
    • Anchor_Hlk427008519_Hlk427008519 with a periodic
    • with a periodic interval defined by the
    • "UP"
    • “UP” interval timer parameter.
    • anchor_Hlk427008821
    • _Hlk427008821
    • 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
    • BfvBoardNotify()
    • new BFV APIfunction is invoked and information is passed to it that now indicates that all four of the SIP Gateways are
    • "UP"
    • “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"
    • “UP” interval timer parameter.

 

Architectural Description

...

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):

  • New #defines A new BFV API function will be added to the BFV API for use with the BfvBoardNotify() function introduced for this feature to allow enabling SIP Gateway Status change notifications as well as reporting information regarding the SIP Gateway status changes.No changes to structures in the BFV API are required for this feature request
  • 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.

Performance Change(s):

  • None

 

Documentation Change(s)

  • The documentation for the BfvBoardNotify() function in the Dialogic Brooktrout Bfv APIs Reference Manual will be updated to document 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:

  1. New parameter settings in the callctrl.cfg file to allow users to specify multiple SIP Gateways.
  2. 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"“UP”.
  3. 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"“DOWN”.

 

For each of the parameters listed above, there are four items that will be defined in order to provide CONFIGTOOL.EXE support:

  1. The name of the parameter that is in the callctrl.cfg file.
  2. The long description that goes into the help file for the item.
    (Most of the time the help file is the API documentation)
  3. The short description that goes into the ConfigTool form.
  4. 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)

...

File

Windows

Linux

Solaris*

bostdlld.dll

?(tick)

 

 

brktsip.dll

?(tick)

 

 

bostlib_mt.so

 

?(tick)?

(tick)

brktsip_mt.so

 

?(tick)?

(tick)

*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

...

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"“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" “UP” interval in the callctrl.cfg configuration file. In addition to this, this test verifies that the new BFV API BfvBoardNotify() function 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"“UP”.

 

  • Multiple SIP Gateways Configured: Some Gateways "DOWN"“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" “UP” or “DOWN” intervals in the callctrl.cfg configuration file, as appropriate. In addition to this, this test verifies that the new BFV API BfvBoardNotify() function 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"“UP”.

 

  • Multiple SIP Gateways Configured: All Gateways "DOWN"“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"“DOWN”, SIP OPTIONS Ping requests are successfully transmitted to each of the configured SIP Gateways at the specified "DOWN" “DOWN” interval in the callctrl.cfg configuration file. In addition to this, this test verifies that the new BFV API BfvBoardNotify() function 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

...