(Page 1 of 1 in this chapter)

Chapter 2

SS7 ISUP API Description

2.1 ISUP Service Users

2.2 Entity and Instance IDs

2.3 API Primitives

2.4 Configuring ISUP for the New Japan/NTT Variant

2.5 Event Initialization Routines

2.6 Signaling Parameters

2.7 Operating System Specific Considerations

: 2.7.1 Receiving Confirmations and Indications
: 2.7.2 UnixWare and Solaris Systems
: 2.7.3 Windows NT

2.8 ISUP API Procedures

: 2.8.1 Binding
: 2.8.2 Connection Establishment
: 2.8.3 Connection Establishment with Continuity Check Required
: 2.8.4 Continuity Recheck
: 2.8.5 Aborted Continuity Check
: 2.8.6 Data Transfer
: 2.8.7 Connection Clearing
: 2.8.8 Circuit Reset
: 2.8.9 Circuit Group Reset
: 2.8.10 Circuit Blocking/Unblocking
: 2.8.11 Circuit Group Blocking/Unblocking
: 2.8.12 Circuit Group Query

2.1 ISUP Service Users

The ISUP user interface supports one or more user applications by way of Service Access Points, or SAPs. One SAP is defined for each application that may use the ISUP service. A user applications binds to a particular SAP at initialization time, specifying the SAP ID that it wishes to bind to. Associated with each user SAP (in the ISUP configuration file) is a switch type (CCITT, ANSI-88, or ANSI-92) which the ISUP process uses to associate with its configured network connections. Multiple SAPs, and hence multiple applications, for a particular switch type may be defined for outgoing call requests. Incoming messages which are associated with a previously issued outgoing request are always routed to the SAP that issued the original outgoing request. Incoming call requests, however, are always routed to the first SAP whose switch type matches the switch type of the network connection that the request was received over. Note: The number of SAPs and the characteristics of each SAP are specified in the ISUP configuration file. See the Signaling System 7 (SS7) Installation and Configuration Manual for details.

2.2 Entity and Instance IDs

Each user application must also have a unique entity and instance number, which is used to route messages among the various processes in the system. Entity IDs are single byte values in the range 0x00..0x3F, assigned as desired by the application developer. The following entity IDs are reserved. 0x00-0x13 Reserved ISUP 0x14 ISDN User Part Protocol Handler MTP3 0x15 Message Transfer Part Layer 3 MTP2 0x16 Message Transfer Part Layer 2 0x17-0x1B Reserved MTP1 0x1C Message Transfer Part Layer 1 0x1D Reserved SCCP 0x1E SCCP Protocol Handler 0x1F Reserved 0x20-0x3F Available for applications
Instance IDs identify the processor that the entity executes on. The host is always processor 0 (zero), so for all host-resident SCCP user applications this value should be coded to zero. All tasks on TX Series board number 1 receive and instance ID of 1, all tasks on TX Series board number 2 receive and instance ID of 2, and so on.

	0x00-0x13	Reserved
ISUP	0x14	ISDN User Part Protocol Handler
MTP3	0x15	Message Transfer Part Layer 3
MTP2	0x16	Message Transfer Part Layer 2
	0x17-0x1B	Reserved
MTP1	0x1C	Message Transfer Part Layer 1
	0x1D	Reserved
SCCP	0x1E	SCCP Protocol Handler
	0x1F	Reserved
	0x20-0x3F	Available for applications

2.3 API Primitives

The SS7 ISUP API provides a set of functions which provide the application access to the ISUP layer services. Applications invoke ISUP services by calling ISUP API request primitives which generally result in an ISUP message to a remote exchange, or end point. Request primitive parameters are converted by the API to messages and sent by the host OS TX Series driver to the ISUP process.
The remote end point may optionally return a confirmation (i.e., acknowledgment), which is delivered to the application via the TX Series driver. The application retrieves the confirmation via an API primitive which also translates the confirmation parameters from SS7/ISUP raw format to API format.
The ISUP requests from the remote end points are presented to the application as indications, through the same driver and API mechanisms through which confirmations are received. The application may then issue a reply to the end point by invoking the appropriate ISUP API response primitive.
In addition to performing message handling on behalf of the application, the ISUP API primitives also perform the byte ordering translation, where necessary, between application processor (Intel, or "little endian") byte order and network (or "big endian") byte order.

