(Page 1 of 1 in this chapter) Version

Chapter 6

Using DPNSS Supplementary Features

: 6.1 Introduction
: 6.2 DPNSS Service Supplementary Feature Overview
: 6.3 Sending DPNSS Supplementary Feature Messages
: 6.4 Receiving DPNSS Supplementary Feature Messages

6.1 Introduction

In addition to basic call control, DPNSS supports several supplementary features.
This chapter: Lists the features. Describes how to access them using the CT Access DPNSS service.

6.2 DPNSS Service Supplementary Feature Overview

In addition to basic call control, DPNSS supports several supplementary features. A subset of these features is supported by the CT Access DPNSS service.
The following is a list of supported DPNSS supplementary features: Call Diversion Immediate and Busy Call Diversion on No Reply Diversion Validation Virtual Calls Call Hold Enquiry Call Call Transfer Transit Working Non-Specified Information Text Trunk Identity Add-on/Conference Executive Intrusion
DPNSS features are sent and received using Supplementary Information Strings (SIS). The strings for each supported DPNSS feature are accessed through SIS identifiers declared in the DPNSS service header file (dpndef.h). Each identifier begins with the prefix DPNSIS_ (for example, DPNSIS_CLC_ORD).
The values of SIS identifiers defined in the CT Access DPNSS service are different than the identifier values found in BTNR 188. In your application code, use the DPNSIS_xxx value, and not the SIS identifier code as defined within the BTNR 188 documentation.

6.3 Sending DPNSS Supplementary Feature Messages

Sending of DPNSS feature messages is performed in two phases:

The application prepares a DPNSS Supplementary Information String (SIS) to be sent, by calling dpnSetExtendedArgs with a valid DPNSS service SIS identifier passed as an argument. This causes the identifier to be stacked within a DPNSS service buffer, but it is not sent yet.

To send more than one supplementary feature message at a time, the application calls dpnSetExtendedArgs multiple times, each with a different SIS identifier. The identifiers are stacked within the buffer.

The application calls a call control function: dpnAcceptCall, dpnAnswerCall, dpnRejectCall, dpnPlaceCall, or dpnReleaseCall. At this point, the SISs in the buffer are inserted in the DPNSS message to be sent, and the complete DPNSS message is sent.

If the application does not wish to perform a call control operation while sending a supplementary feature message, it can instead call dpnSendFeatureMessage. This function causes the supplementary feature messages in the buffer to be sent without performing any other operation.
Each time one of the functions is called, the SISs are cleared from the buffer.
The following code sample shows how an application can implement DPNSS features in conjunction with call control: . . // Prepare DPNSS SIS we want to send retStatus = dpnSetExtendedArgs (myCtaHandle, DPNSIS_CLI,calledNumber); retStatus = dpnSetExtendedArgs (myCtaHandle, DPNSIS_CLC_ORD, NULL); // Perform Call control sending prepared SISs retStatus = dpnPlaceCall(myCtaHandle, calledNumber, NULL); // SISs are now cleared . . Note: Not all SISs can be sent with each call control function. SIS identifiers allowed with each call control function are listed with the function in Chapter 5.
The application must avoid sending competing or contradictory SIS identifiers in the same message. For instance, the application must not send DPNSIS_DIVERTING_RNR and DPNSIS_DIVERTING_BSY at the same time because they are contradictory. In such a case, the resulting behavior on the call state is unpredictable. We strongly encourage you to check that your application conforms to the scenario diagrams provided in the sections of BTNR 188 related to each DPNSS feature group.

6.4 Receiving DPNSS Supplementary Feature Messages

A DPNSS feature message consists of one or more Supplementary Information Strings (SIS). They can be received at any time, as long as a call is not in the Disconnected state.
The application can receive SIS during call state changes, notified through ctaWaitEvent with one of the following events:

DPNEVN_INCOMING_CALL

DPNEVN_REMOTE_ALERTING

DPNEVN_CONNECTED

DPNEVN_DISCONNECTED
In addition, the event DPNEVN_INCOMING_INFO is returned when the other party sends a feature message without acting on the call state (i.e., calls dpnSendFeatureMessage or its equivalent).
When one of these events is received, the buffer field within the CTA_EVENT structure points to a list of DPN_RECEIVED_SIS structures. If buffer is NULL, no SIS identifiers have been received.
Each DPN_RECEIVED_SIS structure contains two fields: sisid: A DWORD containing the DPNSS service Supplementary Information String Identifier DPNSIS_xxx (for example, DPNSIS_IPL_RSP). sisparam: An zero-terminated char containing any parameters associated with the SIS identifier. The type and the meaning of the parameters associated with each SIS identifier is given in the BTNR 188 Section 4 Annex 2.
At the end of the SIS identifier list, a DPN_RECEIVED_SIS appears with zero in the sisid field. This provides a way for the application to determine when the end of the list is reached.
The application can compute the number of received SIS by performing the following operation: nb_of_sis_in_the_list = event.size / sizeof(DPN_RECEIVED_SIS);
The DPNSS service allocates a block of memory each time your application receives SISs. After exploring and using this buffer, the application must release it by calling dpnReleaseBuffer, as shown here:

dpnReleaseBuffer(event.buffer);

WARNING:

The application MUST release the SIS buffer after examining its contents, before further SIS information can be received.

WARNING:	The application MUST release the SIS buffer after examining its contents, before further SIS information can be received.

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com