SKIM API Messaging

The SKIM API layer provides the following functionalities:

• Allocation / Deallocation of Call Reference ID

• Handler Functions

• Handling Multiple Stack/SSN

• SKIM Error Handling

• Resource Limitation Error

These functionalities are described further in this section.

SKIM data types and return codes are defined in Appendix B Each SKIM transaction is uniquely identified by a call reference ID. The Call Reference ID is allocated by SKIM when a new transaction is initiated or received. The call reference ID is released when a transaction is ended or aborted by the SKIM application.

Memory Management

A SKIM application does not need to do memory management with respect to SKIM API usage. A SKIM application must manage the ongoing transactions and should clear the transaction by sending or receiving prearranged end, basic end, or abort.

SKIM API allocates a transaction context for each active transaction. The transaction context is cleared when transaction is ended / aborted. In error scenarios, sending a prearranged end will clear the transaction.

Allocation / Deallocation of Call Reference ID

Each ongoing TCAP transaction is identified by a call reference ID. The SKIM API layer allocates a call reference ID when a user initiates a transaction or a new transaction is received from the remote end. After initiating a transaction the SKIM API user can retrieve the call reference ID assigned for the new transaction by calling GetCallReferenceId() method of a transaction object.

Call Reference ID and associated resources are deallocated when a transaction is ended/aborted by the SKIM user or remote SS7 entity. The SKIM user can free the call reference ID by calling SendPreArrangedEnd() for a given call reference ID value. TCAP prearranged end terminate transaction locally without sending any TCAP message to remote SS7 entity.

Handler Functions

SKIM API maintains a transaction handler to pass incoming transaction messages to the SKIM user. SKIM API maintains notification handlers to pass incoming notification messages to the SKIM user. SKIM notifications consist of SCCP N-STATE/N-PCSTATE indications, TCAP timeouts, SKIM internal error, and NACK messages from the CSP. The SKIM user must register a transaction handler function and notification handler function as part of SKIM_Api object initialization. The SKIM user can override the default transaction handler function for a given call reference ID.

Most set or get methods return void. If a set or get method is called on in an invalid transaction type, then the method returns void. The set or get methods will have no affect on invalid transaction or operation types.

Handling Multiple
Stack/SSN

The SKIM API user can communicate with multiple stack/SSN combinations configured on the CSP. For each stack/SSN combination the user must create and initialize a SKIM_Api object. Communication to a stack/SSN is controlled using the public interface provided by SKIM_Api object.

SKIM Error Handling

The SKIM API layer maintains a transaction context for each active transaction and provides error handling over and above the TCAP protocol stack. These error conditions are reported to the SKIM user as a notification of type SKIM_NOTIFY_INTERNAL_ERROR. The SKIM user can get the cause of internal error notification by calling the GetCause public method of SKIM_NOTIFY object. Some of the error conditions handled by SKIM API layer are described in the next table:

Resource Limitation Error

This error is returned when a user tries to initiate a transaction but the maximum simultaneous transaction limit has already been reached.

Code Syntax

Each SKIM transaction is uniquely identified by a call reference ID. The Call reference ID is allocated by SKIM when a new transaction is initiated or received. The Call reference ID is released when a transaction is ended or aborted by the SKIM application. SKIM data types and return codes are defined in Appendix 2.

The SwitchKit Interface Module provides the following methods to the application developer.

class SKIM_Api

{

public:

int Initialize(int localNodeId, int stackId, int connId, int pc, int ssn, SKIM_TransHandler h1, SKIM_NotificationHandler h2, void *tag);

int Terminate();

int SSNInService();

int SSNOutOfService();

int Send(SKIM_Trans &trans);

int SendReject(int callrefid, SKIM_OCTET invokeId, SKIM_OCTET probType, SKIM_OCTET probCode);

int CancelOperation(int callrefid, SKIM_OCTET invokeId);

int SendPreArrangedEnd(int calrefid);

int SetTransHandler(int callrefid, SKIM_TransHandler h, void *tag);

int ClearTransHandler(int callrefid);

static int EnableTracing(int traceType);

static int DisableTracing(int traceType);

};