2.4 Configuring ISUP for the New Japan/NTT Variant

The SWITCH_TYPE attribute for all USAP, NSAP, and CIRCUIT entries should be set to JNTT.
16-bit point codes may be specified in either hex or in "x.y.z" dotted notation. Hex point codes must be specified in the same order that they are transmitted on the link; that is, the U-code in the most significant 7 bits, the S-code in the next 4 bits, and the M-code in the least significant 5 bits.
In order to specify J-NTT 16 bit point codes in "x.y.z" notation, the following statement must be added to the MTP3 general configuration section: PC_FORMAT JNTT
This tells the ISUP configuration utility to treat all subsequent point codes as <M-Code>.<S-Code>.<U-Code> format and generate 16-bit internal point codes with the the U-code in the most significant 7 bits, the S-code in the next 4 bits, and the M-code in the least significant 5 bits.

2.5 Event Initialization Routines

The SS7 ISUP API also provides a set of event initialization routines. These routines are used to initialize event structures in preparation for calls to the API primitives.

2.6 Signaling Parameters

Signaling parameters are passed between the application process and the ISUP process in the form of events. Events are fixed format structures consisting of one or more information elements. Information elements are fixed format structures consisting of a flag indicating their presence or absence from the corresponding ISUP message, and one or more tokens, or fields. Likewise, each token is a structure consisting of a flag indicating its presence or absence, possible filler to insure proper byte alignment, and a value.
The event/information element/token structure greatly simplifies applications by allowing them to operate on fixed format structures rather than the variable length/variable formats employed by the ISUP protocol. Figure 2. Sample Event/Information Element/Token Structure

2.7 Operating System Specific Considerations

The following subsections accomodate specific concerns which depend on the individual operating system on which the software is run.

2.7.1 Receiving Confirmations and Indications

Applications receive confirmations (responses) and indications of far-end initiated requests by periodically calling the ISUPRetrieveMessage primitive. This primitive checks for an incoming message and returns an indication of whether or not a message is available. When an incoming message is received, ISUPRetrieveMessage copies the event structure to the buffer provided by the caller, performs any byte-order translation between network byte order and host byte order necessary, and reports which event was received back to the calling application. The application must periodically call this primitive to receive messages from the ISUP layer.

2.7.2 UnixWare and Solaris Systems

To allow applications more flexibility in handling multiple devices, the ISUP API makes the device file descriptor (or handle) used to access the TX Series device available to the application (see the ISUPBindReq and ISUPSyncObj primitive descriptions). Use of this file descriptor is operating system dependent, but is generally intended to allow the application to utilize operating system facilities to determine when a message from the ISUP layer is available rather than periodically call ISUPRetrieveMessage to "poll" the TX Series device.
For example, the value returned on UnixWare and Solaris systems is a file descriptor for an open streams device. The application may use this file descriptor with the poll or select system calls to determine when a message from the ISUP layer is available. The application should then call ISUPRetrieveMessage to read and decode the message.

2.7.3 Windows NT

On Windows NT systems, an application can obtain a handle (via the ISUPSyncObj primitive) which can be used with the WIN32 WaitForSingleObject or WaitForMultipleObjects system calls to efficiently perform asynchronous, or non-blocking, I/O. This allows an application to determine when a message from a single TX Series board or from any TX Series board in a multiple board installation is available without having to periodically call ISUPRetrieveMessage to "poll" each TX Series device.
To access this "synchronization handle" the application performs the following.
After calling ISUPBindReq, the application calls ISUPSyncObj, passing the handle returned from the call to ISUPBindReq, to obtain the synchronization handle.
The application uses the synchronization handle WaitForSingleObject or WaitForMultipleObjects to check or wait for a message.
When WaitForSingleObject or WaitForMultipleObjects indicates an event completion on the corresponding TX Series device synchronization handle, the application then calls ISUPRetrieveMessage (passing the original handle from ISUPBindReq, not the synchronization handle) to retrieve and decode the packet.

2.8 ISUP API Procedures

