(Page 1 of 17 in this chapter) Version

Chapter 5

Alphabetical Function Reference

5.1 Introduction

5.2 Function Summary

: 5.2.1 Managing Telephony Protocols
: 5.2.2 Sending Extended Arguments and Supplementary Service Messages
: 5.2.3 Call Control
: 5.2.4 Utility Functions

5.3 Alphabetical Function Reference

: dpnAcceptCall 52
: dpnAnswerCall 54
: dpnBlockCalls 56
: dpnGetBoardSlots 58
: dpnGetCallStatus 60
: dpnPlaceCall 62
: dpnRefreshAndGetTrunkStatus 65
: dpnRejectCall 67
: dpnReleaseBuffer 69
: dpnReleaseCall 70
: dpnSendFeatureMessage 72
: dpnSetExtendedArgs 75
: dpnSetTransitActive 77
: dpnStartProtocol 79
: dpnStopProtocol 81
: dpnUnBlockCalls 83

5.1 Introduction

This chapter: Provides a summary of DPNSS service functions according to the tasks they perform. Provides comprehensive descriptions of each function, in alphabetical order.

5.2 Function Summary

This section groups the DPNSS service functions according to the tasks a typical telephony application may perform. Such tasks include: Managing telephony protocols Sending extended arguments and supplementary service messages Call control Utility functions

5.2.1 Managing Telephony Protocols

You must start the DPNSS protocol on each context in order to perform telephony activities.
The DPNSS service provides the following functions to start and stop the DPNSS protocol:

Function

S/A ¹

Description

dpnStartProtocol

A

Starts the DPNSS protocol on a CTA context.

dpnStopProtocol

A

Stops the execution of the DPNSS protocol on a CTA context.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
dpnStartProtocol	A	Starts the DPNSS protocol on a CTA context.
dpnStopProtocol	A	Stops the execution of the DPNSS protocol on a CTA context.

5.2.2 Sending Extended Arguments and Supplementary Service Messages

Call control functions may require extended arguments. Also, DPNSS supplementary service messages can be sent at the same time as a call control function is performed. The DPNSS service provides the following functions to set up extended arguments and DPNSS supplementary information strings:

Function

S/A ¹

Description

dpnReleaseBuffer

S

Releases a DPNSS extended argument buffer previously returned with an event.

dpnSendFeatureMessage

S

Sends a DPNSS end-to-end message using arguments previously stacked using dpnSetExtendedArgs.

dpnSetExtendedArgs

S

Sets up extended arguments or DPNSS supplementary information strings.

dpnSetTransitActive

S

Establishes DPNSS transit working between two CT Access handles.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
dpnReleaseBuffer	S	Releases a DPNSS extended argument buffer previously returned with an event.
dpnSendFeatureMessage	S	Sends a DPNSS end-to-end message using arguments previously stacked using dpnSetExtendedArgs.
dpnSetExtendedArgs	S	Sets up extended arguments or DPNSS supplementary information strings.
dpnSetTransitActive	S	Establishes DPNSS transit working between two CT Access handles.

5.2.3 Call Control

The call control functions are abstractions for establishing and tearing down inbound and outbound calls. These functions relieve the programmer of network signaling and procedures required for connection establishment and maintenance. For more information about call control, refer to Chapter 4.
The DPNSS service provides the following functions to manage call control:

Function

S/A ¹

Description

dpnAcceptCall

A

Accepts an incoming call.

dpnAnswerCall

A

Answers an incoming call.

dpnBlockCalls

A

Blocks subsequent calls.

dpnGetCallStatus

S

Gets status information about the current call.

dpnPlaceCall

A

Places an outbound call.

dpnRefreshAndGetTrunkStatus

S

Obtains the trunk status (similar to dtmRefreshTrunkStatus and dtmGetTrunkStatus in the DTM service).

dpnRejectCall

A

Rejects an incoming call.

dpnReleaseCall

A

Releases an active call.

dpnUnBlockCalls

A

