Specifications

ManualsBrandsDialogic ManualsTable Top Game05-0867-005 Table Top Game

ISDN Software Reference

for Linux and Windows

05-0867-005

Summary of content (476 pages)

PAGE 2
COPYRIGHT NOTICE All contents of this document are subject to change without notice and do not represent a commitment on the part of Dialogic Corporation. Every effort is made to ensure the accuracy of this information. However, due to ongoing product improvements and revisions, Dialogic Corporation cannot guarantee the accuracy of this material, nor can it accept responsibility for errors or omissions. No warranties of any nature are extended by the information contained in these copyrighted materials.
PAGE 3
Table of Contents 1. How To Use This Guide .................................................................................. 1 1.1. Products Covered by this Guide ..................................................................... 1 1.2. Organization of this Guide.............................................................................. 1 2. Introduction to Dialogic ISDN Products ....................................................... 3 2.1. The Basic Rate Interface...................................
PAGE 4
ISDN Software Reference for Linux and Windows cc_CauseValue( ) - retrieves the error/cause code of a failure ............................. 67 cc_Close( ) - closes a previously opened line device ............................................ 70 cc_CRN2LineDev( ) - matches a CRN to its line device handle .......................... 73 cc_DropCall( ) - allows the application to disconnect a call ................................. 75 cc_GetANI( ) - retrieves Automatic Number Identification (ANI) information ...
PAGE 5
Table of Contents cc_Restart( ) - resets the channel to Null state .................................................... 194 cc_ResultMsg( ) - interprets the function return code......................................... 198 cc_ResultValue( ) - gets an error/cause code ...................................................... 201 cc_RetrieveAck( ) - accept a request to retrieve a call from hold ....................... 204 cc_RetrieveCall( ) - retrieve a call from the Hold state .................................
PAGE 6
ISDN Software Reference for Linux and Windows 6.10. PARM_INFO ........................................................................................... 316 6.11. SPID_BLK ............................................................................................... 316 6.12. TERM_BLK ............................................................................................. 317 6.13. TERM_NACK_BLK ................................................................................ 319 6.14. ToneParm .....
PAGE 7
Table of Contents BRI Channel Initialization and Start Up (Network Side) ................................... 369 PRI Channel Initialization and Start Up ............................................................. 370 Normal Call Establishment and Termination...................................................... 371 Network initiated call (inbound call) ............................................................ 371 Network terminated call..................................................................
PAGE 8
ISDN Software Reference for Linux and Windows Information Elements for cc_GetCallInfo( ) and cc_GetSigInfo( ) .................... 425 Intrusion IE: .................................................................................................. 425 Diversion IE:................................................................................................. 425 Diversion Validation IE: ............................................................................... 426 Transit IE: .......................
PAGE 9
List of Tables Table 1. ISDN Protocols...................................................................................... 11 Table 2. Call Control States................................................................................. 16 Table 3. Inbound Call Set-Up (Asynchronous Example).................................... 19 Table 4. Outbound Call Set-up (Asynchronous Example).................................. 20 Table 5. Inbound Call Set-Up (Synchronous Example)......................................
PAGE 10
ISDN Software Reference for Linux and Windows Table 37. Table 38. Table 39. Table 40. Table 41. Table 42. Table 43. Table 44. Table 45. Table 46. Table 47. Table 48. Table 49. Table 50. Table 51. Table 52. Table 53. Table 54. Table 55. Table 56. Table 57. Table 58. Table 59. Table 60. x MAKECALL_BLK Parameter ID Definitions .................................. 307 NONCRN_BLK Field Descriptions .................................................. 315 PARM_INFO Field Descriptions ..............................
PAGE 11
List of Figures Figure 1. Layer 2 Frame (D Channel).................................................................. 14 Figure 2. Layer 3 Frame (D Channel).................................................................. 15 Figure 3. Asynchronous Call Establishment Process .......................................... 18 Figure 4. Synchronous Call Establishment Process ............................................ 21 Figure 5. Asynchronous Call Disconnect or Failure Process ..............................
PAGE 12
PAGE 13
1. How To Use This Guide This ISDN Software Reference is intended for users who have purchased a Dialogic board that provides ISDN Primary Rate or Basic Rate connectivity and a Dialogic system software and SDK release for either LINUX or Windows. Installation instructions for the ISDN Package software are provided in the release notes or for system software and SDK releases, in the Getting Started booklet in the CD-ROM jewel case.
PAGE 14
ISDN Software Reference for Linux and Windows Chapter 6 provides descriptions of the data structures used by various ISDN library functions. Chapter 7 describes the events and errors returned by Dialogic ISDN library functions. Chapter 8 provides guidelines for developing ISDN applications.
PAGE 15
2. Introduction to Dialogic ISDN Products The Integrated Services Digital Network (ISDN) is a collection of internationally accepted standards for defining interfaces and operation of digital switching equipment for the transmission of voice, data, and signaling. ISDN has the following characteristics and advantages: • ISDN makes all transmission circuits end-to-end digital. • ISDN adopts a standard out-of-band signaling system. • ISDN brings significantly more bandwidth to the desktop.
PAGE 16
ISDN Software Reference for Linux and Windows station set device to and from the SCbus. BRI/SC boards can be used in either a Windows or a LINUX operating environment. The Dialogic BRI/SC protocol implementations comply with the North American standard ISDN BRI, Euro-ISDN protocol for BRI, and the INS64 standard used in Japan. See Section 2.3. Dialogic ISDN Protocol Support for a listing of currently supported BRI protocols.
PAGE 17
2. Introduction to Dialogic ISDN Products Both the BRI/SC and the BRI/2 boards provide access to ISDN Layer 3 Supplemental Services. These services can be divided into two categories: • Hold and Retrieve allows the application to place calls on hold, to retrieve held calls and to respond to requests to hold or retrieve held calls using the following Dialogic functions: cc_HoldCall( ), cc_RetrieveCall( ), cc_HoldAck( ), cc_HoldRej( ), cc_RetrieveAck( ), and cc_RetrieveRej( ).
PAGE 18
ISDN Software Reference for Linux and Windows This means that the BRI/2 may be used by applications that use the standard networking APIs that are part of the Windows operating system. NDIS supports Remote Access Service (RAS) and Point-to-Point Protocol (PPP): • Remote Access Service (RAS) - RAS is enabled via NDIS and allows users to interact with the service selections provided by the specified dial-up networking setup.
PAGE 19
2. Introduction to Dialogic ISDN Products • Multiple D Channel Configuration - this feature allows the D channel of each line to be configured at any time, and as many times as needed. The application can configure and reconfigure the protocol for each station interface, allowing different protocols to be run on different stations simultaneously.
PAGE 20
ISDN Software Reference for Linux and Windows The T-1 protocol implementations comply with the North American standard ISDN Primary Rate and the INS-1500 standard used in Japan. In North America and Japan, the Primary Rate includes 23 voice/data channels (B channels) and one signaling channel (D channel). The E-1 protocol implementations comply with the E-1 Primary Rate interface protocol.
PAGE 21
2. Introduction to Dialogic ISDN Products • Vari-A-Bill. A flexible billing option enabling a customer to modify the charge for a call while the call is in a stable state (for example, between answer and disconnect). This feature is available from the AT&T network only. • ANI-on-demand. Allows the user to request a caller ID number to identify the origin of the call, when necessary. • Non-facility Associated Signaling (NFAS) . Provides support for multiple ISDN spans from a single D channel.
PAGE 22
ISDN Software Reference for Linux and Windows The following sections contain examples of typical applications for terminate and drop-and-insert configurations. Terminate Configuration Applications Dialogic ISDN products in a terminate configuration with one or more resource boards (for example, voice boards) allow for the development of a variety of applications, such as the following: • Audiotex applications allow users to retrieve and listen to pre-recorded messages over the telephone.
PAGE 23
2. Introduction to Dialogic ISDN Products • Operator Services applications are able to automate large numbers of telephone calls that require some kind of caller assistance. Such applications include, but are not limited to, partially automated directory assistance, calling card voice prompting, and collect calls. • Telemarketing applications depend on a specific event/transaction.
PAGE 24
ISDN Software Reference for Linux and Windows NOTES: 1. Only one protocol may be configured per digital network interface at a given time. 2. Refer to the package release notes or system software catalog for updated protocol support information. Also, refer to the Dialogic Worldview website at http://www.dialogic.com and to the Dialogic FirstCall™ Info Server website at http://support.dialogic.com. DPNSS and Q.SIG are ISDN PRI E-1 protocols that are used to pass calls transparently between PBXs.
PAGE 25
3. ISDN Technology Overview The Integrated Services Digital Network (ISDN) is a digital communications network capable of carrying all forms (voice, computer, and facsimile) of digitized data between switched endpoints. This chapter provides an overview of ISDN technology, including the signaling method used to transmit data, framing and framing formats, and ISDN call control states. 3.1. Signaling The digital data stream contains two kinds of information: user data and signaling data.
PAGE 26
ISDN Software Reference for Linux and Windows 3.2. Framing Voice data from each time slot in a configuration is routed to a separate B channel. The signaling information for all B channels is routed to the D channel of the device. Information from the B and D channels is transmitted in frames. A single frame contains information from each of the channels, providing a “snapshot” of the data being transmitted at any given time. The frames contain the eight bits of information about each time slot or channel.
PAGE 27
3. ISDN Technology Overview Layer 2 Flag Layer 3 Address Protocol Discriminator Control Information Call Reference Message Type Value FCS Flag Information Elements Figure 2.
PAGE 28
ISDN Software Reference for Linux and Windows Table 2. Call Control States Call State Description Accepted An indication to the network that the incoming call has been accepted, but has not been connected to the end user. (Most voice applications do not need this.) Alerting The destination is reached and the phone is ringing. This state may be reported to the application or masked depending on the application directive. Connected An incoming or outgoing call is established.
PAGE 29
3. ISDN Technology Overview • In general, in asynchronous mode, events trigger the transitions between call states. For example, the termination event, CCEV_ANSWERED, causes the call state to change to the Connected state. Likewise, the unsolicited event, CCEV_DISCONNECTED, causes the call state to change to the Disconnected state. • Synchronous functions return at the successful completion of the function or if the function fails.
PAGE 30
ISDN Software Reference for Linux and Windows Inbound Outbound Null cc_WaitCall( ) CCEV_OFFERED Offered cc_MakeCall( ) cc_SetEvtMsk( ) (Maskable) CCEV_ALERTING cc_AcceptCall( ) CCEV_ACCEPT Accepted Dialing Alerting cc_AnswerCall( ) CCEV_ANSWERED CCEV_CONNECTED cc_AnswerCall( ) CCEV_ANSWER ED CCEV_CONNECTED Connected LEGEND cc_Function( ) State0 CCEV_EVENT State1 State2 Figure 3.
PAGE 31
3. ISDN Technology Overview Table 3. Inbound Call Set-Up (Asynchronous Example) Function/Event Action/Description cc_WaitCall( ) Issued once after line device opened with cc_Open( ).
PAGE 32
ISDN Software Reference for Linux and Windows Table 4. Outbound Call Set-up (Asynchronous Example) Function/Event Action/Description cc_MakeCall( ) Requests a connection using a specified line device. A CRN is assigned and returned immediately; call is transitioned to the Dialing state. CCEV_CONNECTED event sent if call is connected; otherwise a CCEV_TASKFAIL event is sent. *cc_SetEvtMsk( ) Specifies the events enabled or disabled for a specified line device.
PAGE 33
3. ISDN Technology Overview Null Inbound cc_WaitCall( ) Outbound cc_MakeCall( ) cc_MakeCall( ) in progress Offered CCEV_ALERTING (Maskable) cc_AcceptCall( ) Accepted cc_AnswerCall( ) cc_AnswerCall( ) completion of cc_makeCall( ) Connected LEGEND cc_Function( ) State0 CCEV_EVENT State1 State2 Figure 4. Synchronous Call Establishment Process Table 5 provides an example of a simple inbound call using the synchronous call establishment process.
PAGE 34
ISDN Software Reference for Linux and Windows Table 5. Inbound Call Set-Up (Synchronous Example) Function Action/Description cc_WaitCall( ) Enables notification of an incoming call after line device opened with cc_Open( ). Call is in OFFERED state. *cc_GetANI( ) Request ANI information *cc_GetDNIS( ) Retrieves DNIS digits received from the network.
PAGE 35
3. ISDN Technology Overview Table 6. Outbound Call Set-up (Synchronous Example) Function/Event Action/Description cc_MakeCall( ) Requests a connection using a specified line device; a CRN is assigned and returned immediately. *CCEV_ALERTING Remote end was reached but a connection has not been established none When the cc_MakeCall( ) function successfully completes, the call is in the Connected state. NOTES: 1. * = Maskable events 2. There are no termination events in synchronous mode. 3.3.3.
PAGE 36
ISDN Software Reference for Linux and Windows All Other CC States CCEV_DISCONNECTED cc_DropCall( ) CCEV_DROPCALL Idle cc_DropCall( ) CCEV_DROPCALL Disconnected cc_ReleaseCall( ) Null Figure 5. Asynchronous Call Disconnect or Failure Process Table 7 presents an asynchronous call termination scenario. The item denoted by an asterisk (*) is an optional function call. For more detailed call scenarios, see Appendix A.
PAGE 37
3. ISDN Technology Overview Table 7. Call Termination (Asynchronous Example) Function/Event Action/Description CCEV_DISCONNECTED Unsolicited event generated when call is terminated by network; initiates transition to Disconnected state. cc_DropCall( ) Disconnects call specified by CRN.
PAGE 38
ISDN Software Reference for Linux and Windows Terminated by Application Terminated by Network All Other CC States CCEV_DISCONNECTED cc_DropCall( ) cc_DropCall( ) Idle Disconnected cc_ReleaseCall( ) Null Figure 6. Synchronous Call Disconnect or Failure Process Table 8 presents a synchronous call termination scenario. The item denoted by an asterisk (*) is an optional function call. For more detailed call scenarios, see Appendix A.
PAGE 39
3. ISDN Technology Overview Table 8. Call Termination (Synchronous Example) Function/Event Action/Description CCEV_DISCONNECTED Unsolicited event generated when call is terminated by network; initiates transition to Disconnected state. cc_DropCall( ) Disconnects call specified by CRN. Initiates transition to Idle state. *cc_GetBilling( ) Retrieves billing information cc_ReleaseCall( ) Issued to release all resources used for call; network port is ready to receive next call.
PAGE 40
PAGE 41
4. ISDN Function Overview This chapter provides the following information about the Dialogic ISDN library functions used to interact with the network in an ISDN environment: • ISDN function categories • a brief description of each ISDN library function • the ISDN technologies supported for each function For a complete description of each function, see Chapter 5. ISDN Function Reference in this guide. 4.1.
PAGE 42
ISDN Software Reference for Linux and Windows • 30 retrieve calls from the Hold state, and to accept and reject hold requests and retrieve-from-hold requests (see Table 14). Global Tone Generation - Set, change, and control the In-band tones for BRI/SC protocols (see Table 15).
PAGE 43
4. ISDN Function Overview Table 9.
PAGE 44
ISDN Software Reference for Linux and Windows Table 10.
PAGE 45
4.
PAGE 46
ISDN Software Reference for Linux and Windows Table 11.
PAGE 47
4. ISDN Function Overview Table 12.
PAGE 48
ISDN Software Reference for Linux and Windows cc_SetParmEx( ) sets parameters requiring variable data to be passed down to the firmware cc_SetUsrAttr( ) sets the user attribute 36
PAGE 49
4.
PAGE 50
ISDN Software Reference for Linux and Windows Table 13. Data Link Layer Handling Functions Function Description cc_GetFrame( ) retrieves the frame received by the application cc_SndFrame( ) sends a frame to the data link layer NOTE: These functions are available only when Layer 2 access is configured.
PAGE 51
4. ISDN Function Overview Table 14.
PAGE 52
ISDN Software Reference for Linux and Windows Table 15. Global Tone Generation Functions Function Description cc_PlayTone( ) plays a user-defined tone cc_StopTone( ) stops the tone that is currently playing on a channel cc_ToneRedefine( ) redefines the tones in the firmware tone template table 4.2. API Functions and Supported ISDN Technologies The following table lists all of the ISDN API functions and indicates which functions can be used in each of the supported ISDN technologies. Chapter 5.
PAGE 53
4. ISDN Function Overview Table 16. ISDN API Functions and Supported Technologies ISDN API Functions PRI BRI/2 BRI/SC DPNSS Q.
PAGE 54
ISDN Software Reference for Linux and Windows ISDN API Functions PRI BRI/2 * BRI/SC * Q.
PAGE 55
4. ISDN Function Overview ISDN API Functions PRI BRI/2 BRI/SC DPNSS Q.
PAGE 56
ISDN Software Reference for Linux and Windows ISDN API Functions PRI BRI/2 * * * cc_TermRegisterResponse( ) * cc_ToneRedefine( ) * cc_WaitCall( ) 44 DPNSS Q.
PAGE 57
5. ISDN Function Reference The Dialogic ISDN API functions are application-specific programming interfaces that provide standard software interrupts, calls, and data formats for developing ISDN applications. This chapter provides a detailed description of each ISDN API function included in the cclib.h file.
PAGE 58
ISDN Software Reference for Linux and Windows Table 17. ISDN Function Description Format Section Provides: Function Header the function name and briefly states its purpose. Function Overview an overview of the function, including the following: • Name Defines the function name and function syntax using standard C language syntax. • Inputs Lists all input parameters using standard C language syntax. • Returns Lists all returns of the function.
PAGE 59
5. ISDN Function Reference 5.2. Programming Conventions The Dialogic ISDN library functions use the following format: cc_function(reference, parameter1, parameter2, parameterN, mode) Where: • cc_function is the function name • reference is an input field that directs the function to a specific line device or call when the reference is a CRN or a line device handle (see Section 5.3.
PAGE 60
ISDN Software Reference for Linux and Windows A call reference value (CRV), which conforms to the Q.931 standard, is a network-assigned value that is used to identify a call on a specific line device. The CRV is transmitted over the network and maintained by the ISDN firmware. The ISDN firmware maintains a table to match the host-assigned CRN and the network-associated CRV. Use the cc_GetCRN( ) function to obtain the CRN. The CRV for a particular CRN can be obtained by using the cc_GetNetCRV( ) function.
PAGE 61
5. ISDN Function Reference value <0 is returned along with the CCEV_TASKFAIL event. However, when an asynchronous function call fails, a result value of 0 (indicating success) can be returned along with the CCEV_TASKFAIL termination event, which indicates failure. This means that the library has accepted the request that was sent to the firmware, but at that moment, the request cannot be fulfilled due to specific circumstances or conditions.
PAGE 62
cc_AcceptCall( ) Name: Inputs: int cc_AcceptCall(crn, rings, mode) CRN crn • call reference number int rings • number of rings before return unsigned long mode • synchronous or asynchronous 0 on success < 0 on failure cclib.h Optional call handling synchronous or asynchronous BRI/2; BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! responds to an incoming call request Description The cc_AcceptCall( ) function responds to an incoming call request.
PAGE 63
responds to an incoming call request • ! cc_AcceptCall( ) CCEV_TASKFAIL - indicates that a request/message was rejected by the firmware. Typically, this event is triggered by an incorrect function call during the call. Cautions None ! Example #include #include #include #include #include #include "srllib.h" "dtilib.h" "cclib.
PAGE 64
cc_AcceptCall( ) responds to an incoming call request int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code.
PAGE 65
accepts a connection request from the remote end Name: Inputs: Returns: Includes: Category Mode: Technology: ! cc_AnswerCall( ) int cc_AnswerCall(crn, rings, mode) CRN crn • call reference number int rings • number of rings before return unsigned long mode • synchronous or asynchronous 0 on success < 0 on failure cclib.
PAGE 66
cc_AnswerCall( ) ! • • ! accepts a connection request from the remote end Termination Events CCEV_ANSWERED - indicates that a CONNECT message has been sent to the network. CCEV_TASKFAIL - indicates that a request/message was rejected by the firmware. Typically, this event is triggered by an incorrect function call during the call. Cautions This function is called only after an inbound call has been detected. ! Example #include #include #include #include #include #include
PAGE 67
accepts a connection request from the remote end cc_AnswerCall( ) } int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure.
PAGE 68
cc_CallAck( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! send the first response to an incoming call int cc_CallAck(crn, newLineDev, msg_id) CRN crn • call reference number LINEDEV newLineDev • new line device handle int msg_id • message id 0 on success < 0 on failure cclib.
PAGE 69
send the first response to an incoming call • 2. ! • • ! cc_CallAck( ) cc_CallAck(crn, newLineDev, CALL_PROCEEDING) if a new B channel is desired. The received setup message contains insufficient destination information.
PAGE 70
cc_CallAck( ) send the first response to an incoming call * The cc_CallAck() function needs to be called after * cc_WaitCall and before cc_CallProgress(), cc_AcceptCall() * and cc_AnswerCall() */ if ( cc_CallAck(crn,0,CALL_PROCEEDING) < 0 ) callfail(crn); printf("Accepting call\n"); if ( cc_AcceptCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); . . . . .
PAGE 71
send the first response to an incoming call cc_CallAck( ) Error codes from the cc_CallAck( ) function include the following: Error Code Description E_ISBADIF | ERR_ISDN_LIB Bad interface number E_ISBADTS | ERR_ISDN_LIB Bad time slot ! • See Also cc_SetEvtMsk( ) 59
PAGE 72
cc_CallProgress( ) Name: Inputs: int cc_CallProgress(crn, indicator) CRN crn • call reference number int indicator • progress indicator 0 on success < 0 on failure cclib.h Optional call handling synchronous BRI/2; BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! sends a PROGRESS message to the network Description The cc_CallProgress( ) function sends a PROGRESS message to the network.
PAGE 73
sends a PROGRESS message to the network ! cc_CallProgress( ) Example #include #include #include #include #include #include "srllib.h" "dtilib.h" "cclib.h" /* For Windows applications only */ void main() { LINEDEV devhdl = 0; CRN crn = 0; char *devname = "dtiB1T1"; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } printf("Waiting for call\n"); if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(de
PAGE 74
cc_CallProgress( ) sends a PROGRESS message to the network } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h and isdncmd.h.
PAGE 75
retrieves the state of a call Name: Inputs: int cc_CallState(crn, state_buf) CRN crn • call reference number int* state_buf • pointer to requested state number 0 on success < 0 on failure cclib.h System tools synchronous BRI/2; BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! cc_CallState( ) Description The cc_CallState( ) function retrieves the state of a call associated with a particular call reference number (CRN).
PAGE 76
cc_CallState( ) Parameter retrieves the state of a call Description • CCST_NULL - The call was released; the call is in the Null state. • CCST_OFFERED - An inbound call was received; the call is in the Offered state. ! Cautions Due to normal process latency time, the state value acquired may not reflect the current state of the call. The state retrieved will be associated with the last event received by the application. ! Example #include #include #include #include #include #include
PAGE 77
retrieves the state of a call cc_CallState( ) { if ( cc_DropCall(crn, NORMAL_CLEARING, EV_SYNC) < 0 ) callfail(crn); if ( cc_ReleaseCall(crn) < 0 ) callfail(crn); exit(1); } } . . . . . /* Drop the call */ if ( cc_DropCall(crn, NORMAL_CLEARING, EV_SYNC) < 0 ) callfail(crn); if ( cc_ReleaseCall(crn) < 0 ) callfail(crn); /* Close the device */ if ( cc_Close( devhdl ) < 0 ) printf("Error closing device, errno = %d\n", errno); } int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } i
PAGE 78
cc_CallState( ) retrieves the state of a call Error Code Description ERR_ISDN_LIB | E_ISBADIF Bad interface number ERR_ISDN_LIB | E_ISBADTS Bad time slot ERR_ISDN_LIB | E_ISCALLRELATED Call related event ! See Also None 66
PAGE 79
retrieves the error/cause code of a failure Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_CauseValue( ) int cc_CauseValue(linedev) LINEDEV linedev • line device handle cause value code cclib.h System tools synchronous BRI/2; BRI/SC; PRI (all protocols) Description The cc_CauseValue( ) function retrieves the error/cause code of a failure on a given device when a function returns a -1.
PAGE 80
cc_CauseValue( ) ! retrieves the error/cause code of a failure Cautions None ! Example #include #include #include #include #include #include "srllib.h" "dtilib.h" "cclib.h" /* For Windows applications only */ void main() { LINEDEV devhdl = 0; CRN crn = 0; char *devname = "dtiB1T1"; int state; int reason; char *msg; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } printf("Waiting for call\n"); if ( cc_WaitCal
PAGE 81
retrieves the error/cause code of a failure cc_CauseValue( ) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors The cc_CauseValue( ) function returns -1 when there is no error/cause code available for the specified line device. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 82
cc_Close( ) closes a previously opened line device Name: Inputs: Returns: int cc_Close(linedev) LINEDEV linedev • line device handle 0 on success < 0 on failure cclib.h System control synchronous BRI/2; BRI/SC; PRI (all protocols) Includes: Category: Mode: Technology: ! Description The cc_Close( ) function closes a previously opened line device. The application can no longer access the device via the specified line device handle after this function is called.
PAGE 83
closes a previously opened line device cc_Close( ) printf("Error opening device: errno = %d\n", errno); exit(1); } printf("Waiting for call\n"); if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); . . . . .
PAGE 84
cc_Close( ) ! • • 72 See Also cc_Open( ) cc_CallState( ) closes a previously opened line device
PAGE 85
matches a CRN to its line device handle Name: Inputs: int cc_CRN2LineDev(crn, linedevp) CRN crn • call reference number LINEDEV *linedevp • pointer to a buffer to store the line device handle 0 on success < 0 on failure cclib.h System control synchronous BRI/2; BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! cc_CRN2LineDev( ) Description The cc_CRN2LineDev( ) function is a utility function that matches a CRN to its line device handle.
PAGE 86
cc_CRN2LineDev( ) matches a CRN to its line device handle if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } printf("Waiting for call\n"); if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); . . . . .
PAGE 87
allows the application to disconnect a call Name: Inputs: int cc_DropCall(crn, cause, mode) CRN crn • call reference number int cause • reason for dropping the call unsigned long mode • synchronous or asynchronous 0 on success < 0 on failure cclib.
PAGE 88
cc_DropCall( ) allows the application to disconnect a call Value Description CHAN_DOES_NOT_EXIST Channel does not exist CHAN_NOT_IMPLEMENTED Channel type not implemented CHANNEL_UNACCEPTABLE Channel is unacceptable DEST_OUT_OF_ORDER Destination out of order FACILITY_NOT_IMPLEMENT Requested facility not implemented FACILITY_NOT_SUBSCRIBED Facility not subscribed FACILITY_REJECTED Facility rejected INCOMPATIBLE_DEST Incompatible destination INCOMING_CALL_BARRED Incoming call barred INTER
PAGE 89
allows the application to disconnect a call cc_DropCall( ) Value Description NO_ROUTE Network has no route to the specified transient network, or the network has no route to the destination.
PAGE 90
cc_DropCall( ) ! allows the application to disconnect a call Cautions In order to release the call reference number, this function must be followed by a cc_ReleaseCall( ) to prevent a blocking condition or memory allocation errors. ! Example #include #include #include #include #include #include "srllib.h" "dtilib.h" "cclib.
PAGE 91
allows the application to disconnect a call cc_DropCall( ) char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 92
cc_GetANI( ) retrieves Automatic Number Identification (ANI) information Name: Inputs: int cc_GetANI(crn, ani_buf) CRN crn • call reference number char *ani_buf • pointer to buffer where ANI will be stored 0 on success < 0 on failure cclib.
PAGE 93
retrieves Automatic Number Identification (ANI) information CRN char char cc_GetANI( ) crn = 0; *devname = "dtiB1T1"; ani_buf[CC_ADDRSIZE]; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); printf("Retrieving ANI\n"); if ( cc_GetANI(crn, ani_buf) < 0 ) callfail(crn); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); . . . . .
PAGE 94
cc_GetANI( ) retrieves Automatic Number Identification (ANI) information Error Code Description E_ISBADCRN | ERR_ISDN_LIB Bad call reference number E_ISBADPAR | ERR_ISDN_LIB Bad input parameter E_ISNOINFOBUF | ERR_ISDN_LIB Information buffer not ready ! • • • 82 See Also cc_WaitCall( ) cc_ReqANI( ) cc_MakeCall( )
PAGE 95
retrieves the status of the B channel Name: Inputs: int cc_GetBChanState(linedev, bchstate_buf) LINEDEV linedev • line device handle for the B channel int *bchstate_buf • pointer to the location where the B channel state value is stored 0 on success < 0 on failure cclib.h System tools synchronous BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! cc_GetBChanState( ) Description The cc_GetBChanState( ) function retrieves the status of the B channel at any time.
PAGE 96
cc_GetBChanState( ) retrieves the status of the B channel { LINEDEV CRN char int devhdl = 0; crn = 0; *devname = "dtiB1T1"; bchanstate; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } /* * Using cc_GetBChanState() to get the current * B channel status. */ if ( cc_GetBChanState(devhdl,&bchanstate) < 0 ) procdevfail(devhdl); else if ( bchanstate != ISDN_IN_SERVICE ) { printf("B Channel is not in service...\n"); if ( cc_Close( devhdl ) < 0 ) print
PAGE 97
retrieves the status of the B channel cc_GetBChanState( ) } ! Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 98
cc_GetBilling( ) gets the call charge information Name: Inputs: int cc_GetBilling(crn, billing_buf) CRN crn • call reference number char *billing_buf • pointer to billing string buffer 0 on success < 0 on failure cclib.h Optional call handling synchronous PRI (4ESS only) Returns: Includes: Category: Mode: Technology: ! Description The cc_GetBilling( ) function gets the call charge information associated with the specified call. The billing information is in a NULL terminated ASCII string.
PAGE 99
gets the call charge information cc_GetBilling( ) #include "cclib.h" void main() { LINEDEV devhdl = 0; CRN crn = 0; char *devname = "dtiB1T1"; char billingbuf[CC_BILLSIZE]; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } printf("Making call\n"); if ( cc_MakeCall(devhdl,&crn,"9933000",NULL,30,EV_SYNC) < 0 ) procdevfail(devhdl); . . . . .
PAGE 100
cc_GetBilling( ) ! gets the call charge information Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 101
gets the information elements associated with the CRN Name: Inputs: cc_GetCallInfo(crn, info_id, valuep) CRN crn • call reference number int info_id • call information identifier char *valuep • pointer to information buffer 0 on success < 0 on failure cclib.h isdnlib.
PAGE 102
cc_GetCallInfo( ) gets the information elements associated with the CRN Table 19. cc_GetCallInfo( ) Info_ID Definitions info_id Definition U_IES Information Elements (IEs) in CCITT format. The cc_GetCallInfo( ) function retrieves all unprocessed IEs in CCITT format. Be sure to allocate enough memory (up to 256 bytes) to hold the retrieved IEs. The IEs are returned as raw data and must be parsed and interpreted by the application. Use IE_BLK to retrieve the unprocessed IEs.
PAGE 103
gets the information elements associated with the CRN cc_GetCallInfo( ) void main() { LINEDEV devhdl = 0; CRN crn = 0; char *devname = "dtiB1T1"; char dnis_buf[CC_ADDRSIZE]; char infbuf[MAXLEN_IEDATA]; /* buffer raw information in CCITT format */ int i; /* for loop counter to print out information buffer contents */ /* open the ISDN line device */ if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } printf("Waiting for call\n"); if ( cc_WaitCall(devhd
PAGE 104
cc_GetCallInfo( ) gets the information elements associated with the CRN reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 105
retrieves the connection endpoint suffix Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_GetCES( ) int cc_GetCES(cesp, evtdatap) char *cesp • pointer to connection endpoint suffix buffer void *evtdatap • pointer to an event block 0 on success < 0 on failure cclib.h System tools synchronous BRI/SC Description The cc_GetCES( ) function retrieves the connection endpoint suffix (CES) associated with the CCEV_D_CHAN_STATUS event received from the event queue.
PAGE 106
cc_GetCES( ) retrieves the connection endpoint suffix long EventHandler(event) { int rc; L2_BLK frame; unsigned int resultValue; unsigned char sapi, ces; int device; void *datap; device = sr_getevtdev(); datap = sr_getevtdatap(); ...
PAGE 107
retrieves the connection endpoint suffix ! cc_GetCES( ) Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 108
cc_GetChanId( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! gets the last channel information cc_GetChanId(crn, chanId) CRN crn • call reference number CHAN_ID *chanId • pointer to channel ID structure 0 on success < 0 on failure cclib.h Optional call handling synchronous BRI/2; BRI/SC Description The cc_GetChanId( ) function gets the last channel information received from messages for the specified CRN.
PAGE 109
gets the last channel information cc_GetChanId( ) void main( ) { LINEDEV boarddev; . . if ( cc_Open ( &boarddev, “dtiB1”, 0 ) < 0 ) { printf (“Error opening board device: errno = %d\n”, errno); exit (1); } . . sr_setparm ( SRL_DEVICE, SR_MODELTYPE, &sr_mode ); sr_enbhdlr ( EV_ANYDEV, EV_ANYEVT, event_handler ); if ( cc_WaitCall (boarddev, &normal_crn, NULL, -1, EV_ASYNC) < 0 ) procdevfail (linedev); . . .
PAGE 110
cc_GetChanId( ) gets the last channel information { if( cc_DropCall (crn, NORMAL_CLEARING, EV_ASYNC) < 0 ) callfail(crn); } break; case DCHAN_IND: /* non circuit switched calls */ /* Ignore this call */ break; default: /* normal call */ normal_crn = crn; switch(chanId.
PAGE 111
gets the last channel information cc_GetChanId( ) cc_GetChanId(crn, &chanId); if( cc_AcceptCall(callwaiting_crn, num_rings, EV_ASYNC) < 0 ) callfail(crn); } break; case CCEV_RELEASE: if(active_crn == crn) active_crn = 0; else if(waitingcall_crn == crn) waitingcall_crn = 0; break; . . .
PAGE 112
cc_GetChanId( ) ! See Also • • 100 cc_AcceptCall( ) cc_MakeCall( ) gets the last channel information
PAGE 113
retrieves the call reference number for the event Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_GetCRN( ) int cc_GetCRN(crnp, evtdatap) CRN *crnp • pointer to the CRN void *evtdatap • pointer to an event block 0 on success < 0 on failure cclib.h System tools synchronous BRI/2; BRI/SC; PRI (all protocols) Description The cc_GetCRN( ) function retrieves the call reference number for the event in the event queue pointed to by evtdatap.
PAGE 114
cc_GetCRN( ) retrieves the call reference number for the event #include "cclib.h" main() { . . . . if ( sr_enbhdlr( devhdl,CCEV_DISCONNECTED,discCallHdlr ) < 0 ) { printf( "dtiEnable for DISCONNECT failed: %s\n", ATDV_ERRMSGP( SRL_DEVICE ) ); return( 1 ); } . . . .
PAGE 115
retrieves the call reference number for the event cc_GetCRN( ) Typically, a < 0 return code for the cc_GetCRN( ) function indicates that the function reference (the device number) is not valid for the function call.
PAGE 116
cc_GetDChanState( ) Name: Reference: Returns: Includes: Category: Mode: Technology: ! retrieves the status of the D channel int cc_GetDChanState(boarddev, dchstate_buf) LINEDEV boarddev • line device handle for the D channel board int *dchstate_buf • pointer to the location where the requested D channel state value is stored 0 on success < 0 on failure cclib.h System tools synchronous PRI (excluding DPNSS and Q.
PAGE 117
retrieves the status of the D channel cc_GetDChanState( ) void main() { short devhdl; /* device handle for D channel */ int dchanstate; /* the space for cc_GetDChanState output */ . . . if ( cc_Open(devhdl,"dtiB1T1", 0 ) < 0 ) exit(1); */ * Using cc_GetDChanState() to get the * layer 2 status. */ if ( cc_GetDChanState(devhdl,&dchanstate) < 0 ) procdevfail(devhdl); else if ( dchanstate != DATA_LINK_UP ) { printf("D Channel link is inoperable...\n"); exit(1); } /* The layer 2 is OK, continue the program.
PAGE 118
cc_GetDChanState( ) retrieves the status of the D channel Error Code Description ERR_ISDN_LIB | E_ISBADIF Bad interface number ! See Also • 106 cc_SetDChanCfg( )
PAGE 119
retrieves the configuration of a logical link Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_GetDLinkCfg( ) int cc_GetDLinkCfg(bdev, dlinkptr, dlinkcfgptr) LINEDEV bdev • device handle DLINK *dlinkptr • pointer to data link information block DLINK_CFG *dlinkcfgptr • pointer to location of D channel logical link configuration block 0 on success < 0 on failure cclib.
PAGE 120
cc_GetDLinkCfg( ) retrieves the configuration of a logical link #include "cclib.h" /* Global variables */ LINEDEV ldev; /* Board device handle */ main() { DLINK dlink; DLINK_CFG cfg; . . . dlink.sapi = 0; dlink.ces = 1; /* Get config parameters for ces 1, sapi 0 */ if ( cc_GetDLinkCfg(ldev, &dlink, &cfg) < 0) { printf("error"); } else { printf(" tei=0x%X state=0x%X protocol=0x%X\n", cfg.tei, cfg.state, cfg.protocol); . . .
PAGE 121
retrieves the logical data link state Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_GetDLinkState( ) int cc_GetDLinkState(bdev, dlinkptr, state_buf) LINEDEV bdev • device handle DLINK *dlinkptr • pointer to data link information block int *state_buf • pointer to location of D channel state 0 on success < 0 on failure cclib.
PAGE 122
cc_GetDLinkState( ) ! retrieves the logical data link state Example /* BRI code example */ #include #include #include #include #include #include "srllib.h" "dtilib.h" "cclib.h" /* For Windows applications only */ /* Global variables */ LINEDEV lbuf; main () { DLINK dlink; char ces; . . . /* open BRI station device bris1 */ dlink.sapi = 0; /* check state of each data link */ for(ces = 1; ces <= 8; ces++) { /* initialize connection endpoint suffix */ dlink.
PAGE 123
retrieves the logical data link state Error Code Description ERR_ISDN_LIB|E_ISBADIF Bad interface number ERR_ISDN_LIB|E_ISNOMEM Cannot map or allocate memory ! • • cc_GetDLinkState( ) See Also cc_GetCES( ) cc_GetSAPI( ) 111
PAGE 124
cc_GetDNIS( ) gets the dialed number information string Name: Inputs: Returns: Includes: Category: Mode: Technology: ! int cc_GetDNIS(crn, dnis_buf) CRN crn • call reference number char *dnis_buf • pointer to DNIS buffer 0 on success < 0 on failure cclib.h Optional call handling synchronous BRI/2; BRI/SC; PRI (all protocols) Description The cc_GetDNIS( ) function gets the dialed number information string (destination address/called party number) associated with a specific call reference number (CRN).
PAGE 125
gets the dialed number information string char char cc_GetDNIS( ) *devname = "dtiB1T1"; dnis_buf[CC_ADDRSIZE]; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } printf("Waiting for call\n"); if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); printf("Getting DNIS\n"); if ( cc_GetDNIS(crn,dnis_buf) < 0 ) callfail(crn); else printf("cc_GetDNIS succeeded: %s\n",dnis_buf); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn
PAGE 126
cc_GetDNIS( ) gets the dialed number information string used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 127
retrieves the current ISDN event mask Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_GetEvtMsk( ) int cc_GetEvtMsk(bdev, maskp) LINEDEV bdev • device handle ULONG *maskp • pointer to mask buffer 0 on success < 0 on failure cclib.h System tools synchronous BRI/2; BRI/SC; PRI (all protocols) Description The cc_GetEvtMsk( ) function retrieves the current ISDN event mask for a specified board device handle for PRI or station device handle for BRI.
PAGE 128
cc_GetEvtMsk( ) retrieves the current ISDN event mask Bitmask Type Action Default Setting CCMSK_SERVICE Receiving CCEV_SERVICE. When this event arrives, the application should respond with a status message using cc_SndMsg( ). The firmware will not automatically respond to this message. Not enabled CCMSK_SERVICE_ACK Receiving CCEV_SETCHANSTATE. When this event is masked, the cc_SetChanState( ) function may be blocked.
PAGE 129
retrieves the current ISDN event mask ! cc_GetEvtMsk( ) Cautions None ! Example #include #include #include #include #include #include "srllib.h" "dtilib.h" "cclib.h" /* For Windows applications only */ void main() { LINEDEV devhdl = 0; CRN crn = 0; char *devname = "dtiB1T1"; ULONG *evtmskvalue; USHORT uSubMask; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } if ( cc_GetEvtMsk (devhdl, &evtmskvalue) < 0 ) {
PAGE 130
cc_GetEvtMsk( ) ! retrieves the current ISDN event mask Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 131
retrieves the frame Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_GetFrame( ) int cc_GetFrame(linedev, rcvfrmptr) LINEDEV linedev • line device handle for D channel L2_BLK *rcvfrmptr • pointer to the received frame buffer 0 on success < 0 on failure cclib.h Data link layer handling synchronous BRI/SC; PRI (excluding DPNSS) Description The cc_GetFrame( ) function retrieves the frame received by the application. This function is used after a CCEV_L2FRAME event is received.
PAGE 132
cc_GetFrame( ) ! retrieves the frame Example #include #include #include #include #include #include "srllib.h" "dtilib.h" "cclib.h" /* For Windows applications only */ /* Global variables */ int size = 8; LINEDEV lbuf; L2_BLK; rcvfrmptr; typedef long int (*EVTHDLRTYP)( ); . . . int evt_hdlr( ) { int rc = 0; int ldev = sr_getevtdev( ); unsigned long *ev_datap = (unsigned long *)sr_getevtdatap( ); int len = sr_getevtlen( ); switch(sr_getevttype( )) { . . .
PAGE 133
retrieves the frame cc_GetFrame( ) Error codes from the cc_GetFrame( ) function include the following: Error Code Description ERR_ISDN_LIB | E_ISNOINFO Information not available ! • See Also cc_SndFrame( ) 121
PAGE 134
cc_GetInfoElem( ) Name: Reference: Inputs: Returns: Includes: Category: Mode: Technology: ! gets information elements associated with a line device int cc_GetInfoElem(linedev, iep) LINEDEV linedev • line device handle of the B channel board IE_BLK *iep • pointer to the information element buffer 0 on success < 0 on failure cclib.
PAGE 135
gets information elements associated with a line device cc_GetInfoElem( ) Network Facility IE using the cc_GetCallInfo( ) function is no longer supported. ! Example #include #include #include /* For Windows applications only */ long evt_handl; void main(...) { char LINEDEV CRN int dev_name[20]; devhdl[MAXDEVS]; crn[MAXDEVS]; ch; sprintf(dev_name, "dtiB1"); if(cc_Open(devhdl[0], dev_name, 0) != 0) { printf("cc_Open(%s) failed\n", dev_name); exit(0); } for(ch = 1; ch
PAGE 136
cc_GetInfoElem( ) gets information elements associated with a line device int i; printf("%s: CCEV_NOTIFY cc_GetInfoElem =%d\n", ATDV_NAMEP(event_dev), cc_GetInfoElem(event_dev, &ie) ); printf("IE %d)= ", ie.length); for(i = 0; i < ie.length; i++) printf("%02X, ", (unsigned char)ie.data[i]); printf("\n"); . . } break; . . . } } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure.
PAGE 137
retrieves the line device handle for an event Name: Inputs: int cc_GetLineDev(linedevp, evtdatap) LINEDEV *linedevp • pointer to the line device handle void *evtdatap • pointer to an event block 0 on success < 0 on failure cclib.h System tools synchronous BRI/2; BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! cc_GetLineDev( ) Description The cc_GetLineDev( ) function retrieves the line device handle for an event from the event queue.
PAGE 138
cc_GetLineDev( ) retrieves the line device handle for an event ATDV_ERRMSGP( SRL_DEVICE ) ); return( 1 ); } . . . .
PAGE 139
collects more digits via overlap receiving Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_GetMoreDigits( ) int cc_GetMoreDigits(crn, numofdigs, timeout, mode) CRN crn • call reference number int numofdigs • number of digits to be collected long timeout • timeout value in seconds unsigned long mode • asynchronous or synchronous 0 on success < 0 on failure cclib.
PAGE 140
cc_GetMoreDigits( ) collects more digits via overlap receiving Parameter Description crn: The call reference number. Each call needs a valid CRN. numofdigs: The number of digits to be collected. timeout: Specifies the amount of time in seconds in which the additional digits must be collected. The function returns unconditionally when the timer expires. The timeout parameter is used to prevent a blocked situation in which the application expects more digits than the network provides.
PAGE 141
collects more digits via overlap receiving cc_GetMoreDigits( ) { LINEDEV CRN char devhdl = 0; crn = 0; *devname = "dtiB1T1"; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); if ( cc_GetDNIS(crn, dnis_buf) < 0 ) callfail(crn); /* * The cc_GetMoreDigits() function can only be called * after the cc_WaitCall and before cc_CallProgress(), * cc_AcceptCall() and cc_AnswerCall(
PAGE 142
cc_GetMoreDigits( ) collects more digits via overlap receiving cc_ResultMsg(handle,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 143
retrieves the network call reference value Name: Inputs: int cc_GetNetCRV(crn, netcrvp) CRN crn • call reference number int *netcrvp • pointer to network call reference buffer 0 on success < 0 on failure cclib.h System tools synchronous BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! cc_GetNetCRV( ) Description The cc_GetNetCRV( ) function retrieves the network call reference value (CRV) for a specified call reference number (CRN).
PAGE 144
cc_GetNetCRV( ) retrieves the network call reference value #include "srllib.h" #include "dtilib.h" #include "cclib.h" void main() { LINEDEV devhdl = 0; CRN crn = 0; char *devname = "dtiB1T1"; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } if ( sr_enbhdlr(devhdl, CCEV_OFFERED, (HDLR)OfferedHdlr) == < 0 ) { printf ( ‘sr_enbhdlr for OFFERED failed: %s\n’, ATDV_ERRMSGP(devhdl)); return (1); } } /* * OfferedHdlr - Accept the incoming call */ OfferedH
PAGE 145
retrieves the network call reference value ! cc_GetNetCRV( ) Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 146
cc_GetNonCallMsg( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! retrieves call data for a GLOBAL or NULL CRN event int cc_GetNonCallMsg(devhndl, msgblkptr) LINEDEV devHndl • board device handle associated with NULL or GLOBAL CRN event NONCRN_BLK *msgblkptr • pointer to NULL or GLOBAL information structure 0 on success < 0 on failure cclib.
PAGE 147
retrieves call data for a GLOBAL or NULL CRN event • • • cc_GetNonCallMsg( ) CCEV_INFOGLOBAL CCEV_NOTIFYGLOBAL CCEV_FACILITYGLOBAL Parameter Description devhndl: The board device on which the GLOBAL or NULL event occurred. msgblkptr: Pointer to the NONCRN_BLK data structure that contains the information related to the GLOBAL or NULL CRN event. For a description of the data structure, see Section 6.9. NONCRN_BLK. See the Example code below for details.
PAGE 148
cc_GetNonCallMsg( ) retrieves call data for a GLOBAL or NULL CRN event if(cc_GetNonCallMsg(devhndl, &nullDataBlk) == 0) { int i; printf(“Sapi = 0x%x.\n”,nullDataBlk.sapi); printf(“CES = 0x%x.\n”,nullDataBlk.ces); printf(“Raw IE data length = %d.\n”,nullDataBlk.length); printf(“IE data =:\n”); for(i = 0; i < nullDataBlk.Iength; i++) { printf("0x%02x ", (unsigned char)nullDataBIk.
PAGE 149
retrieves call data for a GLOBAL or NULL CRN event ! cc_GetNonCallMsg( ) Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 150
cc_GetParm( ) gets the current parameter values of the line device Name: Inputs: int cc_GetParm(linedev, parm_id, valuep) LINEDEV linedev • line device handle int parm_id • parameter identifier CC_PARM *valuep • pointer to value buffer 0 on success < 0 on failure cclib.h System tools synchronous BRI/2; BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! Description The cc_GetParm( ) function gets the current parameter values of the line device.
PAGE 151
gets the current parameter values of the line device cc_GetParm( ) Table 21.
PAGE 152
cc_GetParm( ) gets the current parameter values of the line device Define Description Possible return values USR_RATE User rate to use on bearer channel (layer 1 rate) ISDN_UR_EINI460 - determined by E bits in I.460 ISDN_UR_56000 - 56 kbits ISDN_UR_64000 - 64 kbits ISDN_UR_134 - 134.5 bits, X.1 ISDN_UR_12000 - 12 kbits, V.6 CALLED_NUM_TYPE Called number type EN_BLOC_NUMBER - number is sent en-block (in whole, not overlap sending) INTL_NUMBER - international number for international call.
PAGE 153
gets the current parameter values of the line device cc_GetParm( ) Define Description Possible return values CALLING_NUM_PLAN Calling number plan Same values as CALLED_NUM_PLAN CALLING_ PRESENTATION Calling presentation indicator PRESENTATION_ALLOWED allows the display of the calling number at the remote end CALLING_SCREENING Calling screening indicator field USER_PROVIDED - user provided, not screened (passes through) RECEIVE_INFO_BUF Multiple IE buffer – the number of messages that can be s
PAGE 154
cc_GetParm( ) gets the current parameter values of the line device printf("Parameter BC_XFER_RATE has value: 0x%x\n",value); if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); . . . . . if ( cc_DropCall(crn, NORMAL_CLEARING, EV_SYNC) < 0 ) callfail(crn); if ( cc_ReleaseCall(crn) < 0 ) procdevfail(devhdl); if ( cc_Close( devhdl ) < 0 ) printf("Error closing device, errno = %d\n", errno); } int callfail(CRN crn) { LINEDEV ld;
PAGE 155
gets the current parameter values of the line device ! • • cc_GetParm( ) See Also cc_GetParmEx( ) cc_SetParm( ) 143
PAGE 156
cc_GetParmEx( ) Name: Inputs: int cc_GetParmEx(linedev, parm_id, valuep) LINEDEV linedev • line device handle int parm_id • parameter identifier PARM_INFO *valuep • pointer to buffer containing the variable data 0 on success < 0 on failure cclib.
PAGE 157
retrieve parameters containing variable data cc_GetParmEx( ) Table 22. cc_GetParmEx( ) Parameter ID Definitions Define Description Return values DIRECTORY_NUMBER Directory Number String of length parmdatalen SPID_NUMBER Service Provider Identifier String of length parmdatalen SUBADDR_NUMBER Subaddress Number String of length parmdatalen ! Cautions None ! Example #include #include #include #include #include #include #include "srllib.h" "dtilib.
PAGE 158
cc_GetParmEx( ) retrieve parameters containing variable data procdevfail(devhdl); else { strcpy(databuffer, parm_ret_value.parmdata); printf("Parameter DIRECTORY_NUMBER has value: %s\n", databuffer); } if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); . . .
PAGE 159
retrieve parameters containing variable data Error Code Description ERR_ISDN_LIB | E_ISBADIF Bad interface number ERR_ISDN_LIB | E_ISBADTS Bad time slot ERR_ISDN_LIB | E_ISBADPAR Bad input parameter ! • • cc_GetParmEx( ) See Also cc_GetParm( ) cc_SetParmEx( ) 147
PAGE 160
cc_GetSAPI( ) retrieves the service access point ID Name: Inputs: int cc_GetSAPI(sapip, evtdatap) char *sapip • pointer to service access point ID buffer void *evtdatap • pointer to an event block 0 on success < 0 on failure cclib.h System tools synchronous BRI/SC Returns: Includes: Category: Mode: Technology: ! Description The cc_GetSAPI( ) function retrieves the service access point ID (SAPI) associated with the CCEV_D_CHAN_STATUS event received from the event queue.
PAGE 161
retrieves the service access point ID L2_BLK unsigned int unsigned char int void cc_GetSAPI( ) frame; resultValue; sapi, ces; device; *datap; device = sr_getevtdev(); datap = sr_getevtdatap(); ...
PAGE 162
cc_GetSAPI( ) retrieves the service access point ID can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 163
gets the signaling information of an incoming message Name: Inputs: int cc_GetSigInfo(valuep, info_id, evtdatap) char *valuep • pointer to information buffer int info_id • signal information identifier void *evtdatap • pointer to an event block 0 on success < 0 on failure cclib.
PAGE 164
cc_GetSigInfo( ) gets the signaling information of an incoming message Table 23. cc_GetSigInfo( ) Info_ID Definitions Info_ID Definition U_IES Information elements (IEs) in CCITT format. The cc_GetSigInfo( ) function retrieves all unprocessed IEs in CCITT format. Be sure to allocate enough memory (up to 256 bytes) to hold the retrieved information elements. The IEs are returned as raw data and must be parsed and interpreted by the application. Use IE_BLK to retrieve the unprocessed IEs.
PAGE 165
gets the signaling information of an incoming message cc_GetSigInfo( ) Network Facility IE using the cc_GetCallInfo( ) function is no longer supported. ! Example #include #include #include #include #include #include #define MAX_QUEUE_SIZE /* For Windows applications only */ 20 void main() { LINEDEV ldev; char *devname = "dtiB1T1"; . . .
PAGE 166
cc_GetSigInfo( ) gets the signaling information of an incoming message . . . switch(sr_getevttype()){ . . . case CCEV_CALLINFO: /* retrieve signaling information from queue */ if ( cc_GetSigInfo(&ie_blk, U_IES, ev_datap) <0) { /* failed, get failure reason */ procdevfail (ldev); } else { /* succeeded, process signaling information */ . . . } break; } . . . } int procdevfail(LINEDEV ldev) { int reason; char *msg; reason = cc_CauseValue(ldev); cc_ResultMsg(ldev,reason,&msg); printf("reason = %x - %s\n",reas
PAGE 167
gets the signaling information of an incoming message cc_GetSigInfo( ) Error codes from the cc_GetSigInfo( ) function include the following: Error Code Description E_ISMISGSI | ERR_ISDN_LIB The cc_GetSigInfo( ) function is not supported because the application did not use cc_SetParm( ) to allocate the signaling queue. E_ISLSIEBUF | ERR_ISDN_LIB The signaling information queue was too small to accommodate the incoming data. The signaling information associated with this event is lost.
PAGE 168
cc_GetUsrAttr( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! gets the established attribute for the line device int cc_GetUsrAttr(linedev, usr_attr) LINEDEV linedev • line device handle long *usr_attr • user attribute information 0 on success < 0 on failure cclib.h System tools synchronous BRI/2; BRI/SC; PRI (all protocols) Description The cc_GetUsrAttr( ) function gets the established attribute for the line device.
PAGE 169
gets the established attribute for the line device cc_GetUsrAttr( ) . if ( sr_enbhdlr( devhdl,CCEV_DISCONNECTED,discCallHdlr ) < 0 ) { printf( “dtiEnable for DISCONNECT failed: %s\n”, ATDV_ERRMSGP( SRL_DEVICE ) ); return( 1 ); } printf(devname,”dtiB1T%d”,chan); if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf(“Error opening device: errno = %d\n”, errno); exit(1); } if ( cc_SetUsrAttr(devhdl,chan)) procdevfail(devhdl); . . . .
PAGE 170
cc_GetUsrAttr( ) gets the established attribute for the line device } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf(“reason = %x - %s\n”,reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.
PAGE 171
retrieves the firmware version number Name: Inputs: int cc_GetVer(linedev, majorp, minorp) LINEDEV linedev • line device handle int *majorp • pointer to major number int *minorp • pointer to minor number 0 on success < 0 on failure cclib.h Optional call handling synchronous BRI/2; BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! cc_GetVer( ) Description The cc_GetVer( ) function retrieves the firmware version number associated with the specified line device handle.
PAGE 172
cc_GetVer( ) retrieves the firmware version number int minnum; /* minor version number */ . . . if ( cc_Open(devhdl,”dtiB1”, 0 ) < 0 ) printf(“Error opening device: errno = %d\n”, errno); /* * Use cc_GetVer() to get the version values. */ if ( cc_GetVer(devhdl,&majnum,&minnum) < 0 ) procdevfail(devhdl); else printf(“Major version number 0x%x, minor version number 0x%x\n” ,majnum,minnum); /* continue the program. */ . . . . . if ( cc_Close(devhdl) < 0 ) printf(“Error closing device, errno = %d\n”, errno);
PAGE 173
accept a hold request from remote equipment Name: Inputs: Returns: int cc_HoldAck(crn) CRN crn • call reference number 0 on success <0 on failure cclib.h Hold and Retrieve synchronous BRI/2; BRI/SC; PRI (DPNSS and Q.SIG only) Includes: Category: Mode: Technology: ! cc_HoldAck( ) Description The cc_HoldAck( ) function allows the application to accept a hold request from remote equipment.
PAGE 174
cc_HoldAck( ) accept a hold request from remote equipment exit(1); } if ( sr_enbhdlr( ldev,CCEV_HOLDCALL,HoldCallHdlr ) < 0 ) { printf( "dtiEnable for HoldCallHdlr failed: %s\n", ATDV_ERRMSGP( SRL_DEVICE ) ); return( 1 ); } . . . .
PAGE 175
accept a hold request from remote equipment cc_HoldAck( ) Error codes from the cc_HoldAck( ) function include the following: Error Code Description ERR_ISDN_FW | ISDN_BADSTATE Cannot accept event in current state ERR_ISDN_LIB | E_ISNULL_PTR Null pointer error ! • See Also cc_RetrieveCall( ) 163
PAGE 176
cc_HoldCall( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! place an active call on hold int cc_HoldCall(crn, mode) CRN crn • call reference number unsigned long mode • synchronous or asynchronous 0 on success <0 on failure cclib.h Hold and Retrieve synchronous or asynchronous BRI/2; BRI/SC; PRI (DPNSS and Q.SIG only) Description The cc_HoldCall( ) function allows the application to place an active call on hold.
PAGE 177
place an active call on hold ! cc_HoldCall( ) Example #include #include #include #include #include #include #include /* For Windows applications only */ void main() { LINEDEV ldev; CRN crn_buf = 0; char *devname = "dtiB1T1"; if ( cc_Open( &ldev, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } printf("Waiting for call\n"); if ( cc_WaitCall(ldev, &crn_buf, NULL, -1, EV_SYNC) < 0 ) { procdevfa
PAGE 178
cc_HoldCall( ) place an active call on hold } /* Close the device */ if ( cc_Close( ldev ) < 0 ) printf("Error closing device, errno = %d\n", errno); } int procdevfail(LINEDEV ldev) { int reason; char *msg; reason = cc_CauseValue(ldev); cc_ResultMsg(ldev,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure.
PAGE 179
reject a hold request from remote equipment Name: Inputs: int cc_HoldRej(crn, cause) CRN crn • call reference number int cause • standard ISDN Network error code 0 on success <0 on failure cclib.h Hold and Retrieve synchronous BRI/2; BRI/SC; PRI (DPNSS and Q.SIG only) Returns: Includes: Category: Mode: Technology: ! cc_HoldRej( ) Description The cc_HoldRej( ) function allows the application to reject a hold request from remote equipment.
PAGE 180
cc_HoldRej( ) ! reject a hold request from remote equipment Example #include #include #include #include #include #include /* For Windows applications only */ main() { char *devname = “dtiB1T1”; LINEDEV ldev; . . . . if ( cc_Open( &ldev, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } if ( sr_enbhdlr( ldev,CCEV_HOLDCALL,HoldCallHdlr ) < 0 ) { printf( "dtiEnable for HoldCallHdlr failed: %s\n", ATDV_ERRM
PAGE 181
reject a hold request from remote equipment cc_HoldRej( ) int procdevfail(LINEDEV ldev) { int reason; char *msg; reason = cc_CauseValue(ldev); cc_ResultMsg(ldev,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 182
cc_MakeCall( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! request a connection to make an outgoing call int cc_MakeCall(linedev, crnp, numberstr, makecallp, timeout, mode) LINEDEV linedev • device handle CRN *crnp • pointer to call reference number char *numberstr • destination phone number MAKECALL_BLK *makecallp • pointer to outbound call information int timeout • time interval unsigned long mode • synchronous or asynchronous 0 on success < 0 on failure cclib.
PAGE 183
request a connection to make an outgoing call cc_MakeCall( ) Parameter Description linedev: The line device handle or, for applications using the call waiting feature, the board device handle (BRI and Windows only). crnp: Pointer to the buffer where the call reference number will be stored. numberstr: The destination (called party 's) telephone number string. The maximum length is 32 digits.
PAGE 184
cc_MakeCall( ) • ! request a connection to make an outgoing call BRI only: Applications using the call waiting feature must use the cc_MakeCall( ) function in asynchronous mode. Example #include #include #include #include #include #include “srllib.h” “dtilib.h” “cclib.
PAGE 185
request a connection to make an outgoing call cc_MakeCall( ) void build_makecall_blk( MAKECALL_BLK *makecall_blk ) { memset(makecall_blk,0xff,sizeof(MAKECALL_BLK)); makecall_blk->isdn.BC_xfer_cap = BEAR_CAP_SPEECH; makecall_blk->isdn.BC_xfer_mode = ISDN_ITM_CIRCUIT; makecall_blk->isdn.BC_xfer_rate = BEAR_RATE_64KBPS; makecall_blk->isdn.facility_coding_value = ISDN_CPN; makecall_blk->isdn.destination_number_type = NAT_NUMBER; makecall_blk->isdn.destination_number_plan = ISDN_NUMB_PLAN; makecall_blk->isdn.
PAGE 186
cc_MakeCall( ) request a connection to make an outgoing call printf(“The call is conducted on channel %d\n”, chanId.channel); . . . if ( cc_DropCall(crn, NORMAL_CLEARING, EV_SYNC) < 0 ) callfail(crn); if ( cc_ReleaseCall(crn) < 0 ) callfail(crn); if ( cc_Close( devhdl ) < 0 ) printf(“Error closing device, errno = %d\n”, errno); } int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_Result
PAGE 187
request a connection to make an outgoing call ! cc_MakeCall( ) Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 188
cc_Open( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! opens a device int cc_Open(linedevp, devicename, rfu) LINEDEV *linedevp • pointer to the buffer storing the line device handle char *devicename • name of the device int rfu • reserved for future use 0 on success <0 on failure cclib.
PAGE 189
opens a device cc_Open( ) Each BRI structure is composed of one D channel and two B (bearer) channels. A BRI board device, such as briS1, is defined as a station and controls the D-channel the same way as a PRI board device. A BRI time slot device, such as briS1T1, is defined as a bearer channel under a station and is handled the same way as a PRI line device. ! Cautions Do not open a D or B channel more than once from the same process, or unpredictable results could occur.
PAGE 190
cc_Open( ) opens a device int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf(“reason = %x - %s\n”,reason,msg); } ! Errors If the function returns < 0 to indicate failure, check errno.h to retrieve the reason for the failure.
PAGE 191
play a user-defined tone Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_PlayTone( ) int cc_PlayTone(devHdl, pToneParm, tptp, mode) int devHdl • channel device handle toneParm *pToneParm • pointer to the toneParm structure DV_TPT *tptp • pointer to the DV_TPT structure int mode • asynchronous/synchronous 0 on success <0 on failure cclib.
PAGE 192
cc_PlayTone( ) play a user-defined tone Use the SRL Event Management functions to handle the termination event. ! Cautions • The channel must be in the Idle state when calling the cc_PlayTone( ) function. • The cc_PlayTone( ) command is a host tone command that allows the application to play a user-defined tone. This command cannot be used to set or play the firmware-applied call progress tones.
PAGE 193
play a user-defined tone cc_PlayTone( ) * Play a Tone with its * Frequency1 = 330, Frequency2 = 460 * amplitude at -10dB for both * frequencies and duration of infinity * This is a Panasonic Local Dial Tone. * */ if (cc_PlayTone( devHdl, &ToneParm, &tpt, EV_SYNC ) == -1 ){ printf( "Unable to Play the Tone\n" ); printf( "Lasterror = %d Err Msg = %s\n", cc_CauseValue( devHdl ), cc_ResultMsg( devHdl ) ); cc_close( devHdl); exit( 1 ); } /* * Continue Processing * . * . * .
PAGE 194
cc_PlayTone( ) play a user-defined tone ERR_TONEON1 Invalid value specified in parameter toneOn1 ERR_TONEOFF1 Invalid value specified in parameter toneOff1 ERR_TONEDURATION Invalid value specified in parameter duration ERR_TONECHANNELID Invalid channel ID ! • • See Also cc_ToneRedefine( ) cc_StopTone( ) 182
PAGE 195
release all internal resources Name: Inputs: Returns: int cc_ReleaseCall(crn) CRN crn • call reference number 0 on success < 0 on failure cclib.h Call control synchronous BRI/2; BRI/SC; PRI (all protocols) Includes: Category: Mode: Technology: ! cc_ReleaseCall( ) Description The cc_ReleaseCall( ) function instructs the driver and firmware to release all internal resources for the specified call. An inbound call will be rejected after cc_DropCall( ) is used.
PAGE 196
cc_ReleaseCall( ) release all internal resources bottleneck for processing any other event and, thereby, could affect call handling performance. • After a connection is terminated, the cc_ReleaseCall( ) function should be called to release the call reference number (CRN). Failure to call this function may cause a blocking condition or a memory allocation error. Channels will remain allocated if call-related resources are not released.
PAGE 197
release all internal resources cc_ReleaseCall( ) procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf(“reason = %x - %s\n”,reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.
PAGE 198
cc_ReleaseCallEx( ) Name: Inputs: int cc_ReleaseCallEx(crn, mode) CRN crn • call reference number unsigned long • synchronous or asynchronous mode 0 on success < 0 on failure cclib.h Call control synchronous or asynchronous BRI/2; BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! release all Dialogic ISDN resources Description The cc_ReleaseCallEx( ) function instructs the driver and firmware to release all Dialogic ISDN resources for the specified call.
PAGE 199
release all Dialogic ISDN resources ! cc_ReleaseCallEx( ) Termination Events • CCEV_RELEASECALL - indicates that all Dialogic ISDN resources have been released for the call. • CCEV_RELEASECALLFAIL – indicates that the cc_ReleaseCallEx( ) function failed. ! Cautions The cc_ReleaseCallEx( ) function is not supported for LINUX applications. ! Example #include #include #include #include #include #include #include "srllib.h" "dtilib.h" "cclib.
PAGE 200
cc_ReleaseCallEx( ) release all Dialogic ISDN resources exit(1); } else printf("Waiting for call...\n"); . . . /* wait indefinitely for events */ sr_waitevt(-1); /* continue with application */ . . . .
PAGE 201
release all Dialogic ISDN resources cc_ReleaseCallEx( ) Possible error codes from the cc_ReleaseCallEx( ) function include the following: Error Code Description ERR_ISDN_LIB | E_ISBADIF Bad interface number ERR_ISDN_LIB | E_BADSTATE Bad state ERR_ISDN_LIB | E_ISBADTS Bad time slot ! • See Also cc_DropCall( ) 189
PAGE 202
cc_ReqANI( ) returns the caller ID Name: Inputs: Returns: Includes: Category: Mode: Technology: ! int cc_ReqANI(crn, ani_buf, reqtype, mode) CRN crn • call reference number char *ani_buf • pointer to address of ANI buffer int reqtype • type of information requested unsigned long mode • synchronous or asynchronous 0 on success < 0 on failure cclib.
PAGE 203
returns the caller ID cc_ReqANI( ) AT&T’s ANI-on-demand service). cc_ReqANI( ) is a non-multitasking function when the calling party number is received or when the network does not offer an ANI-on-demand service. Thus, if ANI is already available, the function returns immediately because it does not have to instruct the interface device to query the switch. In EV_ASYNC mode, the function will always return an event. In EV_SYNC mode, the function will return automatically with the ANI if one is available.
PAGE 204
cc_ReqANI( ) returns the caller ID if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf(“Error opening device: errno = %d\n”, errno); exit(1); } if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); printf(“Requesting ANI\n”); if ( cc_ReqANI(crn, ani_buf, ISDN_CPN_PREF, EV_SYNC) < 0 ) callfail(crn); else printf(“cc_ReqANI succeeded: %s\n”,ani_buf); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); . . . . .
PAGE 205
returns the caller ID cc_ReqANI( ) Error Code Description ERR_ISDN_LIB | E_ISBADPAR Bad input parameter ERR_ISDN_LIB | E_ISNULLPTR Null pointer error ERR_ISDN_LIB | E_ISBADIF Bad interface number ERR_ISDN_LIB | E_ISBADCALLID Bad call identifier ERR_ISDN_LIB | E_ISBADTS Bad time slot ! • • See Also cc_GetANI( ) cc_WaitCall( ) 193
PAGE 206
cc_Restart( ) resets the channel to Null state Name: Inputs: int cc_Restart(linedev, mode) LINEDEV linedev • device handle unsigned long mode • asynchronous or synchronous 0 on success < 0 on failure cclib.h System control synchronous or asynchronous BRI/2; BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! Description The cc_Restart( ) function resets the channel to Null state.
PAGE 207
resets the channel to Null state ! • cc_Restart( ) Termination Event CCEV_RESTART - indicates that the Restart operation has been completed. The channel is in Null state. CCEV_RESTARTFAIL - indicates that the function call failed. The application can use cc_ResultValue( ) after this event is received to verify the reason for failure. • ! Cautions In asynchronous mode, the application cannot call any call state-related function prior to CCEV_RESTART. ! Example #include
PAGE 208
cc_Restart( ) resets the channel to Null state . . cc_Close(devhdl); } /****************************************************************** /* NAME: void WaitCallThread(devhdlptr) /* DESCRIPTION: Waits for incoming call. /* INPUT: devhdlptr - pointer to devhdl /* RETURNS: none. ******************************************************************/ void WaitCallThread(void *devhdlptr) { short devhdl = *devhdlptr; /* device handle */ CRN crn; /* call reference number */ . . . while(1) { . . .
PAGE 209
resets the channel to Null state cc_Restart( ) * is recommended here. */ if ( cc_MakeCall(devhdl, &crn, dialnum, NULL, 20, EV_SYNC) < 0 ) procdevfail(devhdl); . . . . } /* function to process error conditions */ int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle, reason, &msg); printf(“reason = %x - %s\n”,reason,msg); } ! Errors If the function returns a value < 0 to
PAGE 210
cc_ResultMsg( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! interprets the function return code int cc_ResultMsg(linedev, ResultCode, msg) LINEDEV linedev • line device handle int ResultCode • function return value char **msg • pointer to the address where the result message is stored 0 on success < 0 on failure cclib.h System tools synchronous BRI/2; BRI/SC; PRI (all protocols) Description cc_ResultMsg( ) is a convenience function that interprets the function return code.
PAGE 211
interprets the function return code cc_ResultMsg( ) void main() { LINEDEV devhdl = 0; CRN crn = 0; char *devname = “dtiB1T1”; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf(“Error opening device: errno = %d\n”, errno); exit(1); } printf(“Waiting for call\n”); if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); . . . . .
PAGE 212
cc_ResultMsg( ) ! See Also • 200 cc_ResultValue( ) interprets the function return code
PAGE 213
gets an error/cause code Name: Inputs: Returns: int cc_ResultValue(evtdatap) void *evtdatap • pointer to an event block 0 on success < 0 on failure to retrieve the error/cause value > 0 error/cause value associated with event cclib.h System tools synchronous BRI/2; BRI/SC; PRI (all protocols) Includes: Category: Mode: Technology: ! cc_ResultValue( ) Description The cc_ResultValue( ) function gets an error/cause code of an event.
PAGE 214
cc_ResultValue( ) gets an error/cause code . if ( sr_enbhdlr(devhdl, CCEV_DISCONNECTED, discCallHdlr) < 0 ) { printf( “dtiEnable for DISCONNECT failed: %s\n”, ATDV_ERRMSGP( SRL_DEVICE ) ); return( 1 ); } . . . .
PAGE 215
gets an error/cause code ! • cc_ResultValue( ) See Also cc_ResultMsg( ) 203
PAGE 216
cc_RetrieveAck( ) Name: Inputs: Returns: int cc_RetrieveAck(crn) CRN crn • call reference number 0 on success <0 on failure cclib.h Hold and Retrieve synchronous BRI/2; BRI/SC; PRI (Q.SIG only) Includes: Category: Mode: Technology: ! accept a request to retrieve a call from hold Description The cc_RetrieveAck( ) function allows the application to accept a request to retrieve a call from hold from remote equipment.
PAGE 217
accept a request to retrieve a call from hold cc_RetrieveAck( ) . . . if ( cc_Open( &ldev, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } if ( sr_enbhdlr( ldev,CCEV_HOLDCALL,HoldCallHdlr ) < 0 ) { printf( "dtiEnable for HoldCallHdlr failed: %s\n", ATDV_ERRMSGP( SRL_DEVICE ) ); return( 1 ); } if ( sr_enbhdlr( ldev,CCEV_RETRIEVECALL,RetrieveCallHdlr ) < 0 ) { printf( "dtiEnable for RetrieveCallHdlr failed: %s\n", ATDV_ERRMSGP( SRL_DEVICE ) ); return( 1 ); } . . . .
PAGE 218
cc_RetrieveAck( ) accept a request to retrieve a call from hold return( 0 ); } int procdevfail(LINEDEV ldev) { int reason; char *msg; reason = cc_CauseValue(ldev); cc_ResultMsg(ldev,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.
PAGE 219
retrieve a call from the Hold state Name: Inputs: int cc_RetrieveCall(crn, mode) CRN crn • call reference number unsigned long mode • synchronous or asynchronous 0 on success <0 on failure cclib.h Hold and Retrieve synchronous or asynchronous BRI/2; BRI/SC; PRI (DPNSS and Q.SIG only) Returns: Includes: Category: Mode: Technology: ! cc_RetrieveCall( ) Description The cc_RetrieveCall( ) function allows the application to retrieve a call from the Hold state.
PAGE 220
cc_RetrieveCall( ) retrieve a call from the Hold state void main() { LINEDEV ldev; CRN crn_buf = 0; char *devname = "dtiB1T1"; if ( cc_Open( &ldev, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } printf("Waiting for call\n"); if ( cc_WaitCall(ldev, &crn_buf, NULL, -1, EV_SYNC) < 0 ) { procdevfail(ldev); . } if ( cc_AnswerCall(crn_buf, 0, EV_SYNC) < 0 ) { procdevfail(ldev); . } . . . if ( cc_HoldCall(crn_buf, EV_SYNC) < 0 ) { procdevfail(ldev); . } . .
PAGE 221
retrieve a call from the Hold state cc_RetrieveCall( ) int procdevfail(LINEDEV ldev) { int reason; char *msg; reason = cc_CauseValue(ldev); cc_ResultMsg(ldev,reason,&msg); printf("reason = %x - %s\n",reason,msg); } ! Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 222
cc_RetrieveRej( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! reject a request to retrieve a held call int cc_RetrieveRej(crn, cause) CRN crn • call reference number int cause • standard ISDN Network cause/error code 0 on success <0 on failure cclib.h Hold and Retrieve synchronous BRI/2; BRI/SC; PRI (Q.SIG only) Description The cc_RetrieveRej( ) function allows the application to reject a request to retrieve a held call from remote equipment.
PAGE 223
reject a request to retrieve a held call • ! cc_RetrieveRej( ) Not all ISDN Network cause/error codes are universally supported across switch types. Before using a particular cause code, compare its validity with the appropriate switch vendor specifications. Example #include #include #include #include #include #include /* For Windows applications only */ main() { char *devname = “dtiB1T1”; LINEDEV ldev; . . . .
PAGE 224
cc_RetrieveRej( ) reject a request to retrieve a held call CRN crn_buf; LINEDEV ldev = sr_getevtdev(); int len = sr_getevtlen(); void *ev_datap = sr_getevtdatap(); cc_GetCRN(&crn_buf, ev_datap); if ( cc_HoldAck( crn_buf ) < 0 ) procdevfail(ldev); return( 0 ); } /***********************************************************/ /* RetrieveCallHdlr - Reject the retrieve call request */ /***********************************************************/ int RetrieveCallHdlr( ) { CRN crn_buf; LINEDEV ldev = sr_getevtdev
PAGE 225
reject a request to retrieve a held call ! • • • cc_RetrieveRej( ) See Also cc_HoldCall( ) cc_RetrieveAck( ) cc_RetrieveCall( ) 213
PAGE 226
cc_SetBilling( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! sets the billing rate for int cc_SetBilling(crn, rate_type, ratep, mode) CRN crn • call reference number int rate_type • type of billing data CC_RATE_U *ratep • pointer to call charge rate unsigned long mode • asynchronous or synchronous 0 on success < 0 on failure cclib.
PAGE 227
Vari-A-Bill services ! • • ! cc_SetBilling( ) Termination Events CCEV_SETBILLING - indicates that the billing information for the call has been acknowledged by the network. This event is returned only when the AT&T Vari-A-Bill feature is used. CCEV_TASKFAIL - indicates that a request/message was rejected by the firmware. Typically, this event is triggered by an incorrect function call during the call. Cautions • This function is available only on the AT&T network and only for the PRI 4ESS protocol.
PAGE 228
cc_SetBilling( ) Vari-A-Bill services * This function is used in conjunction with AT&T Vari-A-Bill * service only. * Do not use it in other protocol applications */ rate.ATT.cents = 99; if ( cc_SetBilling(crn, ISDN_FLAT_RATE, &rate, EV_SYNC) < 0 ) callfail(crn); . . . . . if ( cc_DropCall(crn, NORMAL_CLEARING, EV_SYNC) < 0 ) callfail(crn); if ( cc_ReleaseCall(crn) < 0 ) callfail(crn); if ( cc_Close(devhdl) < 0 ) printf(“Error closing device, errno = %d\n”, errno); } int callfail(CRN crn) { LINEDEV ld; cc_
PAGE 229
Vari-A-Bill services cc_SetBilling( ) Error Code Description ERR_ISDN_LIB | E_ISBADTS Bad time slot ERR_ISDN_LIB | E_FB_UNAVAIL Flex billing unavailable ERR_ISDN_LIB | E_ISBADIF Bad interface number ERR_ISDN_LIB | E_ISBADCALLID Bad call identifier ERR_ISDN_LIB | E_ISBADPAR Bad input parameter NOTE: See Section 7.2.1. Cause/Error Codes from the ISDN Firmware for information on firmware return codes that are specific to the cc_SetBilling( ) function.
PAGE 230
cc_SetCallingNum( ) Name: Inputs: int cc_SetCallingNum(linedev, callingnum) LINEDEV linedev • line device handle char *callingnum • calling phone number string 0 on success < 0 on failure cclib.h Optional call handling synchronous BRI/SC; PRI (all protocols) Returns: Includes: Category: Mode: Technology: ! sets the default calling party number Description The cc_SetCallingNum( ) function sets the default calling party number (caller ID) associated with the specific channel (line device) handle.
PAGE 231
sets the default calling party number cc_SetCallingNum( ) { LINEDEV CRN char devhdl = 0; crn = 0; *devname = “dtiB1T1”; if ( cc_Open(&devhdl, devname, 0) < 0 ) { printf(“Error opening device: errno = %d\n”, errno); exit(1); } /* * Using cc_SetCallingNum(devhndl, “9933000”) to * set default calling party number */ if ( cc_SetCallingNum(devhdl, “9933000”) < 0 ) procdevfail(devhdl); if ( cc_MakeCall(devhdl, &crn, ”9933000”, NULL, 30, EV_SYNC) < 0 ) procdevfail(devhdl); . . . . .
PAGE 232
cc_SetCallingNum( ) sets the default calling party number Error codes from the cc_SetCallingNum( ) function include the following: Error Code Description ERR_ISDN_LIB | E_ISBADTS Bad time slot ERR_ISDN_LIB | E_ISBADIF Bad interface number ! See Also • 220 cc_MakeCall( )
PAGE 233
change the maintenance state of a specified B channel Name: Inputs: int cc_SetChanState(linedev, chanstate, mode) LINEDEV linedev • line device handle int chanstate • channel service state unsigned long mode • synchronous or asynchronous 0 on success < 0 on failure cclib.
PAGE 234
cc_SetChanState( ) • ! change the maintenance state of a specified B channel CCEV_TASKFAIL - indicates that a request/message was rejected by the firmware. Typically, this event is triggered by an incorrect function call during the call. Cautions • The cc_SetChanState( ) function should only be invoked in the Null state. The Null state occurs immediately after a call to either the cc_Open( ) or cc_ReleaseCall( ) function.
PAGE 235
change the maintenance state of a specified B channel cc_SetChanState( ) /* Drop the call */ if ( cc_DropCall(crn, NORMAL_CLEARING, EV_SYNC) < 0 ) callfail(crn); if ( cc_ReleaseCall(crn) < 0 ) callfail(crn); /* Close the device */ if ( cc_Close( devhdl ) < 0 ) printf(“Error closing device, errno = %d\n”, errno); } int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle, reas
PAGE 236
cc_SetDChanCfg( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! sets the configuration of the Digital Subscriber Loop int cc_SetDChanCfg(boarddev, dchan_cfgptr) LINEDEV boarddev • line device handle of the D channel board DCHAN_CFG dchan_cfgptr • pointer to DCHAN_CFG structure 0 on success < 0 on failure isdncmd.h isdnlib.
PAGE 237
sets the configuration of the Digital Subscriber Loop cc_SetDChanCfg( ) Parameter Description boarddev: The line device handle of the D channel board. dchan_cfgptr: The pointer to the D channel configuration (DCHAN_CFG) block. See Section 6.3. DCHAN_CFG for a description of the DCHAN_CFG data structure and for possible field values. ! Cautions • The cc_SetDChanCfg( ) function must be issued prior to any call control commands.
PAGE 238
cc_SetDChanCfg( ) dchan_cfg.tmr.te.T305 dchan_cfg.tmr.te.T308 dchan_cfg.tmr.te.T310 dchan_cfg.tmr.te.T313 dchan_cfg.tmr.te.T318 dchan_cfg.tmr.te.T319 sets the configuration of the Digital Subscriber Loop = = = = = = TMR_DEFAULT; TMR_DEFAULT; TMR_DEFAULT; TMR_DEFAULT; TMR_DEFAULT; TMR_DEFAULT; . . . if (cc_Open(&boarddev, “briS1”, 0) != 0) { printf(“cc_open: error\n”); } if (cc_SetDChanCfg(boarddev, &dchan_cfg) == 0) { printf(“Configuration is set\n”); } else printf(“Configuration could not be set\n”); /*
PAGE 239
sets the configuration of the Digital Subscriber Loop Error Code Description ERR_ISDN_LIB | E_ISBADIF Bad interface number ERR_ISDN_LIB | E_ISNOMEM Cannot map or allocate memory ISDN_INVALID_SWITCH_TYPE Switch type requested is not supported ISDN_MISSING_FIXED_TEI Fixed Terminal Endpoint Identifier (TEI) value not provided for noninitializing terminal ISDN_MISSING_DN Directory number not specified for terminal ISDN_MISSING_SPID Service Profile Identifier (SPID) not provided for North American
PAGE 240
cc_SetDLinkCfg( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! configures a logical link int cc_SetDLinkCfg(bdev, dlinkptr, dlinkcfgptr) LINEDEV bdev • device handle DLINK *dlinkptr • pointer to data link information block DLINK_CFG *dlinkcfgptr • pointer to location of D channel logical link configuration block 0 on success < 0 on failure cclib.h System tools synchronous BRI/SC Description The cc_SetDLinkCfg( ) function configures a logical link.
PAGE 241
configures a logical link cc_SetDLinkCfg( ) #include "cclib.h" /* Global variables */ LINEDEV ldev; /* Board device handle */ main() { DLINK dlink; DLINK_CFG cfg; . . . dlink.sapi = 0; dlink.ces = 1; cfg.tei = AUTO_TEI; cfg.state = DATA_LINK_UP; cfg.protocol = DATA_LINK_PROTOCOL_Q931; if ( cc_SetDLinkCfg(ldev, &dlink, &cfg) < 0) { printf("error"); } else { . . .
PAGE 242
cc_SetDLinkState( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! set the logical data link state int cc_SetDLinkState(bdev, dlinkptr, state_buf) LINEDEV bdev • device handle DLINK *dlinkptr • pointer to data link information block int *state_buf • pointer to location of D channel state 0 on success < 0 on failure cclib.
PAGE 243
set the logical data link state cc_SetDLinkState( ) Parameter Description bdev: Board device handle for PRI, station device handle for BRI. dlinkptr: Pointer to the data link information block. See Section 6.4. DLINK for a description of the elements of this data structure. state_buf: Pointer to the buffer containing the requested data link state value.
PAGE 244
cc_SetDLinkState( ) LINEDEV set the logical data link state ldev; main() { DLINK dlink; int state; . . . /* Establish the data link on SAPI 0, CES 1 */ dlink.sapi = 0; dlink.ces = 0; state = DATA_LINK_UP; if(cc_SetDLinkState(ldev, &dlink, &state) < 0) { printf(“error”); } else { . . . } } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code.
PAGE 245
sets the event mask Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_SetEvtMsk( ) int cc_SetEvtMsk(linedev, mask, action) LINEDEV linedev • line device handle unsigned long mask • bitmask or events int action • action to be taken on the mask bit 0 on success < 0 on failure cclib.
PAGE 246
cc_SetEvtMsk( ) sets the event mask Bitmask Type Action Default CCMSK_CALLACK_SEND Application sends first response to SETUP CCMSK_CALLPROC_SEND message, either CALL_SETUP_ACK or CALL_PROCEEDING Firmware sends first response to SETUP message CCMSK_PROCEEDING Receiving CCEV_PROCEEDING Enabled CCMSK_PROGRESS Receiving CCEV_PROGRESSING Enabled CCMSK_SERVICE Receiving CCEV_SERVICE. When this event arrives, the application should respond with a status message using cc_SndMsg( ).
PAGE 247
sets the event mask cc_SetEvtMsk( ) Bitmask Type Action Default CCMSK_TMREXPEVENT Receiving the CCEV_TIMER event. This event is generated when some timer expires at the firmware in Layer 3. Timer ID, Call ID and the value of the timer are returned. Not enabled The action parameter may either set or reset the mask bit(s) as specified in the bitmask. Possible actions are shown in Table 25 below. Table 25.
PAGE 248
cc_SetEvtMsk( ) sets the event mask /* * using cc_ SetEvtMsk (devhdl,CCMSK_PROGRESS * | CCMSK_ALERT, CCACT_ADDMSK) to block the incoming ISDN * message ALERTING and PROGRESSING. Note that the devhdl is a * board level device. */ if ( cc_SetEvtMsk (devhdl, CCMSK_PROGRESS | CCMSK_ALERT, CCACT_ADDMSK) < 0 ) procdevfail(devhdl); /* continue the program. */ . . . . . if ( cc_Close(devhdl) < 0 ) printf(“Error closing device, errno = %d\n”, errno); procdevfail(devhdl); } int callfail(CRN crn) { LINEDEV ld; cc_CR
PAGE 249
sets the event mask ! • • cc_SetEvtMsk( ) See Also cc_SetParm( ) cc_GetEvtMsk( ) 237
PAGE 250
cc_SetInfoElem( ) Name: Reference: Inputs: Returns: Includes: Category: Mode: Technology: ! sets additional information elements int cc_SetInfoElem(linedev, iep) LINEDEV linedev • line device handle of the B channel board IE_BLK *iep • pointer to the information element buffer 0 on success < 0 on failure cclib.
PAGE 251
sets additional information elements ! cc_SetInfoElem( ) Example #include #include #include #include #include #include “srllib.h” “dtilib.h” “cclib.h” /* For Windows applications only */ typedef struct uui_type { unsigned char uui_id; unsigned char length; char data[128]; } USR_USR_INFO; /* This structure complies with CCITT Q.
PAGE 252
cc_SetInfoElem( ) sets additional information elements } int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf(“reason = %x - %s\n”,reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure.
PAGE 253
sets the minimum number of digits to be collected Name: Inputs: int cc_SetMinDigits(linedev, mindigits) LINEDEV linedev • device handle int mindigits • the minimum number of digits to be collected 0 on success < 0 on failure cclib.
PAGE 254
cc_SetMinDigits( ) #include #include #include #include #include #include “srllib.h” “dtilib.h” “cclib.h” sets the minimum number of digits to be collected /* For Windows applications only */ void main() { LINEDEV devhdl = 0; CRN crn = 0; char *devname = “dtiB1T1”; char dnis_buf[CC_ADDRSIZE]; if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf(“Error opening device: errno = %d\n”, errno); exit(1); } /* * using cc_SetMinDigits(linedev, mindigits) to set minimum * digits to be
PAGE 255
sets the minimum number of digits to be collected cc_SetMinDigits( ) int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf(“reason = %x - %s\n”,reason,msg); } ! Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.
PAGE 256
cc_SetParm( ) sets the default channel parameters Name: Inputs: Returns: Includes: Category: Mode: Technology: ! int cc_SetParm(linedev, parm_id, value) LINEDEV linedev • line device handle int parm_id • parameter identifier long value • parameter value 0 on success < 0 on failure cclib.h System tools synchronous BRI/2; BRI/SC; PRI (all protocols) Description The cc_SetParm( ) function sets the default channel parameters of the line device.
PAGE 257
sets the default channel parameters cc_SetParm( ) Table 26.
PAGE 258
cc_SetParm( ) sets the default channel parameters Define Description Possible return values USR_RATE User rate to use on bearer channel (layer 1 rate) ISDN_UR_EINI460 - determined by E bits in I.460 ISDN_UR_56000 - 56 kbits, V.6 ISDN_UR_64000 - 64 kbits, X.1 ISDN_UR_134 - 134.5 bits, X.1 ISDN_UR_12000 - 12 kbits, V.6 CALLED_NUM_TYPE Called number type EN_BLOC_NUMBER - number is sent en-block (in whole, not overlap sending) INTL_NUMBER - international number for international call.
PAGE 259
sets the default channel parameters cc_SetParm( ) Define Description Possible return values CALLING_NUM_PLAN Calling number plan Same values as CALLED_NUM_PLAN CALLING_PRESENTATION Calling presentation indicator PRESENTATION_ALLOWED allows the display of the calling number at the remote end CALLING_SCREENING Calling screening indicator field USER_PROVIDED - user provided, not screened (passes through) RECEIVE_INFO_BUF Multiple IE buffer; sets the size of the buffer, that is, the number of mes
PAGE 260
cc_SetParm( ) sets the default channel parameters /* * using cc_ SetParm(devhdl, CALLED_NUM_TYPE,EN_NAT_NUMBER) * to set the default value for “called party number type” to * ‘enbloc national’ type */ if ( cc_SetParm(devhdl, CALLED_NUM_TYPE, NAT_NUMBER) < 0 ) procdevfail(devhdl); else printf(“Parameter CALLED_NUM_TYPE has value: 0x%x\n”,value); if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); . . . . .
PAGE 261
sets the default channel parameters cc_SetParm( ) Error Code Description ERR_ISDN_LIB | E_ISBADTS Bad time slot ERR_ISDN_LIB | E_ISBADIF Bad interface number ERR_ISDN_LIB | E_ISBADPAR Bad input parameter ! • • See Also cc_GetParm( ) cc_SetParmEx( ) 249
PAGE 262
cc_SetParmEx( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! set parameters requiring variable data to be passed int cc_SetParmEx(linedev, parm_id, *parminfoptr) LINEDEV linedev • line device handle int parm_id • parameter identifier PARM_INFO *parminfoptr • pointer to the PARM_INFO block 0 on success < 0 on failure cclib.
PAGE 263
set parameters requiring variable data to be passed cc_SetParmEx( ) Parameter Description linedev: The line device handle. parm_id: The parameter identification. This function supports all of the parameters listed in Table 26 in the cc_SetParm( ) function description.
PAGE 264
cc_SetParmEx( ) set parameters requiring variable data to be passed { LINEDEV ldev = 0; CRN crn = 0; char *devname = “briS1T1”; /* device name for BRI station 1 timeslot 1 */ PARM_INFO *parminfo; /* variable data to be set */ char *DN = “99330008080”; . . . /* open the ISDN board device */ if ( cc_Open( &ldev, devname, 0 ) < 0 ) { printf(“Error opening device: errno = %d\n”, errno); exit(1); } /* initialize PARM_INFO structure */ parminfo.parmdatalen = strlen(DN); strcpy (parminfo.
PAGE 265
set parameters requiring variable data to be passed cc_SetParmEx( ) Error codes from the cc_SetParmEx( ) function include the following: Error Code Description ERR_ISDN_LIB | E_ISBADIF Bad interface number ERR_ISDN_LIB | E_ISBADTS Bad time slot ERR_ISDN_LIB | E_ISBADPAR Bad input parameter ! • • See Also cc_GetParmEx( ) cc_SetParm( ) 253
PAGE 266
cc_SetUsrAttr( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! sets the user attribute int cc_SetUsrAttr(linedev, usrattr) LINEDEV linedev • line device handle long usrattr • user attribute information 0 on success < 0 on failure cclib.h System tools synchronous BRI/2; BRI/SC; PRI Description The cc_SetUsrAttr( ) function sets the user attribute for a line device for later retrieval. The user attribute value can be a memory pointer used to identify a board and a channel on a board.
PAGE 267
sets the user attribute cc_SetUsrAttr( ) main() { int chan = 1; char devname[16]; . . . . if ( sr_enbhdlr( devhdl, CCEV_DISCONNECTED, discCallHdlr ) < 0 ) { printf( “dtiEnable for DISCONNECT failed: %s\n”, ATDV_ERRMSGP( SRL_DEVICE ) ); return( 1 ); } printf(devname,”dtiB1T%d”,chan); if ( cc_Open(&devhdl, devname, 0) < 0 ) { printf(“Error opening device: errno = %d\n”, errno); exit(1); } if ( cc_SetUsrAttr(devhdl, chan)) procdevfail(devhdl); . . . .
PAGE 268
cc_SetUsrAttr( ) sets the user attribute int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle, reason, &msg); printf(“”reason = %x - %s\n””,reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code.
PAGE 269
sends a frame to the data link layer Name: Inputs: int cc_SndFrame(linedev, sndfrmptr) LINEDEV linedev • line device handle for the D channel L2_BLK *sndfrmptr • pointer to the transmit frame buffer 0 on success < 0 on failure cclib.h Data link layer handling synchronous BRI/SC; PRI (excluding Q.SIG) Returns: Includes: Category: Mode: Technology: ! cc_SndFrame( ) Description The cc_SndFrame( ) function sends a frame to the data link layer.
PAGE 270
cc_SndFrame( ) ! sends a frame to the data link layer Example #include #include #include #include #include #include “srllib.h” “dtilib.h” “cclib.h” /* For Windows applications only */ /* Global variables */ typedef long int (*EVTHDLRTYP)( ); . . .
PAGE 271
sends a frame to the data link layer ! cc_SndFrame( ) Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 272
cc_SndMsg( ) sends a non-Call State related ISDN message to the network Name: Inputs: Returns: Includes: Category: Mode: Technology: ! int cc_SndMsg(crn, msg_type, sndmsgptr) CRN crn • call reference number int msg_type • ISDN message type IE_BLK *sndmsgptr • pointer to the information element (IE) block 0 on success < 0 on failure cclib.
PAGE 273
sends a non-Call State related ISDN message to the network cc_SndMsg( ) Table 27.
PAGE 274
cc_SndMsg( ) sends a non-Call State related ISDN message to the network if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); /* answer the call */ if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0) callfail(crn); /*initialize the SndMsg Block to send */ InitSndMsgBlk(&ie_blk); /* send INFORMATION IE data */ if ( cc_SndMsg(crn, SndMsg_Information, &ie_blk) == -1> { < 0 ) callfail(crn); } /* drop the call */ if ( cc_DropCall(crn, NORMAL_CLEARING, EV_SYNC) < 0 ) callfail(crn); /* release the CR
PAGE 275
sends a non-Call State related ISDN message to the network ! cc_SndMsg( ) Errors If the function returns a value < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 276
cc_SndNonCallMsg( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! sends a non-call related ISDN message int cc_SndNonCallMsg(boarddev, crn_type, msg_type, sndmsgptr) LINEDEV boarddev • board device int crn_type • ISDN call reference number type int msg_type • ISDN message type NONCRN_BLK *sndmsgptr • pointer to the message block containing non-call related ISDN message data 0 on success < 0 on failure cclib.
PAGE 277
sends a non-call related ISDN message cc_SndNonCallMsg( ) Parameter Description boarddev: The board device handle. crn_type: Specifies one of the following ISDN CRN types: • GLOBAL_CRN • NULL_CRN msg_type: Specifies one of the following ISDN message types: • SndMsg_Facility • SndMsg_Notify • SndMsg_FacilityACK • SndMsg_ServiceACK • SndMsg_FacilityREJ • SndMsg_Status • SndMsg_Information • SndMsg_StatusEnquiry The values for msg_type are defined in cclib.h.
PAGE 278
cc_SndNonCallMsg( ) sends a non-call related ISDN message { LINEDEV devhdl = 0; char *devname = "briS1"; /* device name for BRI board 1 station 1 */ NONCRN_BLK ie_blk; /* IE block to transmit custom data */ . . . /* open the ISDN board device */ if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf("Error opening device: errno = %d\n", errno); exit(1); } /* Initialize the values to transmit. For this example, the ISDN INFORMATION message will be transmitted with a Keypad IE.
PAGE 279
sends a non-call related ISDN message Error Code Description ERR_ISDN_LIB | E_ISBADIF Bad interface number ERR_ISDN_LIB | E_BADSTATE Bad state ERR_ISDN_LIB | E_ISBADTS Bad time slot ! • • cc_SndNonCallMsg( ) See Also cc_GetNonCallMsg( ) cc_SndMsg( ) 267
PAGE 280
cc_StartTrace( ) Name: Inputs: Returns: Includes: Category: Mode: Technology: ! start the capture of all D channel information int cc_StartTrace(boarddev, FileName) LINEDEV boarddev • board device handle controlling the D channel char *FileName • file name for the trace 0 on success < 0 on failure cclib.
PAGE 281
start the capture of all D channel information ! cc_StartTrace( ) Example #include #include #include #include #include #include “srllib.h” “dtilib.h” “cclib.h” /* For Windows applications only */ void main() { LINEDEV brddevhdl; /* device handle for D channel */ LINEDEV devhdl = 0; CRN crn = 0; char *devname = “dtiB1”; . . . if ( cc_Open(brddevhdl, devname, 0 ) < 0 ) exit(1); if ( cc_Open( &devhdl, devname, 0 ) < 0 ) { printf(“Error opening device: errno = %d\n”, errno
PAGE 282
cc_StartTrace( ) start the capture of all D channel information if ( cc_Close(brddevhdl) < 0 ) printf(“Error closing device, errno = %d\n”, errno); } int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf(“reason = %x - %s\n”,reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the rea
PAGE 283
forces the termination of a tone Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_StopTone( ) int cc_StopTone(devHdl, mode) int devHdl • channel device handle int mode • asynchronous/synchronous 0 on success <0 on failure cclib.h Global Tone Generation asynchronous/synchronous BRI/SC Description The cc_StopTone( ) function forces the termination of a tone that is currently playing on a channel. The function forces a channel that is in the playing state to become idle.
PAGE 284
cc_StopTone( ) forces the termination of a tone Use the SRL Event Management functions to handle the termination event. ! Cautions • If an I/O function terminates due to another reason before the cc_StopTone( ) function is issued, the reason for termination will not indicate that cc_StopTone( ) was called. • In asynchronous mode, if the application tries to stop a tone that is already stopped, the CCEV_STOPTONEFAIL termination event will be received.
PAGE 285
forces the termination of a tone cc_StopTone( ) /* * Play a Tone with its * Frequency1 = 330, Frequency2 = 460 * Amplitude at -10dB for both * Duration of infinity * This is a Panasonic Local Dial Tone. * */ if (cc_PlayTone( devHdl, &ToneParm, &tpt, EV_SYNC ) == -1 ){ printf( "Unable to Play the Tone\n" ); printf( "Lasterror = %d Err Msg = %s\n", cc_CauseValue( devHdl ), cc_ResultMsg( devHdl ) ); cc_Close( devHdl); exit( 1 ); } . . . . /* Force the channel idle.
PAGE 286
cc_StopTone( ) ! • • See Also cc_PlayTone( ) cc_ToneRedefine( ) 274 forces the termination of a tone
PAGE 287
stops the trace cc_StopTrace( ) Name: Inputs: Returns: int cc_StopTrace(boarddev) LINEDEV boarddev • board device handle 0 on success < 0 on failure cclib.h System control asynchronous BRI/2; BRI/SC; PRI (all protocols) Includes: Category: Mode: Technology: ! Description The cc_StopTrace( ) function stops the trace that was started using the cc_StartTrace( ) function, discards the trace information, and closes the file. Parameter Description boarddev: The line device handle of the D channel board.
PAGE 288
cc_StopTrace( ) } /* using cc_StartTrace() to begin the trace function and save it on file “istrace.log”. Note that the brddevhdl is a board level device. */ if ( cc_StartTrace(brddevhdl,”istrace.log”) < 0 ) procdevfail(brddevhdl); printf(“Waiting for call\n”); if ( cc_WaitCall(devhdl, &crn, NULL, -1, EV_SYNC) < 0 ) procdevfail(devhdl); if ( cc_AnswerCall(crn, 0, EV_SYNC) < 0 ) callfail(crn); . . . . .
PAGE 289
stops the trace ! cc_StopTrace( ) Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the reason code for the failure. The cc_ResultMsg( ) function can be used to interpret the reason code. Error codes are defined in the files ccerr.h, isdnerr.h, and isdncmd.h.
PAGE 290
cc_TermRegisterResponse( ) sends a response for CCEV_TERM_REGISTER Name: Inputs: Returns: Includes: Category: Mode: Technology: ! int cc_TermRegisterResponse(linedev, data_blk_ptr) LINEDEV linedev • board device handle TERM_BLK data_blk_ptr • pointer to the terminal initialization block data to be sent to the firmware 0 on success < 0 on failure isdncmd.h System tools asynchronous BRI/SC Description The cc_TermRegisterResponse( ) function sends a response for CCEV_TERM_REGISTER events.
PAGE 291
sends a response for CCEV_TERM_REGISTER cc_TermRegisterResponse( ) The data associated with the terminal initialization events can be retrieved using sr_getevtdatap( ) and casting the value to data types associated with the received event. The types of data structures that are used to cast the event-associated data are provided in Table 28 below. Table 28. Terminal Initialization Events and Data Structures Event Type of Data Structure CCEV_TERM_REGISTER SPID_BLK (See Section 6.11.
PAGE 292
cc_TermRegisterResponse( ) sends a response for CCEV_TERM_REGISTER LINEDEV DCHAN_CFG main () { lbuf; dchan_cfg; dchan_cfg.layer2_access = FULL_ISDN_STACK; /* full protocol */ dchan_cfg.switch_type = ISDN_BRI_NI1; /* NI1 switch */ dchan_cfg.switch_side = NETWORK_SIDE; /* Network Terminal */ dchan_cfg.number_of_endpoints = 1; /* one terminal */ dchan_cfg.user.tei_assignment = FIXED_TEI_TERMINAL; /* Fixed TEI terminal */ dchan_cfg.user.fixed_tei_value = 23; /* TEI assigned to terminal */ dchan_cfg.tmr.te.
PAGE 293
sends a response for CCEV_TERM_REGISTER cc_TermRegisterResponse( ) /***********************************************/ /* termRegisterHdlr - Term Register Handler */ /***********************************************/ int termRegisterHdlr( ) { int devindx; int dev = sr_getevtdev(); int len = sr_getevtlen(); void *datap = sr_getevtdatap(); char *message; int dchstate; int x, y; TERM_BLK termBlk; SPID_BLK *spidBlk; /* Extract * Event.
PAGE 294
cc_TermRegisterResponse( ) sends a response for CCEV_TERM_REGISTER Error Code Description ERR_ISDN_LIB | E_ISBADIF Bad interface number ERR_ISDN_LIB | E_ISNOMEM Cannot map or allocate memory ! See Also • 282 cc_SetEvtMsk( )
PAGE 295
redefines a call progress tone’s attributes Name: Inputs: int cc_ToneRedefine(devHdl, sigType, pToneParm, mode) LINEDEV devHdl • line device handle unsigned char sigType • Tone Signal Type toneParm *pToneParm • pointer to Tone Parameter structure int mode • asynchronous/synchronous 0 on success < 0 on failure cclib.
PAGE 296
cc_ToneRedefine( ) redefines a call progress tone’s attributes The following table shows the tone template table that resides in the firmware. Table 29.
PAGE 297
redefines a call progress tone’s attributes ! • • cc_ToneRedefine( ) Termination Events CCEV_TONEREDEFINE - indicates that the tone was successfully redefined CCEV_TONEREDEFINEFAIL - indicates that the function failed Use the SRL Event Management functions to handle the termination event. ! Cautions This function is not supported for the BRI/2 board or for PRI protocols. ! Example #include #include #include #include #include #include
PAGE 298
cc_ToneRedefine( ) redefines a call progress tone’s attributes */ if ( cc_Close( devhdl ) != 0 ) { printf( "Error closing devicd, errno= %d\n”, errno ); } /* Terminate the Program */ exit( 0 ); } The following example illustrates how to override the default tone that is played with an outgoing message. The example shows how the application uses the ALERTING message to direct the firmware to play the Busy tone instead of the default Ringback tone. #include
PAGE 299
redefines a call progress tone’s attributes * table. */ ie_buf.length = 3; ie_buf.data[0] = 0x34; ie_buf.data[1] = 0x01; ie_buf.data[2] = 0x04; cc_ToneRedefine( ) /* Signal IE ID */ /* Length of data in Signal IE */ /* Q.931 definition for Busy Tone On signal value */ if (cc_SetInfoElem( tsDevHdl, &ie_buf) < 0) { printf( "Error setting IE data : errno < %d\n”, errno ); exit( 1 ); } if (cc_AcceptCall( tsDevHdl, 0, EV_ASYNC) < 0) { printf( "Error sending Alerting message : errno < %d\n”, errno ); exit( 1 )
PAGE 300
cc_ToneRedefine( ) redefines a call progress tone’s attributes ERR_TONEFREQ1 Invalid value specified in parameter freq 1 ERR_TONEFREQ2 Invalid value specified in parameter freq 2 ERR_TONEAMP1 Invalid value specified in parameter amp1 ERR_TONEAMP2 Invalid value specified in parameter amp2 ERR_TONEON1 Invalid value specified in parameter toneOn1 ERR_TONEOFF1 Invalid value specified in parameter toneOff1 ERR_DURATION Invalid value specified in parameter duration ! See Also • 288 cc_PlayTone
PAGE 301
sets up conditions for processing an incoming call Name: Inputs: Returns: Includes: Category: Mode: Technology: ! cc_WaitCall( ) int cc_WaitCall(linedev, crnptr, waitcall_blkp, timeout, mode) LINEDEV linedev • device handle CRN *crnptr • pointer to call reference number WAITCALL_BLK *waitcall_blkp • for future use int timeout • amount of time to wait for calls unsigned long mode • synchronous or asynchronous 0 on success < 0 on failure cclib.
PAGE 302
cc_WaitCall( ) Parameter sets up conditions for processing an incoming call Description (EV_SYNC) mode. When and how the cc_WaitCall( ) function is issued depends on whether the function is called in synchronous or asynchronous mode. In synchronous mode, the cc_WaitCall( ) function cannot be stopped until timeout expires or until cc_Restart( ) is called from another process. The parameter crnptr will be assigned when cc_WaitCall( ) is terminated by the event CCEV_OFFERED.
PAGE 303
sets up conditions for processing an incoming call • cc_WaitCall( ) To receive incoming waiting calls, applications using the NTT protocol must use the cc_SetInfoElem( ) function to override the default Channel ID IE content. This ensures that the application complies with the NTT protocol specification requiring the first reply to the SETUP message to specify the B channel on which the call will proceed.
PAGE 304
cc_WaitCall( ) sets up conditions for processing an incoming call if ( cc_Close( devhdl ) < 0 ) printf(“Error closing device, errno = %d\n”, errno); } int callfail(CRN crn) { LINEDEV ld; cc_CRN2LineDev(crn,&ld); procdevfail(ld); } int procdevfail(LINEDEV handle) { int reason; char *msg; reason = cc_CauseValue(handle); cc_ResultMsg(handle,reason,&msg); printf(“reason = %x - %s\n”,reason,msg); } ! Errors If the function returns < 0 to indicate failure, use the cc_CauseValue( ) function to retrieve the re
PAGE 305
6. Data Structure Reference The data structures used by selected ISDN functions are described in this chapter. These structures are used to control the operation of functions and to return information.
PAGE 306
ISDN Software Reference for Linux and Windows 6.1. CC_RATE_U The CC_RATE_U data structure contains billing rate information for Vari-A-Bill services, which is set by the cc_SetBilling( ) function. The current structure, defined for AT&T only, is shown below: typedef union { struct } CC_RATE_U; ATT {long cents} Table 30. CC_RATE_U Field Descriptions Field Description ATT The billing rate for the current call. 6.2.
PAGE 307
6. Data Structure Reference Table 31. channel_id Descriptions and Values Field Description Values channel Specifies the channel to be used. NO_BCHAN – No B channel ANY_BCHAN – Any B channel DCHAN_IND – Non circuit switched channel mode rfu Specifies the channel mode to be used for the B channel, if a B channel is specified in the channel field. PREFERRED – B channel preferred Reserved for future use Not used EXCLUSIVE – B channel exclusive 6.3.
PAGE 308
ISDN Software Reference for Linux and Windows terminated string.
PAGE 309
6. Data Structure Reference Table 32. DCHAN_CFG Field Descriptions and Values Type layer2_access Description Boolean value used to configure the DSL for direct layer 2 access or for full stack access. Values #define LAYER_2_ONLY #define FULL_ISDN_STACK 0 1 Where: • LAYER_2_ONLY = ISDN access at layer 2 (If LAYER_2_ONLY is selected, no other parameters are required) • FULL_ISDN_STACK = ISDN access at L3 call control switch_type Basic rate protocol (switch type) for DSL.
PAGE 310
ISDN Software Reference for Linux and Windows Type Description switch_side Boolean value defining whether the DSL should be configured as the Network side (NT) or the User side (TE). Values #define USER_SIDE #define NETWORK_SIDE 0 1 Where: • USER_SIDE = User side of ISDN protocol • NETWORK_SIDE = Network side of ISDN protocol number_of_ endpoints 298 Number of logical data links to be supported. 1 to MAX_DLINK, where MAX_DLINK is currently set to 8.
PAGE 311
6. Data Structure Reference Type Description Values feature_controlA Firmware feature control field A. This is a bit mask field for setting features in the firmware. The following defines are used to configure the firmware features. The lowest two bits provide a combination of four possible settings for the TONE feature.
PAGE 312
ISDN Software Reference for Linux and Windows Type Description Values rfu_1 & rfu_2 Reserved for future use. Currently not used. tei_assignment Applies to User Side only. It specifies if the terminal has a fixed TEI or an autoassigning TEI. If it is fixed, then "fixed_tei_value" must be specified (see below). fixed_tei_value Defines the TEI to be used for a fixed TEI assigning terminal. auto_init_flag Boolean value defining whether or not the terminal is an auto initializing terminal.
PAGE 313
6. Data Structure Reference Type Description Values SPID Defines the assigned Service Provider Identifier (SPID) value for terminal initialization. It is only applicable to User side US switches. ASCII digit string limited to the digits 0-9 and limited in length to MAX_SPID_SIZE Where: MAX_SPID_SIZE = (20+1) (Required when auto_init_flag = AUTO_INIT_TERMINAL. Most North American switches require a SPID.) NOTE: When the SPID is set, it is assigned to both bearer channels associated with the D channel.
PAGE 314
ISDN Software Reference for Linux and Windows Type Description Values T3xx Defines the Layer 3 timer values. See Q.931 specification and corresponding switch specifications for exact definitions and default values for these timers. Not all timers are applicable to all of the switches. Specified values are in 10 millisecond increments. For example, a specified value of 100 is equivalent to 1 second.
PAGE 315
6. Data Structure Reference Table 33. DLINK Field Descriptions Field Description sapi The service access pointer identifier. (This field is zero for PRI.) ces The connection endpoint suffix. (This field is zero for PRI.) 6.5. DLINK_CFG The DLINK_CFG structure contains information about the data link logical link configuration block. The DLINK_CFG structure is retrieved using the cc_GetDLinkCfg( ) function.
PAGE 316
ISDN Software Reference for Linux and Windows Field Description the network side to establish the logical link if requested. • DATA_LINK_DISABLED - the firmware will attempt to release the logical link if it is currently established. The firmware will not allow the network side to establish the logical link if requested. protocol The protocol to be used on this logical link. For instance: • DATA_LINK_PROTOCOL_Q931 - indicates that the link is to be used as an ISDN connection-oriented logical link.
PAGE 317
6. Data Structure Reference 6.7. L2_BLK The L2_BLK structure is used to send and receive layer 2 information to an ISDN interface using the cc_GetFrame( ) and cc_SndFrame( ) functions. The structure is defined as follows: #define MAXLEN_IEDATA 254 typedef struct { char sapi; char ces; short length; char data[MAXLEN_DATA]; } L2_BLK, *L2_BLK_PTR; Table 36. L2_BLK Field Descriptions Field Description sapi The Service Access Point Identifier (applies to BRI only, set to 0 for PRI).
PAGE 318
ISDN Software Reference for Linux and Windows unsigned char BC_xfer_rate; unsigned char usrinfo_layer1_protocol; unsigned char usr_rate; unsigned char destination_number_type; unsigned char destination_number_plan; unsigned char destination_sub_number_type; unsigned char destination_sub_number_plan; char destination_sub_phone_number[MAXPHONENUM]; unsigned char origination_number_type; unsigned char origination_number_plan; char origination_phone_number[MAXPHONENUM]; unsigned char origination_sub_number_typ
PAGE 319
6. Data Structure Reference Table 37. MAKECALL_BLK Parameter ID Definitions Parameter Description Supported values BC_xfer_cap Bearer channel information transfer capability. BEAR_CAP_SPEECH - speech BEAR_CAP_UNREST_DIG unrestricted digital data BEAR_REST_DIG - restricted digital data NOTE: The value specified by cc_SetParm( ) is used if this element is set to ISDN_NOTUSED.
PAGE 320
ISDN Software Reference for Linux and Windows Parameter Description Supported values usrinfo_layer1_protocol Layer 1 protocol to use on bearer channel ISDN_UIL1_CCITTV.110 - CCITT standardized rate adaptation V.110) ISDN_UIL1_G711uLAW recommendation G.711 u-Law ISDN_UIL1_G711ALAW recommendation G.711 a-Law ISDN_UIL1_G721ADCPM recommendation G.721 32 kbits/s ADCPM and recommendation I.460 ISDN_UIL1_G722G725 recommendation G.772 and G.725 7kHz ISDN_UIL1_H261 recommendation H.
PAGE 321
6. Data Structure Reference Parameter Description Supported values usr_rate User rate to use on bearer channel (layer 1 rate) ISDN_UR_EINI460 - determined by E bits in I.460 ISDN_UR_56000 - 56 kbits, V.6 ISDN_UR_64000 - 64 kbits, X.1 ISDN_UR_134 - 1345 kbits, X.1 ISDN_UR_12000 - 12 kbits, V.6 NOTE: This element must be set to ISDN_NOTUSED if it is not to be used in the setup message.
PAGE 322
ISDN Software Reference for Linux and Windows Parameter Description Supported values destination_number_plan Called party number plan UNKNOWN_NUMB_PLAN unknown new plan ISDN_NUMB_PLAN ISDN/telephony - E.164/E.163 (accepted by most networks) TELEPHONY_NUMB_PLAN telephony numbering plan - E.164 PRIVATE_NUMB_PLAN - private numbering plan NOTE: The value specified by cc_SetParm( ) is used if this element is set to ISDN_NOTUSED.
PAGE 323
6. Data Structure Reference Parameter Description Supported values destination_sub_phone_ number [MAXPHONENUM] Called party sub-phone number ASCII digit string of MAXPHONENUM. If the first character is set to ISDN_NOTUSED, the number plan and type are ignored and the destination_sub_phone_number IE will not be sent. NOTE: This element must be set to ISDN_NOTUSED if it is not to be used in the setup message.
PAGE 324
ISDN Software Reference for Linux and Windows Parameter Description Supported values origination_sub_phone_ number [MAXPHONENUM] Calling party sub-phone number ASCII digit string of MAXPHONENUM. If the first character is set to ISDN_NOTUSED, the number plan and type are ignored and the origination_sub_phone_number IE will not be sent. NOTE: This element must be set to ISDN_NOTUSED if it is not to be used in the setup message.
PAGE 325
6.
PAGE 326
ISDN Software Reference for Linux and Windows Parameter Description Supported values NFACILITY_ELEM *nsfc_bufp Network specific facility element Not used, set to NULL. See the cc_SetInfoElem( ) function to add custom IEs to the MAKECALL Block. NOTE: This element must be set to NULL if it is not to be used in the setup message. NOTE: The facility_feature_service and facility_coding_value data elements must be paired to support the specific feature or service requested from the network.
PAGE 327
6. Data Structure Reference makecall_blk.isdn.facility_coding_value = 0xFF; makecall_blk.isdn.usrinfo_bufp = NULL; makecall_blk.isdn.nsfc_bufp = NULL; For more on the MAKECALL_BLK structure, see the cc_MakeCall( ) function description in Chapter 5. ISDN Function Reference. 6.9. NONCRN_BLK The NONCRN_BLK structure contains information related to a GLOBAL or NULL call reference number (CRN). The messages are sent to the network using the SndNonCallMsg( ) function.
PAGE 328
ISDN Software Reference for Linux and Windows 6.10. PARM_INFO The PARM_INFO structure contains parameters that contain variable data that is passed from the firmware. The variable data is retrieved using the cc_GetParmEx( ) function and set using the cc_SetParmEx( ) function. The structure is defined as follows: typedef struct { byte parmdatalen; unsigned char parmdata [256]; } PARM_INFO, *PARM_INFO_PTR; /* maximum length of 256 bytes for ISDN information */ Table 39.
PAGE 329
6. Data Structure Reference Table 40. SPID_BLK Field Descriptions Field Description data_link The DLINK data structure; see Section 6.4. DLINK. initializing_term The type of initializing terminal. SPID The Service Profile Interface ID 6.12. TERM_BLK The TERM_BLK data structure contains information regarding the application's response to the CCEV_TERM_REGISTER event. The response is sent using the cc_TermRegisterResponse( ) function.
PAGE 330
ISDN Software Reference for Linux and Windows Table 41. TERM_BLK Field Descriptions Field Description data_link The DLINK data structure; see Section 6.4. DLINK. ack_type The type of acknowledgement to be passed to the firmware. The settings are: • ISDN_OK - to send a Positive acknowledgment • ISDN_ERROR - to send a Negative acknowledgment cause_value The Cause Value defined in isdncmd.h. (For a listing of Cause Values, see Section 7.2.1. Cause/Error Codes from the ISDN Firmware.
PAGE 331
6. Data Structure Reference 6.13. TERM_NACK_BLK The TERM_NACK_BLK data structure is used to cast terminal initialization event data after a CCEV_RCVTERMREG_NACK event is received. TERM_NACK_BLK contains the cause value for the event, indicating why the terminal initialization request was rejected by the network. The data structure is defined as follows: /* * Structure for CCEV_RCVTERMREG_NACK Event. */ typedef struct { DLINK data_link; byte cause_value; } TERM_NACK_BLK; Table 42.
PAGE 332
ISDN Software Reference for Linux and Windows Table 43. Cause Values Associated with CCEV_RCVTERMREG_NACK Cause Value Q.850 Description Meaning 0x26 Network out of order Used when the network has removed the TEI, causing the data link to go down. 0x63 Information element/parameter non-existent or not implemented Switch does not support endpoint initialization. 0x64 Invalid information element contents SPID was most likely coded incorrectly.
PAGE 333
6. Data Structure Reference Table 44. ToneParm Field Descriptions Field Description duration specifies the duration of the tone in 10 ms units. The range is 1 65535. Set to -1 to play forever. freq1 specifies the frequency of the tone. The range is 200 - 3100 Hz. amp1 specifies the amplitude of the tone. The range is -40 - +3 dB. freq2 specifies the frequency of the tone. The range is 200-3100 Hz. amp2 specifies the amplitude of the tone. The range is -40 - +3 dB.
PAGE 334
ISDN Software Reference for Linux and Windows Table 45. USPID_BLK Field Descriptions Field Description data_link The DLINK data structure; see Section 6.4. DLINK. usid User Service Identifier. The range is 01 – FF. 00 signifies default. tid Terminal Identifier. The range is 01 – 63. 00 signifies that the firmware is to provide a default. interpreter Specifies how the usid and tid values are to be interpreted.
PAGE 335
6. Data Structure Reference Table 46. USRINFO_ELEM Field Descriptions Field Description length The length of the user information element protocol discriminator The protocol discriminator usrinformation The user-to-user information (UUI) data 6.17. WAITCALL_BLK This structure is reserved for future use. The pointer to the WAITCALL_BLK structure in the argument list for the cc_WaitCall( ) function must be set to NULL.
PAGE 336
PAGE 337
7. ISDN Events and Errors This chapter describes the events and error/cause codes that are returned by the Dialogic ISDN library functions. The function descriptions in Chapter 5. ISDN Function Reference list the possible error codes and, for asynchronous functions, the termination events returned by the function. 7.1.
PAGE 338
ISDN Software Reference for Linux and Windows Table 47. Termination Events Termination Event Returned After: Indicates: Reference: CCEV_ACCEPT cc_AcceptCall( ) ALERTING message has been sent to the network. CRN CCEV_ANSWERED cc_AnswerCall( ) CONNECT message has been sent to the network. CRN CCEV_CONNECTED cc_MakeCall( ) CONNECT message has been received from the network. CRN CCEV_DROPCALL cc_DropCall( ) DISCONNECT message has been sent to the network.
PAGE 339
7. ISDN Events and Errors Termination Event Returned After: Indicates: Reference: information about why the request was rejected. CCEV_MOREDIGITS cc_GetMoreDigits( ) Requested number of digits has been received. Use cc_GetDNIS( ) to retrieve digits. CRN CCEV_OFFERED cc_WaitCall( ) SETUP message has been received. Use cc_GetCallInfo( ) to retrieve information about the event. CRN CCEV_PLAYTONE cc_PlayTone( ) User-defined tone successfully played.
PAGE 340
ISDN Software Reference for Linux and Windows Termination Event Returned After: Indicates: Reference: CCEV_RESTARTFAIL Failure of cc_Restart( ) Typically, this event is triggered by an incorrect state of a line device. The application may use cc_ResultValue( ) after this event is received to verify the reason for failure. Line Device Handle CCEV_RETRIEVEACK cc_RetrieveCall( ) A RETRIEVE CALL COMPLETE acknowledge message was received from the network.
PAGE 341
7. ISDN Events and Errors Termination Event Returned After: Indicates: Reference: for the call has been acknowledged by the network. This event is used only with the AT&T Vari-A-Bill feature. CCEV_ SETCHANSTATE cc_SetChanState( ) The B channel is placed in the requested state. Line Device Handle CCEV_STOPTONE cc_StopTone( ) The tone operation was terminated. Line Device Handle CCEV_STOPTONEFAIL Failure of cc_StopTone( ) The request to terminate the playing of a tone failed.
PAGE 342
ISDN Software Reference for Linux and Windows Termination Event Returned After: Indicates: Reference: CCEV_TONEREDEFINE cc_ToneRedefine( ) The tone(s) in the firmware tone template table were successfully redefined. Line Device Handle CCEV_ TONEREDEFINEFAIL Failure of cc_ToneRedefine( ) The request to redefine tone(s) in the firmware tone template table failed. Line Device Handle 7.1.2. Unsolicited Events Table 48 lists the events that are triggered by external signals.
PAGE 343
7. ISDN Events and Errors External Event Indicates: SndMsg_Drop message type via the cc_SndMsg( ) function. The CCEV_CONFDROP event has two different meanings that depend upon the type of call: Two-party call - the event is a request to disconnect the call. The application should respond by issuing a cc_DropCall( ). Conference call - the event is a request to remove the last party that was added to the conference.
PAGE 344
ISDN Software Reference for Linux and Windows External Event Indicates: or RELEASE message has been received by the application. This event may be received in any state except IDLE, DISCONNECTED, or NULL. The application must send a cc_DropCall( ) after this event is received. Use the cc_GetCallInfo( ) function to retrieve additional information about the event. CCEV_DIVERTED NAM with divert information has been received by the application.
PAGE 345
7. ISDN Events and Errors External Event Indicates: is associated with all calls on the device. Upon receipt of this event, the application may issue a cc_GetNonCallMsg( ) function to retrieve the data into its local structure. CCEV_FACILITYNULL An ISDN_FACILITY message was received containing a Dummy (NULL) CRN. Upon receipt of this event, the application may issue a cc_GetNonCallMsg( ) function to retrieve the data into its local structure.
PAGE 346
ISDN Software Reference for Linux and Windows External Event Indicates: received frame. It is the application’s responsibility to analyze the contents of the frame. CCEV_L2NOBFFR There are no buffers available to save the incoming frame. CCEV_NOFACILITYBUF There are no buffers available to store the Network Facility Information Element (IE). This event can be ignored. The event is received for every incoming ISDN message that contains the Network Facility IE.
PAGE 347
7. ISDN Events and Errors External Event Indicates: application should use cc_GetCallInfo( ) to retrieve the NSI string(s). CCEV_ISDNMSG An undefined ISDN message has been received by the application. CCEV_PROCEEDING An ISDN message has been received by the application. By default, the firmware will send this event to the application. The application may clear the CCMSK_PROCEEDING bit to block this event. CCEV_PROGRESSING A PROGRESS message has been received by the application.
PAGE 348
ISDN Software Reference for Linux and Windows External Event Indicates: CCEV_REDIRECT The firmware has reset its call state to Overlap Sending. The request to redirect was made by the switch to solicit more out-ofband digits. The CCEV_REDIRECT event pertains only to a Custom BRI 5ESS switch type configured as the TE (User side). A station configured as an NT (Network side) may generate a message, via the cc_SndMsg( ) function, causing this event.
PAGE 349
7. ISDN Events and Errors External Event Indicates: CCEV_TERM_REGISTER An unsolicited event indicating that some action is required by the switch for the North American terminal initialization procedure. The application must respond to the event using the cc_TermRegisterResponse( ) function to either accept or reject the request to initialize the terminal. A Service Profile Identifier (SPID) value is associated with the event.
PAGE 350
ISDN Software Reference for Linux and Windows External Event Indicates: in response to a cc_SndMsg( ) function call, from the far end, in which the msg_type is SndMsg_UsrInformation. Use the cc_GetCallInfo( ) function to retrieve the UUI. 7.2. Error Handling The ISDN library functions return a value indicating success (0) or failure (<0) of the function call. cc_CauseValue( ) is used to retrieve the reason for the failure.
PAGE 351
7. ISDN Events and Errors There are three cause/error locations, as described in Table 49 below. Table 49. Cause/Error Locations Cause/Error Location Return Conditions Firmware (ERR_ISDN_FW) Returned when there is a firmware-related cause/error. Firmware errors are listed in the isdncmd.h file. (See Section 7.2.1. Cause/Error Codes from the ISDN Firmware.) Network (ERR_ISDN_CAUSE) Returned with a CCEV_DISCONNECTED event. The application uses cc_ResultValue( ) to retrieve the cause value.
PAGE 352
ISDN Software Reference for Linux and Windows Table 50. ISDN Firmware Error Codes Error Name Value Description ISDN_OK 0x00 (0) Normal returned code. ISDN_BADDSL 0x101 (257) Wrong DSL (Digital Subscriber Line) number. Will not occur in non-NFAS environment. ISDN_BADTS 0x102 (258) Bad time slot. Will occur when a second call is placed on an already active channel. ISDN_BADARGU 0x103 (259) Bad internal firmware command argument(s), possibly caused by a bad function parameter.
PAGE 353
7. ISDN Events and Errors Error Name Value Description ISDN_BADCALLID 0x10E (270) Bad call ID. No call record exists for specified call ID. ISDN_BADSTATE 0x10F (271) Cannot accept the event in the current state. ISDN_BADSS 0x110 (272) Unspecified service state was requested. ISDN_TSBUSY 0x111 (273) Time slot already in use. ISDN_NOAVAIL 0x112 (274) No more memory available to accept a new call request. ISDN_LINKFAIL 0x113 (275) Layer 2 data link failed.
PAGE 354
ISDN Software Reference for Linux and Windows Error Name Value Description ISDN_MISSING_SPID 0x128 (296) Service Profile Interface ID (SPID) not provided for North American terminal. Cause/Error Codes from the ISDN Firmware for cc_SetBilling( ) The following table provides error codes from the firmware that apply only to the cc_SetBilling( ) function. The error values include the hex followed by the decimal in parentheses. Table 51.
PAGE 355
7. ISDN Events and Errors standards. Not all cause codes are universally supported across switch types. Before using a particular cause code, compare its validity with the appropriate switch vendor specifications. Table 52. ISDN Network Error Codes Error Name Hex Value (Decimal) Q.
PAGE 356
ISDN Software Reference for Linux and Windows Error Name Hex Value (Decimal) Q.
PAGE 357
7. ISDN Events and Errors Error Name Hex Value (Decimal) Q.
PAGE 358
ISDN Software Reference for Linux and Windows Error Name Hex Value (Decimal) Q.
PAGE 359
7. ISDN Events and Errors 7.2.3. Cause/Error Codes from the ISDN Library The following table provides the error/cause codes located in the ISDN library. Error values include the hex followed by the decimal in parentheses. Table 53. ISDN Library Error Codes Error Name Value Description E_ISSUCC 0x00 (0) Message acknowledged. E_ISREADY 0x301 (769) Board not ready. E_ISCONFIG 0x302 (770) Configuration error. E_ISNOINFO 0x303 (771) Information not available.
PAGE 360
ISDN Software Reference for Linux and Windows Error Name Value (905) Description returns when the application either tries to stop a non-existent trace function or to start the trace function twice on the same D channel. E_ISBADPAR 0x38A (906) Bad input parameter(s). E_ISBADCALLID 0x3C1 (961) Bad call identifier. E_ISBADCRN 0x3C2 (962) Bad call reference number. E_ISNOINFOBUF 0x3C3 (963) The information requested in the cc_GetCallInfo( ) function call is not available.
PAGE 361
8. Application Guidelines This chapter offers advice and suggestions for programmers designing and coding Dialogic ISDN applications in a Windows or a LINUX environment. Specific guidelines for developing ISDN applications are provided. Topics include the following: • general guidelines • handling events, errors and alarms • programming considerations • diagnostic tools NOTE: These guidelines are not intended as a comprehensive guide to developing or debugging Dialogic ISDN applications. 8.1.
PAGE 362
ISDN Software Reference for Linux and Windows 8.1.2. Header Files Various header files must be included in an ISDN application. These files provide the equates, structures, and prototypes needed to compile application programs. The following header files are typically used for ISDN call control applications: • cclib.h - ISDN Call Control library defines • isdncmd.h - ISDN command structure defines • isdnlib.h - ISDN library headers • isdnerr.h - ISDN error defines • srllib.
PAGE 363
8. Application Guidelines Reference and the Voice Software Reference - Standard Runtime Library for the appropriate operating system for more information. 8.2.1. Handling Errors Each Dialogic ISDN API library function returns a value < 0 on failure. Be sure to check any call to a Dialogic ISDN API library function for a return value that indicates an error. The following code samples demonstrate how to handle errors done in asynchronous and synchronous modes.
PAGE 364
ISDN Software Reference for Linux and Windows The application may also use the Dialogic function calls to retrieve additional event or error information. For example: • ATDV_NAMEP( ) • ATDV_LASTERR( ) • ATDV_ERRMSGP( ) • sr_getevtdatap( ) • sr_getevtlen( ) 8.2.3. Handling Alarms All ISDN trunk alarms are reported to and handled by the application in the same way as DTI trunk alarms.
PAGE 365
8. Application Guidelines Each BRI structure is composed of one D channel and two B (bearer) channels. A BRI board device, such as briS1, is defined as a station and controls the D channel the same way as a PRI board device. A BRI time slot device, such as briS1T1, is defined as a bearer channel under a station and is handled the same way as a PRI line device. NOTE: For BRI, the protocol must be configured at initialization using the cc_SetDChanCfg( ) function. See Section 8.4.1.
PAGE 366
ISDN Software Reference for Linux and Windows makecall_blk.isdn.origination_sub_number_type = 0xFF; makecall_blk.isdn.origination_sub_phone_number[0] = NULL; makecall_blk.isdn.origination_phone_number[0] = NULL; makecall_blk.isdn.facility_feature_service = 0xFF; makecall_blk.isdn.facility_coding_value = 0xFF; makecall_blk.isdn.usrinfo_bufp = NULL; makecall_blk.isdn.nsfc_bufp = NULL; For more on the MAKECALL_BLK structure, see Section 6.8.
PAGE 367
8. Application Guidelines Table 55. NON-LOCKING Shift IEs - Type 1 Type of IE Value Codeset Network Specific Facilities 0x20 0 Shift 0x9E 6 (NON-LOCKING) IPU 0x76 6 Display 0x28 0 Signal 0x34 0 Table 56. Single Byte IEs - Type 2 Type of IE Value Codeset Network Specific Facilities 0x20 0 Sending Complete 0xA1 0 (Single Byte IE) Display 0x28 0 Signal 0x34 0 Assumption 3: A LOCKING Shift IE must be placed after all the IEs when a lower codeset is included.
PAGE 368
ISDN Software Reference for Linux and Windows Type of IE Value Codeset Shift 0x94 4 (LOCKING) IPU 0x76 4 Shift 0x9E 6 (NON-LOCKING) DDD 0x55 6 SSS 0x44 4 Shift 0x97 7 (LOCKING) ABC 0x77 7 DEF 0x77 7 Table 58.
PAGE 369
8. Application Guidelines Type of IE Value Codeset DEF 0x77 7 Assumption 4: User-supplied IEs (with the exception of CHANNEL_ID_IE, see below) take precedence over the Firmware-defined IEs, even those that are in private IE parts. Assumption 5: The CHANNEL_ID_IE will always be taken from the Firmwaredefined section.
PAGE 370
ISDN Software Reference for Linux and Windows NOTE: North American protocols often require TE devices configured as the User side to transmit a Service Profile Identifier (SPID), which is then acknowledged by the switch. The SPID is programmed using the cc_SetDChanCfg( ) function. See Section 8.4.2. BRI/SC Terminal Initialization below for more information.
PAGE 371
8. Application Guidelines • CCEV_RCVTERMREG_ACK • CCEV_RCVTERMREG_NACK North American protocols often require TE devices to be fully initializing. This means that the Service Profile Identifier (SPID) must be transmitted and acknowledged by the switch. For the User side, the SPID is programmed in the D channel configuration using cc_SetDChanCfg( ). When the SPID is accepted or rejected by the switch, the application receives either a CCEV_RCVTERMREG_ACK or a CCEV_RCVTERMREG_NACK, respectively.
PAGE 372
ISDN Software Reference for Linux and Windows The cc_SetDChanCfg( ) function is used to configure the firmware tone control. In addition, the application can change the values in the firmware tone template table (see Table 29. Tone Template Table) using the cc_ToneRedefine( ) function. To apply user-defined tones (that is, tones other than those in the firmware tone template table), the application uses the cc_PlayTone( ) and cc_StopTone( ) functions.
PAGE 373
8. Application Guidelines isdiag Where: is the board number 1 through 4 (dti1 - dti4) is the channel time slot number (1-23 for T-1, 1-30 for E-1, 1-2 for BRI) is the type of board: “t” for T-1, “e” for E-1, “b” for BRI/SC, “b2” for BRI/2) is the Bus type; “p” for PEB and “s” for SCbus) indicates whether waitcall is issued at startup; “r” is for trace mode (no waitcall issued at startup).
PAGE 374
ISDN Software Reference for Linux and Windows • • • • • • Restart ISDN line devices and set to WaitCall state for receiving inbound ISDN calls Change the current ISDN line device number Use a shell to access DOS environment form the ISDIAG application Hold/retrieve calls (BRI protocols and DPNSS and Q.SIG PRI protocols) Set supplementary DPNSS/Q.SIG services (intrusion, local diversion, remote diversion, virtual calls for inbound/outbound) Use an online Help menu that describes the main menu options 8.5.
PAGE 375
8. Application Guidelines Table 59. ISDTRACE Example File Receive Transmit NET5 RECEIVE Response=0 SAPI=0x00 TEI=0x00 0x01 0x09 Receive Ready TRANSMIT Command=0 TEI=0x00 0x01 0x0b SAPI=0x00 Receive Ready TRANSMIT Response=1 SAPI=0x00 TEI=0x00 0x08 0x0a Information Dest=0 CR=0x0002 SETUP(0x05) 1: SENDING COMPLETE(0xa1) 1: BEARER CAPABILITY(0x04) 2: IE Length(0x02) 3: 1------- Extension Bit -00----- Coding Standard ---00000 Info. Transfer Cap.
PAGE 376
ISDN Software Reference for Linux and Windows Receive Transmit 0x44 User Information 0x69 User Information 0x61 User Information RECEIVE Command=1 TEI=0x00 0x01 0x0a SAPI=0x00 Receive Ready RECEIVE Response=0 SAPI=0x00 TEI=0x00 0x0a 0x0a Information Orig=1 CR=0x8002 CALL PROCEEDING(0x02) 1: CHANNEL ID(0x18) 2: IE Length(0x03) 3: 1------- Extension Bit -0------ Interface ID Present --1----- Interface Type ---0---- Spare ----1--- Preferred/Exclusive -----0-- D-Channel Indicator ------01 Info.
PAGE 377
8.
PAGE 378
PAGE 379
Appendix A - Call Control Scenarios This appendix contains the following ISDN call control scenarios in the order listed: • BRI Channel Initialization and Start Up (User Side) • BRI Channel Initialization and Start Up (Network Side) • PRI Channel Initialization and Start Up • Normal Call Establishment and Termination • • • • • • Call Rejection • • • • • Outgoing call rejected by the network Incoming call rejected by the application Glare (call collision) Simultaneous disconnect (any state) Initi
PAGE 380
ISDN Software Reference for Linux and Windows BRI Channel Initialization and Start Up (User Side) Synchronous or Asynchronous Programming Application Device Driver cc_SetDChanCfg( ) --> State Firmware Return with line device <-Initialize --> Configures protocol and BRI station D channel settings CCEV_D_CHAN_ STATUS <-- Establish Data Link (if Terminal = North American) (if Terminal = North American) SPID information --> CCEV_RCVTERMREG_AC K (if positive) CCEV_RCVTERMREG_NA CK (if negative) <-ISDN
PAGE 381
Appendix A - Call Control Scenarios BRI Channel Initialization and Start Up (Network Side) Synchronous or Asynchronous Programming Application Device Driver Firmware Return with line device <-Initialize --> Configures protocol and BRI station D channel settings DATA_LINK_UP (if Terminal = North American) User toNetwork NULL cc_Open( ) --> cc_SetDChanCfg( ) --> State CCEV_TERM_REGISTE SME_TERM_REGIST R ER <-<-CCEV_RCVTERMREG_A Positive or cc_TermRegisterRespons CK (if positive negative e( ) ack)
PAGE 382
ISDN Software Reference for Linux and Windows PRI Channel Initialization and Start Up Synchronous or Asynchronous Programming Application Device Driver State Firmware Network OOS at power up F/W place B channel to "IN" service state *Maintenance --> F/W resets all B channel in to idle state Call blocked MT_ACK <-**Restart --> Restart_ACK <-- NULL cc_Open( ) --> Return with line device <-ISDN_Unblock_Ts --> Incoming call ***cc_WaitCall( unblocked ) --> * Optional for TE/Windows implementation.
PAGE 383
Appendix A - Call Control Scenarios Normal Call Establishment and Termination This section provides scenarios of normal basic call control procedures for call establishment and termination. Both Facility Associated Signaling (FAS) and Non-Facility Associated Signaling (NFAS) cases are illustrated. Network initiated call (inbound call) Synchronous Programming: The incoming call terminates the cc_WaitCall( ) function. cc_WaitCall( ) must be issued for the next incoming call after the last call is terminated.
PAGE 384
ISDN Software Reference for Linux and Windows Application Device Driver cc_AcceptCall( ) (option) --> Call_Alert --> cc_AnswerCall( ) --> termination of cc_AcceptCall() <-Call_Connect --> State ACCEPTED termination of CONNECTED cc_AnswerCall() <-* Application may connect a voice resource channel to the B channel.
PAGE 385
Appendix A - Call Control Scenarios CCEV_ANSWERCALL CONNECTED CALL_CONNECT_ACK <-<-* Application may connect a voice channel to the B channel.
PAGE 386
ISDN Software Reference for Linux and Windows Network terminated call Firmware-controlled disconnect: This is the default setting for parameter 24 in the *.
PAGE 387
Appendix A - Call Control Scenarios CCEV_DISCONNECTE D <-- DISCONNECTED CALL_DISCONNECTED <-Release --> Rel_Comp <-- cc_DropCall( ) --> cc_ReleaseCall( ) --> Call_Disconnecte d (cause value =0) --> CCEV_DROPCALL <-Call_Dealloc --> IDLE CALL_CLEARED <-NULL Driver releases F/W releases CRN CRN CALL_DEALLOC_ACK Return <-*In the firmware-controlled disconnect process, the firmware ensures that the RELEASE is sent out to the network immediately after the DISCONNECT is received.
PAGE 388
ISDN Software Reference for Linux and Windows Host-controlled disconnect: Parameter 24 in the *.
PAGE 389
Appendix A - Call Control Scenarios Rel_Comp <-* In the host-controlled disconnect process, the RELEASE message gets sent out only when the Host does a cc_ReleaseCall( ).
PAGE 390
ISDN Software Reference for Linux and Windows Application initiated call (outbound call) Synchronous Programming Application Device Driver State Firmware Network CALL_OUTGOING --> *B channel cut thru CALL_PROCEEDING <-PI=1 (interworking with a non-ISDN has occurred within the network) CALL_PROGRESS <-PI=2 (the destination user is not ISDN ) CALL_PROGRESS <-PI=8 (in-band information is now available) CALL_PROGRESS <-CALL_ALERT <-- Set Up --> Proceeding <-- NULL cc_MakeCall( ) --> CRN assigned Call_O
PAGE 391
Appendix A - Call Control Scenarios Application Device Driver State Firmware Network CCEV_PROCEEDING (if requested not masked) <-CCEV_PROGRESSING (if requested not masked) <-- DIALING *B channel cut thru CALL_PROCEEDING <-PI=1 (interworking with a non-ISDN has occurred within the network) CALL_PROGRESS <-PI=2 (the destination user is not ISDN ) CALL_PROGRESS <-PI=8 (in-band information is now available) CALL_PROGRESS <-CALL_ALERT <-- Proceeding <-- CCEV_PROGRESSING (if requested not masked) <-Appl
PAGE 392
ISDN Software Reference for Linux and Windows Aborting cc_MakeCall( ) When a B channel negotiation is used in call setup, the application must select CCEV_PROCEEDING as the termination point for the cc_MakeCall( ) function or use the asynchronous programming model. The following scenario illustrates a case where the application uses an asynchronous model to abort the cc_MakeCall( ) attempt.
PAGE 393
Appendix A - Call Control Scenarios Application Terminated Call Firmware-controlled disconnect: This is the default setting for parameter 24 in the *.
PAGE 394
ISDN Software Reference for Linux and Windows Release <-CCEV_DROPCALL <-- cc_ReleaseCall ( ) --> Call_Dealloc --> Driver releases CRN Return <-- 382 CALL_CLEARED <-RELEASE_DONE --> NULL F/W releases CRN CALL_DEALLOC_ACK <-- Rel_Comp -->
PAGE 395
Appendix A - Call Control Scenarios Host-controlled disconnect: This is the default setting for parameter 24 in the *.
PAGE 396
ISDN Software Reference for Linux and Windows cc_ReleaseCall ( ) --> Call_Dealloc --> Driver releases CRN Return <-- 384 RELEASE_DONE --> NULL F/W releases CRN CALL_DEALLOC_ACK <-- Rel_Comp -->
PAGE 397
Appendix A - Call Control Scenarios Call Rejection Outgoing call rejected by the network Synchronous Programming Application Device Driver State cc_MakeCall( ) --> CRN assigned Call_Outgoing --> DIALING CCEV_ DISCONNECTED <-ISDN_Block_Ts (sync mode only) --> *DISCONNECTED CCEV_DROPCALL cc_ReleaseCall ( ) --> Call_Dealloc --> Network CALL_OUTGOING --> CALL_REJECTION <-- Set up --> Rel_Comp <-- Incoming call blocked IDLE cc_DropCall( ) Firmware B channel disconnected CALL_DISC CALL_CLEARED <
PAGE 398
ISDN Software Reference for Linux and Windows Incoming call rejected by the application Synchronous Programming Application Device Driver State Firmware cc_WaitCall( ) --> ISDN_Unblock_Ts --> NULL Incoming call unblocked CRN assigned termination of cc_WaitCall( ) <-- OFFERED *B channel cut-thru CALL_PROCEEDING --> CALL_INCOMING <-- Network Set_Up <-Proceeding --> cc_GetDNIS( ) (option) --> cc_DropCall( ) --> Return immediately with DNIS <-Call_Disconnect (cause value ≠ 0) --> IDLE terminatio
PAGE 399
Appendix A - Call Control Scenarios Application Device Driver State Firmware Network Proceeding cc_CallAck( ) --> --> *Application may control CALL_PROCEEDING by adding CCMSK_CALL_PROC and using cc_CallAck( ) to send event mask, proceeding toward network.
PAGE 400
ISDN Software Reference for Linux and Windows Glare Condition 1: Call collision occurs after the SETUP message is sent to the network A glare condition occurs when both an incoming and outgoing call request the same time slot. When glare occurs, the incoming call is assigned the time slot. In this scenario, the firmware detects an incoming SETUP message after transmitting the outgoing SETUP message to the network.
PAGE 401
Appendix A - Call Control Scenarios Application Device Driver State cc_MakeCall()--> Host CRN # 1 assigned Call_Outgoing --> NULL cc_DropCall() --> CCEV_DROPCALL <-cc_ReleaseCall( ) Firmware Network Firmware CRN #1 is assigned CALL_OUTGOING --> Set up --> Call_Dis --> IDLE Call_Dealloc --> Host CRN #1 released CALL_CLEARED <-- NULL Firmware CRN #1 released CALL_DEALLOC_AC K <-*Application may connect a voice channel to the B channel.
PAGE 402
ISDN Software Reference for Linux and Windows Glare Condition 2: Call collision occurs before the SETUP message is sent to the network A glare condition occurs when both an incoming and outgoing call request the same time slot. When glare occurs, the incoming call is assigned the time slot. In this scenario, the firmware detects an incoming SETUP message prior to transmitting the outgoing SETUP message to the network.
PAGE 403
Appendix A - Call Control Scenarios cc_AnswerCall() --> Call_Connected --> *B channel cutConnect thru --> CALL_CONNECT --> CCEV_ANSWERCALL CONNECTED CALL_CONNECT_ACK Conn_ACK <-<-<-*Application may connect a voice channel to the B channel. **Note that the CCEV_TASKFAIL event may occur anytime between calling cc_MakeCall() and the receipt of the CCEV_ANSWERCALL event.
PAGE 404
ISDN Software Reference for Linux and Windows Simultaneous disconnect (any state) A simultaneous disconnect condition occurs when both the application and the network attempt to disconnect the call. The following scenarios are written for the asynchronous programming model. For synchronous programming, CCEV_DROPCALL will terminate cc_DropCall( ). The first simultaneous disconnect scenario covers the following conditions: • • Glare at firmware - the firmware sees DISCONNECT first.
PAGE 405
Appendix A - Call Control Scenarios Asynchronous Programming Application Device Driver State Firmware Network DISCONNECTED CALL_DISC <-- IDLE Firmware does nothing here until Release is sent Disconne ct <-Release --> CONNECTED *cc_DropCall( ) ***cc_ReleaseCal l( ) --> CCEV_ DISCONNECTED <-Call_Disconnecte d (cause value =0) --> **CCEV_DISCONNEC TED <-CCEV_DROPCALL <-Call_Dealloc --> Release --> CALL_CLEARED <-- Rel_Comp <-- Driver releases NULL F/W releases CRN CRN CALL_DEALLOC_ACK Return <
PAGE 406
ISDN Software Reference for Linux and Windows The next scenario covers the following simultaneous disconnect conditions: • cc_DropCall( ) arrives after Release command is sent - the network disconnects first while cc_DropCall( ) arrives at the firmware after a Release command is sent to the network. Glare happens on the wire - the firmware sees the cc_DropCall( ) function call first.
PAGE 407
Appendix A - Call Control Scenarios Hold and retrieve - local initiated Step Dialogic API Action/Result Dialogic Event 1 --- CALL CONNECTED --- cc_HoldCall( ) --> --- CALL HELD --- <-- CCEV_HOLDACK 2 3 Unroute SCbus time slot for held call : --> 4 cc_RetrieveCall( ) 5 6 7 8 Reroute SCbus time slot for retrieved call --- <-- CCEV_RETRIEVEACK CALL NOT HELD --- <-- CCEV_HOLDREJ Take no action 1. Place a connected call on hold (cc_HoldCall( )). 2.
PAGE 408
ISDN Software Reference for Linux and Windows Hold and retrieve - remote initiated Step Dialogic API Action/Result Dialogic Event 1 --- CALL CONNECTED --- <-- CCEV_HOLDCALL CALL HELD --- --2 3 Unroute SCbus time slot for held call cc_HoldAck( ) --> : 4 5 Reroute SCbus time slot for retrieved call --- 6 Take no action 7 cc_HoldRej( ) <-- CCEV_RETRIEVECALL CALL NOT HELD --- --> 1. Receives a request to place a connected call on hold (CCEV_HOLDCALL). 2.
PAGE 409
Appendix A - Call Control Scenarios Network Facility Request or Service Vari-A-Bill (AT&T Service Only) Vari-A-Bill is a service option provided only by AT&T at the press time of this document.
PAGE 410
ISDN Software Reference for Linux and Windows ANI-on-demand - incoming call (AT&T Service Only) The following scenario uses cc_ReqANI( ) to acquire the caller's ID. It differs from the cc_GetANI( ) function in the way the function is returned.
PAGE 411
Appendix A - Call Control Scenarios Advice of charge - inbound and outbound call (AT&T Service Only) Asynchronous Programming: Call disconnected by network Application Device Driver State Firmware Network Charge information is part of the DISC message CALL_DISC <-- disconnect <-- CONNECTED CCEV_DISCONNECT ED <-- DISCONNECTED Release --> REL_COMP <-- cc_GetBilling( ) --> cc_ReleaseCall( ) --> billing info (return immediately) <-Call_Dealloc --> Return <-- NULL CALL_DEALLOC_ACK <-- Synchronous
PAGE 412
ISDN Software Reference for Linux and Windows cc_ReleaseCall( ) --> Billing info (return immediately.) <-Call_Dealloc --> Return <-- NULL CALL_DEALLOC_ACK <-- Two B Channel Transfer (TBCT) TBCT enables an ISDN PRI user to request the switch to connect together two independent calls on the user’s interface. The two calls can be served by the same PRI trunk or by two different PRI trunks that both serve the user.
PAGE 413
Appendix A - Call Control Scenarios When a transferred call is disconnected, the network informs the TBCT controller by sending a NOTIFY message with the Network Call Reference Value. The application receives the GCEV_EXTENSION event (with ext_id = GCIS_EXEV_NOTIFY) event. The following figures provide line diagrams that illustrate the operation of this feature. Figure 7 shows the invocation of TBCT with notification in which both calls answered.
PAGE 414
ISDN Software Reference for Linux and Windows Figure 8 shows the invocation of TBCT with notification where one call is answered and the other call is alerting. Network Controller User A FACILITY (Invoke) FACILITY (Return reult: Invoke: Transfers: active transfers.
PAGE 415
Appendix A - Call Control Scenarios The following call scenario describes the procedures for initiating a TBCT. The scenario is followed by code samples that demonstrate the use of Dialogic API in initiating a TBCT.
PAGE 416
ISDN Software Reference for Linux and Windows Application cc_ReleaseCall( ) (Call #1) --> Device Driver CCEV_DROPCALL (Call #1) <-CALL_DEALLOC (Call #1) --> Driver releases CRN return State NULL (Call #1) DISCONNECTED (Call #2) cc_DropCall( ) (Call #2) --> cc_ReleaseCall( ) (Call #2) --> CCEV_DISCONNECT (Call #2) <-CALL_DISCONNECTE D (Call #2) --> CCEV_DROPCALL (Call #2) <-CALL_DEALLOC (Call #2) Driver releases CRN return Firmware Network CALL_CLEARED (Call #1) <-- CALL_DEALLOC_ACK (Call #1) <-C
PAGE 417
Appendix A - Call Control Scenarios The following code samples demonstrate the use of the Dialogic API at various stages of the TBCT call scenario. 1. Opening a board level device: LINEDEV dti_dev1_hdl; . . rc = cc_Open( &dti_bd_hdl, "dtiB1", 0); . . 2. Retrieving the Network’s Call Reference Value: CRN crn1=0; unsigned short crn1_crv=0; . . rc = cc_GetNetCRV ( crn1, &crn1_crv ); . . 3.
PAGE 418
ISDN Software Reference for Linux and Windows tbct_ie.bits.comp_data[3] tbct_ie.bits.comp_data[4] tbct_ie.bits.comp_data[5] tbct_ie.bits.comp_data[6] tbct_ie.bits.comp_data[7] tbct_ie.bits.comp_data[8] tbct_ie.bits.comp_data[9] tbct_ie.bits.comp_data[10] tbct_ie.bits.
PAGE 419
Appendix A - Call Control Scenarios FACILITY_IE_LAYOUT . IE_BLK ie_list; *tbct_ie; ext_id = (EXTENSIONEVTBLK*) (metaevt.extevtdatap); /*assumes ‘metaevt’ is filled by gc_GetMetaEvent */ switch ( event ) { . . case GCEV_EXTENSION: switch (ext_id) { . . . // retrieve facility IE for (ie_len = 2; ie_len < ie_list.
PAGE 420
ISDN Software Reference for Linux and Windows 5. Processing the Network notification for disconnecting transferred calls: ext_id = (EXTENSIONEVTBLK*) (metaevt.extevtdatap); /*assumes ‘metaevt’ is filled by gc_GetMetaEvent */ switch ( event ) { . . . case GCEV_EXTENSION: switch (ext_id); . . . case GCIS_EXEV_NOTIFY: gc_GetInfoElem( boarddev, &ie_list ); . . . // retrieve Notification IE for (ie_len = 2; ie_len < ie_list.
PAGE 421
Appendix A - Call Control Scenarios Non-Call Associated Signaling (NCAS) NCAS allows users to communicate by means of user-to-user signaling without setting up a circuit-switched connection (it does not occupy B channel bandwidth). A temporary signaling connection is established and cleared in a manner similar to the control of a circuit-switch connection. NOTES: 1. This feature is supported for the 5ESS protocol only 2.
PAGE 422
ISDN Software Reference for Linux and Windows User Network Setup Release OR Release Complete Figure 10. User-Rejected Network-Initiated NCAS Request User Network Release Release Complete Figure 11. User-Disconnected NCAS Call The following scenarios demonstrate the procedures for a user-initiated and a network-initiated NCAS call. User-initiated call In the following scenario, the user initiates and disconnects the NCAS call for dtiB1.
PAGE 423
Appendix A - Call Control Scenarios Application Device Driver State Firmware Network Return <-cc_MakeCall( ) D-channel line devices (dtiB1T24) --> CALL_OUTGOING --> CCEV_CONNECTED <-- Setup --> CONNECTED Connect <-- NCAS call connected cc_SetInfoElem( ) setup user-touser information, D-channel line devices (dtiB1T24) --> cc_SndMsg( ) send User-to-user signaling --> cc_GetCallInfo( ) retrieve user-touser information --> cc_DropCall( ) --> cc_ReleaseCall( ) --> CALL_UUI --> UUI --> CCEV_USRINFO
PAGE 424
ISDN Software Reference for Linux and Windows The following code samples demonstrate the use of the Dialogic API at various stages of the NCAS call scenario. 1. Opening a D channel line level device: LINEDEV D_chan_dev1_hdl; . . rc = cc_Open( &D_chan_dev1_hdl, "dtiB24", 0); . 2. Setting up the MAKECALL_BLK for an NCAS call: MAKECALL_BLK *makecallp; . . // initialize makecall block makecallp->isdn.BC_xfer_cap = BEAR_CAP_UNREST_DIG; makecallp->isdn.BC_xfer_mode = ISDN_ITM_PACKET; makecallp->isdn.
PAGE 425
Appendix A - Call Control Scenarios Network-initiated call In the following scenario, the network initiates and disconnects the NCAS call for dtiB1.
PAGE 426
ISDN Software Reference for Linux and Windows cc_ReleaseCall( ) --> 414 CCEV_DROPCALL <-CALL_DEALLOC --> Driver releases CRN return CALL_CLEARED <-- NULL CALL_DEALLOC_ ACK <--
PAGE 427
Appendix B - DPNSS Call Scenarios This appendix describes call scenarios that are specific to the DPNSS protocol. Each scenario provides a table that illustrates the Dialogic Application Programming Interfaces (APIs) issued by the application to either initiate a transaction or to respond to an external action, and the resulting Dialogic event that is returned to the application. A step-by-step description of the scenario follows the table for further clarification.
PAGE 428
ISDN Software Reference for Linux and Windows Executive Intrusion - Normal Step Dialogic API Action/Result 1 cc_MakeCall( ) (with Intrusion IE) --> 2 --3 --4 Dialogic Event <-- CCEV_PROCEEDING INTRUSION SUCCEEDED --- <-- CCEV_CONNECTED INTRUSION FAILED --- <-- CCEV_DISCONNECT 1. Places an outgoing call (cc_MakeCall( )) to a busy extension with intrusion information set to "Normal." See Appendix C for the format of Intrusion IE. 2. Receives call proceeding (CCEV_PROCEEDING). 3.
PAGE 429
Appendix B - DPNSS Call Scenarios 1. Places an outgoing call (cc_MakeCall( )) to a busy extension with intrusion information set to "Prior Validation." See Appendix C for the format of Intrusion IE. 2. Receives call proceeding (CCEV_PROCEEDING) event with indication that remote party was busy. Use cc_GetSigInfo( ) to retrieve Busy IE. See Appendix C for Busy IE's format. 3. Sends intrude request using (cc_SndMsg( )). See the cc_SndMsg( ) function description for details. 4.
PAGE 430
ISDN Software Reference for Linux and Windows 2 cc_SndMsg( ) (SndMsg_Divert, diversion location: DIVERT_LOCAL) --> 3 cc_AnswerCall( ) --> 4 <-- CCEV_ANSWERED 1. Receives incoming call (CCEV_OFFERED) event. 2. Diverts incoming call (cc_SndMsg( )) to different extension. Use cc_SndMsg( ) to divert the incoming call. See the cc_SndMsg( ) function description for details. 3. Answer incoming call (cc_AnswerCall( )). 4. Receives call connected (CCEV_ANSWERED) event.
PAGE 431
Appendix B - DPNSS Call Scenarios 1. Party 1 calls Party 2 by issuing cc_MakeCall( ). 2. Party 1 receives CCEV_PROCEEDING event from Party 2 with indication that call needs to be diverted to Party 3. Diversion IE will contain the telephone number of Party 3. See Appendix C for Diversion IE's format. 3. Party 1 disconnects original call to Party 2. 4. Party 1 receives call disconnect (CCEV_DROPCALL) event from Party 2. 5. Releases first call. 6. Party 1 diverts call to Party 3.
PAGE 432
ISDN Software Reference for Linux and Windows 2. Party 2 diverts incoming call to Party 3. Send Party 3’s telephone number as Diversion number. See Appendix C for the format of SndMsg_Divert message. 3. Party 1 disconnects call to Party 2. 4. Party 2 drops call (cc_DropCall( )). 5. Party 2 receives drop call event (CCEV_DROPCALL) event from Party 1. 6. Releases call.
PAGE 433
Appendix B - DPNSS Call Scenarios 18 cc_DropCall( ) (CRN 1) 19 20 <-cc_ReleaseCall( ) (CRN 1) 21 22 CCEV_DISCONNECT (CRN 2) --> <-- cc_ReleaseCall( ) (CRN 2) CCEV_DROPCALL (CRN 1) --> <-- cc_DropCall( ) (CRN 2) 23 24 --> CCEV_DROPCALL (CRN 2) --> 1. Party 2 receives incoming call (CCEV_OFFERED) from Party 1. 2. Party 2 answers call (cc_AnswerCall( )) from Party 1. 3. Party 2 places call on hold (cc_HoldCall( )). NOTE: Some switches may not support Hold. 4.
PAGE 434
ISDN Software Reference for Linux and Windows 13. Party 2 receives transit (CCEV_TRANSIT) event from Party 1. Party 2 should retrieve the content of the Transmit Message using cc_GetSigInfo( ). 14. Party 2 sends content of Transmit Message (unchanged) from Party 1 to Party 3 (cc_SndMsg( )). See Appendix C for message format. 15. Party 2 receives transit (CCEV_TRANSIT) event from Party 3. Party 2 should retrieve the content of the Transit Message using cc_GetSigInfo( ). 16.
PAGE 435
Appendix B - DPNSS Call Scenarios 4 <-- 5 cc_ReleaseCall( ) CCEV_DROPCALL --> 1. Places an outgoing call (cc_MakeCall( )) with Virtual Call IE and any other information set, such as NSI strings or Extension Status. See Appendix C for the format of Virtual Call IE. 2. Receives call disconnected (CCEV_DISCONNECT) event. Use cc_ResultValue( ) to retrieve the clearing cause. RESP_TO_STAT_ENQ means the call was Acknowledged and FACILITY_REJECT means the call was Rejected. 3. Issues cc_DropCall( ).
PAGE 436
PAGE 437
Appendix C - IEs and ISDN Message Types for DPNSS This appendix lists the information elements (IEs) and ISDN message types in the ISDN software library that support the DPNSS protocol. Information Elements for cc_GetCallInfo( ) and cc_GetSigInfo( ) The following tables describe the different types of IEs that can be retrieved for DPNSS using the cc_GetCallInfo( ) and cc_GetSigInfo( ) functions. Intrusion IE: Field Description Field Selection Definition 1.
PAGE 438
ISDN Software Reference for Linux and Windows Field Description Field Selection Definition 3. Data Diversion Type DIVERT_IMMEDIATE Diverted immediately DIVERT_ON_BUSY Diverted when called party was busy DIVERT_NO_REPLY Diverted when called party did not answer Diversion Location DIVERT_LOCAL Local diversion DIVERT_REMOTE Remote diversion Diversion Number ASCII string Diverted number 4. Data 5. Data Diversion Validation IE: Field Description Field Selection Definition 1.
PAGE 439
Appendix C - IEs and ISDN Message Types for DPNSS Field Description Field Selection Definition 3. Data Transit Data data Transit data that needs to be sent to the other transfer party. Text Display IE: Field Description Field Selection Definition 1. IE ID Text Display IE ID TEXT_DISPLAY_IE This IE can be part of a CCEV_OFFERED event. 2. Data Text Display IE Length 1 + length of Text Display string Number of data bytes for this IE. 3.
PAGE 440
ISDN Software Reference for Linux and Windows Network Specific Indications (NSI) IE: Field Description Field Selection Definition 1. IE ID NSI IE ID NSI_IE This IE can be part of any event including the CCEV_NSI event. 2. Data NSI IE Length 2 + Length of Network Specific Indications (NSI) string Number of data bytes for this IE 3. Data NSI Message Type NSI_EEM End-to-end message NSI_LLM Link-to-link message 4.
PAGE 441
Appendix C - IEs and ISDN Message Types for DPNSS Virtual Call IE: Field Description Field Selection Definition 1. IE ID Virtual Call IE ID VIRTUALCALL_IE This IE, when part of a CCEV_OFFERED event, indicates a virtual call.
PAGE 442
ISDN Software Reference for Linux and Windows Information Elements for cc_SetInfoElem( ) The following tables describe the information elements that can be set for DPNSS using the cc_SetInfoElem( ) function. Intrusion IE: Field Description Field Selection Definition 1. Length Total bytes of the following data field 4 Required value 2. IE ID Intrusion IE ID INTRUSION_IE Use with the cc_MakeCall( ) function to indicate intrusion privilege. 3.
PAGE 443
Appendix C - IEs and ISDN Message Types for DPNSS Diversion IE: Field Description Field Selection 1. Length Total bytes of the following data field 4 + length of Diversion Number 2. Data Diversion IE ID DIVERSION_IE Use with the cc_MakeCall( ) function to indicate why the call was diverted and from where the call was diverted. 3. Data Diversion IE Length 2 + length of Diversion Number Number of data bytes for this element 4.
PAGE 444
ISDN Software Reference for Linux and Windows Field Description Field Selection Definition 2. Data Diversion Bypass IE ID DIVERSION_BYPASS_IE Use with the cc_MakeCall( ) function to indicate that diversion is not allowed. Inquiry IE: Field Description Field Selection 1. Length Total bytes of the following data field 1 2. Data Inquiry IE ID INQUIRY_IE Definition Use with the cc_MakeCall( ) function to indicate three-party call.
PAGE 445
Appendix C - IEs and ISDN Message Types for DPNSS Virtual Call IE: Field Description Field Selection Definition 1. Length Total bytes of the following data field 1 Required value 2. Data Virtual Call IE ID VIRTUALCALL_IE Use with the cc_MakeCall( ) function to indicate virtual call. Text Display IE: Field Description Field Selection Definition 1. Length Total bytes of the following data field 3 + length of Text Display String Required value 2.
PAGE 446
ISDN Software Reference for Linux and Windows Field Description Field Selection Definition 5. Data Text DISPLAY String ASCII string Text Display string. The '*' and '#' symbols cannot be used directly; 0x01 and 0x02 values are substituted respectively Network Specific Indications (NSI) IE: Field Description Field Selection Definition 1. Length Total bytes of the following data field 4 + length of NSI String Required value 2.
PAGE 447
Appendix C - IEs and ISDN Message Types for DPNSS SndMsg_Divert: Field Description Field Selection Definition 1. Length Total bytes of the following data field 4 + length of Diverted Number Required value 2. Data Diversion IE ID DIVERSION_IE Identifies the Diversion IE 3. Data Diversion IE Length 2 + length of Diverted Number Number of data bytes for this IE 4.
PAGE 448
ISDN Software Reference for Linux and Windows Field Description Field Selection Definition 4. Data Intrude Type INTRUDE Intrude INTRUDE_WITHDRAW Withdraw intrusion SndMsg_NSI: Field Description Field Selection Definition 1. Length Total bytes of the following data field 4 + length of NSI String Required value 2. Data NSI IE ID NSI_IE Identifies the NSI IE 3. Data NSI IE Length 2 + length of Network Specific Indications (NSI) string Number of data bytes for this IE 4.
PAGE 449
Appendix C - IEs and ISDN Message Types for DPNSS Field Description Field Selection Definition 2. Data Transfer IE ID TRANSFER_IE Identifies the Transfer IE 3. Data Transfer IE Length 1 Number of data bytes for this IE 4. Data Transfer Direction TRANSFER_ORIG Originating end TRANSFER_TERM Terminating end SndMsg_Transit: 1. Length Total bytes of the following data field 2 + Length of Transit Data Required value 2. Data Transit IE ID TRANSIT_IE Identifies the Transit IE 3.
PAGE 450
PAGE 451
Appendix D – BRI Supplemental Services The ISDN API functions allow BRI boards to perform the following Supplemental Services: • Called/Calling Party Identification • Subaddressing • Hold/Retrieve • Call Transfer • Message Waiting Call Hold and Retrieve are invoked using the following API functions (see the appropriate function descriptions in Chapter 5.
PAGE 452
ISDN Software Reference for Linux and Windows • cc_SndNonCallMsg( ) - Sends a non-Call State related message to the PBX. This function does not require a call reference value. • cc_SetInfoElem( ) - Sets an information element (IE) allowing the application to include application-specific ISDN information elements in the next outgoing message. The following functions are used to retrieve Facility Messages: • cc_GetCallInfo( ) - Retrieves the information elements associated with the CRN.
PAGE 453
Appendix D – BRI Supplemental Services As an example, to invoke Supplemental Service ‘X’, the cc_SndMsg( ) function with msg_type = SndMsg_Facility could be used. The Information Element would be defined in a data structure as follows: ieblk.length = ieblk.data[0] ieblk.data[1] ieblk.data[2] 11; = 0x1c; = 0x09; = 0x91; /* IE Identifier */ /* Length of information */ /* Protocol Profile */ /* information ieblk.data[3] ieblk.data[4] ieblk.data[5] ieblk.data[6] ieblk.data[7] ieblk.data[8] ieblk.
PAGE 454
ISDN Software Reference for Linux and Windows When a Supplemental Service is invoked, the network may return a NOTIFY Message to the user. This message can be retrieved using the cc_GetCallInfo( ) function.
PAGE 455
Appendix D – BRI Supplemental Services Table 60. ETSI Specification Cross-Reference for Supplemental Services Supplementary Service/Description ETS 300 Specification Explicit Call Transfer - enables a user (user A) to transform two of that user's calls (an active call and a held call), each of which can be an incoming call or an outgoing call, into a new call between user B and user C. “Call Transferred Alerting” and “Call Transferred Active” messages are returned by the network to the user.
PAGE 456
ISDN Software Reference for Linux and Windows Supplementary Service/Description ETS 300 Specification Message Waiting Indication 650/745-1/356-20 444
PAGE 457
Appendix E - Establishing ISDN Cable Connections This appendix explains the basic principles of ordering ISDN service and establishing a connection between the Dialogic Digital Network Interface boards and the Network Termination Unit (NTU). Ordering Service When ordering your ISDN service from a carrier, keep the following points in mind when talking to a service representative: • Be specific when describing the kinds of service options you want.
PAGE 458
ISDN Software Reference for Linux and Windows either purchase one from your supplier or build one yourself. If you are building your own cable, it must fit the following specifications: Characteristic Recommendations/Requirements Cable Type: The recommended cable type is twisted-pair cable in which each of the two pairs is shielded and the two pairs have a common shield as well. Shielding helps prevent noise and the twisting helps prevent cross talk.
PAGE 459
Appendix F - Related Publications This appendix lists publications that provide additional information on Dialogic products and ISDN technology.
PAGE 460
PAGE 461
Glossary ASCII American Standard Code for Information Interchange ANI Automatic Number Identification. A service that identifies the phone number of the calling party. ANI-on-Demand A feature of AT&T ISDN service whereby the user can automatically request caller ID from the network even when caller ID does not exist. ASCII American Standard Code for Information Interchange.
PAGE 462
ISDN Software Reference for Linux and Windows be notified of an incoming call (as per the basic call establishment process) with an indication that no information channel is available. CEPT Conference des Administrations Europeenes des Postes et Telecommunications. A collection of groups that set European telecommunication standards.
PAGE 463
Glossary connect the call to a different channel. Drop-and-insert configurations provide the ability to access an operator or another call. DSL Digital Subscriber Loop E-1 Another name given to the CEPT digital telephony format devised by the CCITT that carries data at the rate of 2.048 Mbps (DS-1 level). event An unsolicited communication from a hardware device to an operating system, application, or driver.
PAGE 464
ISDN Software Reference for Linux and Windows established, the application can transmit user-to-user messages using the CRN associated with the NCAS call. An ISDN feature that supports the 5ESS protocol. Network Facility Associated Signal (NFAS) Allows multiple spans to be controlled by a single D channel subaddressing. NULL A call state in which no call is assigned to the device (line or time slot).
PAGE 465
Glossary TEI Terminal Endpoint Identifier (see Recommendations Q.920 and Q.921) synchronous function Synchronous functions block an application or process until the required task is successfully completed or a failed/error message is returned. T-1 A digital line transmitting at 1.544 Mbps over 2 pairs of twisted wires. Designed to handle a minimum of 24 voice conversations or channels, each conversation digitized at 64 Kbps. T -1 is a digital transmission standard in North America.
PAGE 466
ISDN Software Reference for Linux and Windows USID User Service Identifier UUI User-to-User Information. Proprietary messages sent to remote system during call establishment. Vari-A-Bill Service bureaus can vary the billing rate of a 900 call at any time during the call. Callers select services from a voice-automated menu and each service can be individually priced. voice channel Designates a bi-directional transfer of data for a single call between a voice device processing that call and the SCbus.
PAGE 467
Index 5 bitmask values, 115 5ESS Custom Messaging, 7 bitmask values, 233 A Alarm Handling, 350, 352 BRI, 3 advantages over PRI, 4 benefits, 4 ALERTING message, 50 BRI applications, 7 ANI, 8, 80 BRI configuration requirements, 357 ANI-on-demand, 190 feature in PRI, 9 BRI device, 177 Application guidelines, 349 BRI structure, 177, 353 applications, 9 aborting and terminating, 350 BRI terminal initialization, 358 asynchronous call termination, 24 BRI Features, 4 C AT&T ISDN network, 191, 214
PAGE 468
ISDN Software Reference for Linux and Windows network initiated call, 371 network terminated call, 374, 376 PRI channel initialization, 370 PRI start up, 370 simultaneous disconnect, 392 Vari-A-Bill, 397 cause codes, 67 cause value, 67, 198, 210 causes for dropping a call, 75 cautions, 46 call control states, 15 cc_AcceptCall( ), 50 call disconnect, 23, 25 cc_AcceptCall( ), 19, 22, 32 call progress tone, 60 cc_AnswerCall( ), 53 Call Reference Number, 47 cc_AnswerCall( ), 19, 22, 31 call reference
PAGE 469
Index cc_GetCallInfo( ), 89 cc_GetParmEx( ), 35 cc_GetCallInfo( ), 32 cc_GetSAPI( ), 148 cc_GetCES( ), 93 cc_GetSAPI( ), 35 cc_GetCES( ), 35 cc_GetSigInfo( ), 151 cc_GetChanId( ), 96 cc_GetSigInfo( ), 32 cc_GetChanId( ), 32 cc_GetUsrAttr( ), 156 cc_GetCRN( ), 101 cc_GetVer( ), 159 cc_GetCRN( ), 35 cc_GetVer( ), 32 cc_GetDChanState( ), 104 cc_HoldAck( ), 161 cc_GetDLinkCfg( ), 35, 107 cc_HoldAck( ), 39 cc_GetDLinkState( ), 35 cc_HoldCall( ), 164 cc_GetDNIS( ), 112 cc_HoldCall( ), 39
PAGE 470
ISDN Software Reference for Linux and Windows cc_ResultMsg( ), 198 cc_SetUsrAttr( ), 36 cc_ResultMsg( ), 37 cc_SndFrame( ), 257 cc_ResultValue( ), 201 cc_SndFrame( ), 38 cc_ResultValue( ), 37 cc_SndMsg( ), 260 cc_RetrieveAck( ), 39 cc_SndMsg( ), 33 cc_RetrieveCall( ), 39 cc_SndNonCallMsg( ), 33, 264 cc_RetrieveRej( ), 39 cc_StartTrace( ), 268 cc_SetBilling( ), 214 cc_StartTrace( ), 37 cc_SetBilling( ), 32 cc_StopTone( ), 271 cc_SetCallingNum( ), 218 cc_StopTone( ), 40 cc_SetCallingNum(
PAGE 471
Index CCEV_MOREDIGITS, 128 CCST_IDLE, 63 CCEV_OFFERED, 19, 50, 53, 60, 290 CCST_NULL, 63, 64 CCEV_PLAYTONE, 179 CCST_OFFERED, 63, 64 CCEV_PLAYTONEFAIL, 179 CEPT multiframe, 14 CCEV_PROGRESSING, 53 CES, 93 CCEV_RCVTERM_REG_ACK, 321 channel parameters default, 244 CCEV_RCVTERMREG_NACK, 319 CCEV_RELEASECALL, 187 CCEV_RELEASECALLFAIL, 187 CCEV_REQANI, 191 CCEV_RESTART, 195 CCEV_RESTARTFAIL, 195 CCEV_RETRIEVEACK, 207 CCEV_RETRIEVECALL, 204, 210 channel service states, 221 channel states, 83, 104 cl
PAGE 472
ISDN Software Reference for Linux and Windows D4 frame, 14 cc_SetBilling( ), 342 library, 347 network, 342 data link layer, 9, 14, 119, 257 data link layer handling , 29, 38 data link states, 109 data structure, 293 data structures, 293 DCHAN_CFG, 295 devicename format, 176 Error handling, 338, 350 error handling, 351 error handling functions, 37 error locations firmware, 67 ISDN library, 67 network, 67 Dialogic ISDN terminology CRN, 47 line device handle, 47 error/cause codes, 338 Digital Subscriber
PAGE 473
Index format devicename, 176 framing, 14 CEPT multiframe, 14 D4, 14 ESF, 14 function call return state change, 16 function categories, 29 function description, 46 function format, 47 function header, 46 function overview, 46 category, 46 includes, 46 inputs, 46 mode, 46 name, 46 returns, 46 technology, 46 G glare, 451 IEs, 89, 122, 238 inbound call, 19 asynchronous example, 18 synchronous example, 21 Information Element (IE), 451 Information Elements, 89, 122, 238 settings, 354 input fields, 47 Introduct
PAGE 474
ISDN Software Reference for Linux and Windows LAPD protocol, 260 NFAS, 451, 452 Layer 2, 14 Network Layer, 14 Layer 3, 14 Network Termination Unit, 445 connections, 445 Layer 3 Supplementary Services, 5 library error codes, 347 library errors, 339 library function categories, 29 Line Device Handle, 47, 73, 125 LOCKING Shift IE, 355 logical data link state, 109 M MAKECALL Block, 314, 353 MAKECALL block parameters, 306 MAKECALL_BLK, 305, 314, 353 MAKECALL_BLK initialization, 314, 353 MAKECALL_BLK stru
PAGE 475
Index parameter values, 138 return code, 198 PARM_INFO, 316 S Point-to-Multipoint Configuration, 6 SAPI, 148 PRI, 3, 7 benefits, 8 Service Access Point ID, 148 PRI device, 176 PRI structure, 176, 352 Primary Rate Interface, 3, 7 Products listing of, 1 Service Profile Interface ID, 278 setting up a call, 17, 20, 23, 25 setup message, 56, 57 signaling, 13 signaling data, 13 programming considerations, 352 signaling information, 151 Programming conventions, 47 Special Information Tone, 60 progra
PAGE 476
ISDN Software Reference for Linux and Windows TERM_BLK, 317 TERM_NACK_BLK, 319 terminal initialization events, 279 UUI, 90, 152 User-to-User Information, 454 V termination events, 325 Vari-A-Bill, 86, 214, 294, 342 cc_SetBilling( ), 214 feature in PRI, 9 network facility request, 397 termination scenario, 24 variable length IEs, 354 thread Windows, 453 version number, 159 time slot, 453 W Terminate configuration, 10 termination event, 16, 17, 46 Tone Generation, 6 ToneParm, 320 tracing function