The SS7 ISUP interface typically consists of several phases: binding, connection establishment, data transfer, and connection clearing. In addition, there are miscellaneous requests and indications which may take place outside of the context of any particular connection. These stages are described in the following subsections.

2.8.1 Binding

The binding phase establishes the application as a user of the ISUP interface, identifying a particular SAP. Binding consists of a single BIND request from the application to ISUP. If an application attempts to bind to a SAP for which an application was previously bound, the older binding is removed and the new binding is established. The application must bind to ISUP with the ISUPBindReq primitive before performing calls to any other ISUP API primitives.

2.8.2 Connection Establishment

The application initiates a circuit switched connection by invoking the ISUPConnectReq primitive. This results in the generation of an ISUP Initial Address Message (IAM) to the far exchange. Alternatively, the far exchange may initiate the connection by sending the IAM message. This results in the application receiving a connect indication (EVTSITCONIND) event.

Figure 3. Outgoing Connection Establishment (dashed lines indicate optional messages)
During the connection establishment phase, the application exchanges call progress and other status information with the far exchange by invoking the ISUPConnectStatusReq primitive (with the desired event type) and by receiving connect status indications (EVTSITCNSTIND) from the ISUP process.

Figure 4. Incoming Connection Establishment (dashed lines indicate optional messages)
The connection establishment phase ends when the application receives a connect confirmation event (EVTSITCONCFM) (far exchange sent Answer or Connect message); or, for an incoming call, the application invoked the ISUPConnectResp primitive to signal to the far end that the connection is established.

2.8.3 Connection Establishment with Continuity Check Required

The application initiates a circuit switched connection with continuity check required by invoking the ISUPConnectReq primitive with the Nature of Connection Indicator IE field contChk set to CONTCHK_REQ. This results in the generation of an ISUP Initial Address Message (IAM) to the far exchange. When the Initial Address Message has been sent, the ISUP layer will issue a status indication (EVTSITSTAIND) with event type CONTCHK to the application. This is an indication to the application to perform the continuity check on the circuit. The application then reports the results of the continuity check by calling the ISUPStatusReq primitive with event type of CONTREP. Assuming that the continuity test is successful, call processing resumes normally. If the continuity test fails, the application should request a recheck of the circuit as described in Section 2.8.4, Continuity Recheck. Optionally, the application may release the connection as described in Section 2.8.7, Connection Clearing.

Figure 5. Outgoing Connection Establishment with Continuity Check Required
Alternatively, the far exchange may initiate the connection with continuity check required by sending the IAM message. This results in the application receiving a connect indication (EVTSITCONIND) event with the Nature of Connection Indicator IE field contChk set to CONTCHK_REQ. This is an indication to the application to set up a loopback condition on the specified circuit. The far exchange then performs the continuity check and sends a Continuity Message (COT) to report the results of the check. This results in the generation of a status indication (EVTSITSTAIND) with event type CONTREP to the application. Regardless of the results of the check, the application should remove the loop back condition on the circuit. If the continuity check was successful (status event structure contInd IE set to CONTCHK_SUCC) the application should continue with normal call setup. In the case of failure (status event structure contInd IE set to CONTCHK_FAIL), the application should wait for continuity recheck on the indicated circuit. (See Section 2.8.4, Continuity Recheck). Figure 6. Incoming Connection Establishment with Continuity Check Required

2.8.4 Continuity Recheck

The application initiates a continuity recheck by invoking the ISUPStatusReq primitive with the event type of CONTCHK. This will cause the ISUP layer to send a Continuity Check Request message (CCR) to the far exchange. The far exchange will the set the indicated circuit in a loop back condition, and acknowledge with a Loop Back Acknowledgment message (LPA). Upon receipt of this message, the ISUP layer will issue a status indication (EVTSITSTAIND) to the application with event type of LOOPBACK. The application should then perform the continuity check. If the continuity check fails, the application should invoke the ISUPStatusReq primitive with the event type of CONTREP.