Unblocks previously blocked calls.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
dpnAcceptCall	A	Accepts an incoming call.
dpnAnswerCall	A	Answers an incoming call.
dpnBlockCalls	A	Blocks subsequent calls.
dpnGetCallStatus	S	Gets status information about the current call.
dpnPlaceCall	A	Places an outbound call.
dpnRefreshAndGetTrunkStatus	S	Obtains the trunk status (similar to dtmRefreshTrunkStatus and dtmGetTrunkStatus in the DTM service).
dpnRejectCall	A	Rejects an incoming call.
dpnReleaseCall	A	Releases an active call.
dpnUnBlockCalls	A	Unblocks previously blocked calls.

5.2.4 Utility Functions

The following function retrieves administrative information about your system configuration, or about a specific board:

Function

S/A ¹

Description

dpnGetBoardSlots

S

Retrieves the board's MVIP configuration.

¹ Synchronous or Asynchronous

Function	S/A ¹	Description
dpnGetBoardSlots	S	Retrieves the board's MVIP configuration.

5.3 Alphabetical Function Reference

The following is a comprehensive, alphabetically-ordered reference to the DPNSS service functions. A prototype of each function is shown with the function description and details of all arguments and return values. A typical function description includes:

Prototype
The prototype is shown followed by a listing of the function's arguments. Natural MicroSystems data types include:

WORD
DWORD
INT16
INT32
BYTE

16 bit unsigned
32-bit unsigned
16-bit signed
32-bit signed
8-bit unsigned

If a function argument is a data structure, the complete data structure is defined.

Return Values
The return value for a function is either SUCCESS or an error code. For asynchronous functions, a return value of SUCCESS indicates the function was initiated; subsequent events indicate the status of the operation.
Refer to Appendix B for a listing of all errors returned by DPNSS functions.

Events
If events are listed, the function is asynchronous and is complete when the DONE event is returned. If there are no events listed, the function is synchronous.
Additional information such as reason codes and return values may be provided in the value field of the event.
Refer to Appendix C for details of all DPNSS events. Appendix D contains a listing of reason codes.

Extended Arguments
With each call control function is listed the set of information string (SIS) identifiers that can be sent with the function. The SIS identifiers are stacked for the function call using dpnSetExtendedArgs (see Chapter 6).

Example
Example functions which start with Demo are excerpts taken from demonstration function libraries shipped with the product.
Example functions which start with my are excerpts taken from sample application programs shipped with the product.
The notation /* ... */ indicates additional code which is not shown.

Prototype	The prototype is shown followed by a listing of the function's arguments. Natural MicroSystems data types include:
	`WORD` `DWORD` `INT16` `INT32` `BYTE`	16 bit unsigned 32-bit unsigned 16-bit signed 32-bit signed 8-bit unsigned
	If a function argument is a data structure, the complete data structure is defined.
Return Values	The return value for a function is either `SUCCESS` or an error code. For asynchronous functions, a return value of `SUCCESS` indicates the function was initiated; subsequent events indicate the status of the operation. Refer to Appendix B for a listing of all errors returned by DPNSS functions.
Events	If events are listed, the function is asynchronous and is complete when the `DONE` event is returned. If there are no events listed, the function is synchronous. Additional information such as reason codes and return values may be provided in the `value` field of the event. Refer to Appendix C for details of all DPNSS events. Appendix D contains a listing of reason codes.
Extended Arguments	With each call control function is listed the set of information string (SIS) identifiers that can be sent with the function. The SIS identifiers are stacked for the function call using dpnSetExtendedArgs (see Chapter 6).
Example	Example functions which start with `Demo` are excerpts taken from demonstration function libraries shipped with the product. Example functions which start with `my` are excerpts taken from sample application programs shipped with the product. The notation `/* ... */` indicates additional code which is not shown.

(Page 1 of 17 in this chapter) Version

tech_support@nmss.com

Chapter 5

Alphabetical Function Reference

5.1 Introduction

5.2 Function Summary

5.2.1 Managing Telephony Protocols

5.2.2 Sending Extended Arguments and Supplementary Service Messages

5.2.3 Call Control

5.2.4 Utility Functions

5.3 Alphabetical Function Reference

Prototype

Return Values

Events

Extended Arguments

Example