Figure 7. Outgoing Continuity Recheck Failure
If the continuity check is successful, the application should release the connection by following the procedures for outgoing release as described in Section 2.8.7, Connection Clearing. Figure 8. Outgoing Continuity Recheck Success
When a Continuity Check Request message (CCR) is received from the far exchange, the ISUP layer will issue a status indication (EVTSITSTAIND) with event type of CONTCHK to the application. The application should set the specified circuit into a loop back condition and acknowledge the request by invoking the ISUPStatusReq primitive with event type of LOOPBACK. If the continuity test fails, the far exchange will report the results with a Continuity message (COT). This will be presented to the application by the ISUP layer as a status indication (EVTSITSTAIND) with event type of CONTREP.

Figure 9. Incoming Continuity Recheck Failure
If successful, the far exchange will transmit a Release message (REL), which will be presented as a release indication (EVTSITRELIND) to the application. The application should the follow the normal procedures for a far exchange initiated release as described in Section 2.8.7, Connection Clearing. Figure 10. Incoming Continuity Recheck Success

2.8.5 Aborted Continuity Check

If, after transmitting an Initial Address message (IAM) with continuity check required, the ISUP layer receives a Release message (REL) from the far exchange, the ISUP layer will issue a status indication (EVTSITSTAIND) with event type STPCONTIND to the application. The application should then remove the check tone from the indicated circuit. The ISUP layer will subsequently issue a release indication (EVTSITRELIND) to the application. The application should then follow the normal procedure for an incoming release as described in Section 2.8.7, Connection Clearing. Figure 11. Aborted Outgoing Connection Establishment with Continuity Check Required
After sending an Initial Address message (IAM) with continuity check required, the far exchange may transmit a Release message (REL) instead of a Continuity message (COT). In this case, the application will receive a status indication (EVTSITSTAIND) with event type STPCONTIN. The application should remove the loopback condition from the designated circuit. The application will subsequently receive a release indication (EVTSITRELIND). The application should then follow the normal procedure for an incoming release as described in Section 2.8.7, Connection Clearing. Figure 12. Aborted Incoming Connection Establishment with Continuity Check Required

2.8.6 Data Transfer

During the time that the call is connected, the application may exchange user-to-user information with its peer in the far exchange by invoking the ISUPDataReq primitive and/or receiving data indications (EVTSITDATIND) from the ISUP layer.
During this time, the circuit connection may also be suspended/resumed by either party via the ISUPSuspendReq primitive or receiving a suspend indication event (EVTSITSUSPIND), and the ISUPResumeReq primitive or receiving a resume indication event (EVTSITRESMIND), respectively.

2.8.7 Connection Clearing

The application requests clearing of a connection by invoking the ISUPReleaseReq primitive, and is notified of the completion of the release procedure (i.e., the receipt of a Release Complete message) by receipt of a release confirm (EVTRELCFM) event.

Figure 13. Application Connection Release
If the far exchange initiates the release of the connection, the application receives an release indication event (EVTSITRELIND) from the ISUP layer. The application then completes the connection release by invoking the ISUPReleaseResp primitive to send the Release Complete message to the far exchange.

Figure 14. Far Exchange Connection Release

2.8.8 Circuit Reset

The application requests the reset of a circuit by invoking the ISUPStatusReq primitive with the event type of CIRRESREQ. When an acknowledgment (Release Complete message) is received from the far exchange, the ISUP layer delivers release confirm (EVTSITRELCFM) event to the application. The application may consider the circuit reset upon receiving this indication.

Figure 15. Application Initiated Circuit Reset
If the far exchange initiates the reset of the circuit, the application receives a status indication (EVTSITSTAIND) with the event type of CIRRESREQ from the ISUP layer. The application may consider the circuit reset upon receiving this indication. The ISUP task will acknowledge the reset request by sending a Release Complete message (RLC). Note: If the application had issued any request related to this circuit that had not been processed by the ISUP layer before receipt of the Circuit Reset message, the application will receive an error indication (EVTSITERRIND) with the cause code CCINVALCALLREF. The application may choose to ignore this indication. Figure 16. Far Exchange Initiated Circuit Reset
The ISUP layer may determine (due to protocol errors) that a particular circuit should be reset. Under these circumstances, the ISUP layer will issue a status indication (EVTSITSTAIND) with the event type of CIRRESREQLOC, and send a Circuit Reset message to the far exchange. When an acknowledgment (Release Complete message) is received from the far exchange, the ISUP layer delivers release confirm (EVTSITRELCFM) event to the application. The application may consider the circuit reset upon receiving this indication. Figure 17. ISUP Layer Initiated Circuit Reset

2.8.9 Circuit Group Reset

The application requests the reset of a circuit group by invoking the ISUPStatusReq primitive with the event type of CIRGRPRESREQ, and is notified of the completion of the group reset procedure (i.e., the receipt of a Group Reset Acknowledgment message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRGRPRESACK.

Figure 18. Application Initiated Group Reset Request
If the far exchange initiates the reset of the circuit group, the application receives a status indication (EVTSITSTAIND) with the event type of CIRRESREQ from the ISUP layer for each circuit in the circuit group. The application may consider these circuits reset upon receiving these indications. The ISUP task will acknowledge the group reset request by sending a Group Reset Acknowledgment message (GRA). Figure 19. Far Exchange Initiated Group Reset Request

2.8.10 Circuit Blocking/Unblocking

The application requests blocking of a circuit by invoking the ISUPStatusReq primitive with the event type of CIRBLKREQ, and is notified of the completion of the blocking procedure (i.e., the receipt of a Blocking Acknowledgment message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRBLKRSP.

Figure 20. Application Initiated Blocking Request
If the far exchange initiates the blocking of the circuit, the application receives a status indication (EVTSITSTAIND) with the event type of CIRBLKREQ from the ISUP layer. The application then acknowledges the circuit blocking by invoking the ISUPStatusReq primitive with the event type of CIRBLKRSP.

Figure 21. Far Exchange Initiated Blocking Request
The application requests unblocking of a circuit by invoking the ISUPStatusReq primitive with the event type of CIRUNBLKREQ, and is notified of the completion of the unblocking procedure (i.e., the receipt of an Unblocking Acknowledgment message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRUNBLKRSP.

Figure 22. Application Initiated Unblocking Request
If the far exchange initiates the unblocking of the circuit, the application receives a status indication (EVTSITSTAIND) with the event type of CIRUNBLKREQ from the ISUP layer. The application then acknowledges the circuit unblocking by invoking the ISUPStatusReq primitive with the event type of CIRUNBLKRSP.

Figure 23. Far Exchange Initiated Unblocking Request

2.8.11 Circuit Group Blocking/Unblocking

The application requests blocking of a circuit group by invoking the ISUPStatusReq primitive with the event type of CIRGRPBLKREQ, and is notified of the completion of the group blocking procedure (i.e., the receipt of a Group Blocking Acknowledgment message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRGRPBLKRSP.

Figure 24. Application Initiated Group Blocking Request
If the far exchange initiates the blocking of the circuit group, the application receives a status indication (EVTSITSTAIND) with the event type of CIRGRPBLKREQ from the ISUP layer. The application acknowledges the circuit group blocking by invoking the ISUPStatusReq primitive with the event type of CIRGRPBLKRSP.

Figure 25. Far Exchange Initiated Group Blocking Request
The application requests unblocking of a circuit group by invoking the ISUPStatusReq primitive with the event type of CIRGRPUNBLKREQ, and is notified of the completion of the group unblocking procedure (i.e., the receipt of a Group Unblocking Acknowledgment message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRGRPUNBLKRSP.

Figure 26. Application Initiated Group Unblocking Request
If the far exchange initiates the unblocking of the circuit group , the application receives a status indication (EVTSITSTAIND) with the event type of CIRGRPUNBLKREQ from the ISUP layer. The application then acknowledges the circuit group unblocking by invoking the ISUPStatusReq primitive with the event type of CIRGRPUNBLKRSP.

Figure 27. Far Exchange Initiated Group Unblocking Request

2.8.12 Circuit Group Query

The application may initiate a circuit group query by invoking the ISUPStatusReq primitive with the event type of CIRGRPQRYREQ, and is notified of the completion of the group query request (i.e., the receipt of a Circuit Query Response message) by receipt of a status indication (EVTSITSTAIND) with the event type of CIRGRPQRYRSP.

Figure 28. Application Initiated Circuit Group Query Request

(Page 1 of 1 in this chapter)

tech_support@nmss.com