libsua/sualibrary/docs/en/index-4.html

1068 lines
21 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>The Sualibrary Handbook: SUA Application Program Interface (SUA API)</TITLE>
<LINK HREF="index-5.html" REL=next>
<LINK HREF="index-3.html" REL=previous>
<LINK HREF="index.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="index-5.html">Next</A>
<A HREF="index-3.html">Previous</A>
<A HREF="index.html#toc4">Contents</A>
<HR>
<H2><A NAME="s4">4. SUA Application Program Interface (SUA API)</A></H2>
<H2><A NAME="ss4.1">4.1 General API issues.</A>
</H2>
<P>
<H3><A NAME="ss4.1.1">4.1.1 Constants</A>
</H3>
<P>
The maximum size of an IPv4/IPv6 address string is limited to SCTP_MAX_IP_LEN. An endpoint may
(for now) have a maximum number of addresses, which is limited to SCTP_MAX_NUM_ADDRESSES. The
maximum size of a datagram that may be passed to the sctp_send() function is SCTP_MAXIMUM_DATA_
LENGTH. Since we do NOT do proper MTU path discovery in this release, we cannot guarantee that IP
fragmentation occurs, but for Ethernet hardware type and most packets, these settings will ensure that there
is no fragmentation.
<P>
#define SCTP_MAX_IP_LEN 46
<P>
#define SCTP_MAX_NUM_ADDRESSES 20
<P>
#define SCTP_MAXIMUM_DATA_LENGTH 1400
<P>
<P>
<H3><A NAME="ss4.1.2">4.1.2 Type definitions</A>
</H3>
<P>
The main include file of sua.h defines a number of types that are used throughout the library as well as in
some of the interface functions. They will be explained in the subsequent sections.
<P>
<H3><A NAME="ss4.1.3">4.1.3 SUA_ulpCallbacks </A>
</H3>
<P>
This is a structure containing pointers to functions (used as callbacks for SUA events that may occur
and that the ULP needs to be notified of), which are all explained in detail in section 6.5. This structure
is usually initialized early in the program, and then passed to the function sua_registerInstance() (see
section 4.2.2.3), which in turn registers the appropriate functions from this structure for the corresponding
events.
<P>
Definition:
<P>
Struct{ <P>
void (*ulp_ClDataIndNotif) ( unsigned int local_sua_Id, <P>
unsigned int primitive,<P>
unsigned int datalen<P>
);<P>
void (*ulp_ConnIndNotif) ( unsigned int local_sua_id,<P>
unsigned int local_sua_ref,<P>
unsigned int datalen<P>
);<P>
void (*ulp_ConnConfIndNotif) ( unsigned int local_sua_id,<P>
unsigned int local_sua_ref,<P>
unsigned int datalen<P>
);<P>
void (*ulp_ConnDataIndNotif) ( unsigned int local_sua_id, <P>
unsigned int local_sua_ref,<P>
unsigned int datalen <P>
);<P>
void (*ulp_DisConnIndNotif) ( unsigned int local_sua_id,<P>
unsigned int local_sua_ref,<P>
unsigned int reason,<P>
unsigned int datalen<P>
);<P>
} Sua_ULP_CallBacks; <P>
<P>
parameters:<P>
Local_sua_Id : identifies the local SUA instance<P>
Primitive: identifies the CLDT or CLDR in case of a Connectionless Data Notification<P>
Local_sua_ref : reference to the SUA connection used for data transfer<P>
Reason: reason for the release of the SUA connection<P>
<P>
<H3><A NAME="ss4.1.4">4.1.4 SCTP Helper Functions </A>
</H3>
<P>
The libsctp-library contains a few functions that influence the general control flow of a program using
them, and are needed to create an application that works as expected. The important functions needed in
any program using the libsctp-library are the functions sctp_eventLoop()
<P>
<H4><A NAME="ss4.1.4.1">4.1.4.1 sctp_timerCallback </A>
</H4>
<P>
Definition: see also [3].<P>
typedef void (*sctp_timerCallback) (unsigned int, void *, void *); <P>
Defines the callback function that is called when a timer expires. Parameters:<P>
unsigned int ID of timer<P>
void* pointer to param1<P>
void* pointer to param2<P>
param1 and param2 are pointers to data that are returned to the callback function, when the timer expires.
These must still exist at that time and point to valid data !<P>
<P>
<H4><A NAME="ss4.1.4.2">4.1.4.2 sctp_eventLoop() </A>
</H4>
<P>
Basically this is a wrapper to a poll() or select()-system call. The function waits until either of one events
occurrs:<P>
1. the time for which a timer event was scheduled has passed by, so the callback function belonging to
that (previously registered) event is executed.<P>
2. one of the sockets that had previously been registered with the function sua_registerCallback()
or the raw socket that waits for incoming SCTP packets has encountered a read event, so there is data
available. The appropriate function callback is then called to treat that event.
The control flow of the program is given to the callback function which may in turn register new timer
events. The function returns -1 if an error ocurrs, 0 if a timeout has ocurred, or else the number of file
descriptor events that have been treated.<P>
Definition:<P>
int sctp_eventLoop();<P>
<P>
<H4><A NAME="ss4.1.4.3">4.1.4.3 sctp_registerStdinCallback()</A>
</H4>
<P>
6.3.4
This function is supposed to register a callback function for catching input from the Unix STDIN file
descriptor. We expect this to be useful in test programs mainly, so it is provided here for convenience.
Events on this file descriptor are dispatched differently, as applications may read directly from STDIN (i.e.
the callback function buffer does not contain the data from STDIN, and the registered callback function
may retrieve this data with functions as fgets()).<P>
scf callback funtion that is called when data has arrived <P>
It returns 0, or -1 if an error ocurred.<P>
Definition:<P>
int sctp_registerStdinCallback(sctp_socketCallback scf);<P>
<P>
<H4><A NAME="ss4.1.4.4">4.1.4.4 sctp_startTimer() </A>
</H4>
<P>
This function adds a callback that is to be called some time from now. It realizes the timer (in an ordered
list). The function takes the following parameters:<P>
milliseconds action is to be started in milliseconds ms from now<P>
timer_cb pointer to a function to be executed, when timer expires<P>
param1 pointer to be returned to the caller when timer expires<P>
param2 pointer to be returned to the caller when timer expires<P>
The function returns a timer ID value, that can be used to cancel or restart this timer. NOTE: the pointers
param1 and param2 exist to point to data useful for the function callback. They need to point to data
that is still valid at the time the callback is activated. Do not pass pointers to temporary objects !<P>
Definition:<P>
unsigned int sctp_startTimer(unsigned int milliseconds,
sctp_timerCallback timer_cb, void *param1, void *param2); <P>
<P>
<H4><A NAME="ss4.1.4.5">4.1.4.5 sctp_stopTimer() </A>
</H4>
<P>
This function stops a previously started timer. The function takes the following parameter:<P>
tid timer-id of timer to be removed<P>
The function returns 0 on success, 1 if tid not in the list, -1 on error.<P>
Definition:<P>
int sctp_stopTimer(unsigned int tid); <P>
<P>
<H4><A NAME="ss4.1.4.6">4.1.4.6 sctp_restartTimer() </A>
</H4>
<P>
Restarts a timer that is currently running. The function takes the following parameters:<P>
timer_id the timer id returned by start_timer<P>
milliseconds action is to be taken in milliseconds ms from now<P>
The function returns a new timer ID, zero when there is an error (i.e. the timer was not running). The
function basically stops the old timer, and sets a new timer. So it is there for convenience. The timer ID
will be different after calling this function !<P>
Definition:<P>
unsigned int sctp_restartTimer(unsigned int timer_id, unsigned int milliseconds);<P>
<P>
<H4><A NAME="ss4.1.4.7">4.1.4.7 sctp_getTime() </A>
</H4>
<P>
This helper function returns a 32 bit value representing the current time in milliseconds. Beware, this
counter wraps about once per 20 days. Keep that in mind when calculating time differences ! This function
may be useful, or may not be useful.<P>
Definition:<P>
unsigned int sctp_getTime(void);<P>
<H2><A NAME="ss4.2">4.2 standard SUA API</A>
</H2>
<P>
<H3><A NAME="ss4.2.1">4.2.1 ULP-to-SUA </A>
</H3>
<P>
<P>
<H4><A NAME="ss4.2.1.1">4.2.1.1 sua_read_config_file() </A>
</H4>
<P>
sua_read_config_file() is called to fill in the internal SUA database.<P>
The file can contain:<P>
- only IP source address(es) and portnumber(s) of local SUA instance(s) or <P>
- IP source and destination address togethers with the portnumbers for setting up SCTP associations between the specified endpoints.<P>
If the port is not specified then the default SUA port 14001 will be used.<P>
Definition:<P>
unsigned int sua_read_config_file <P>
( char *pConfFile );<P>
Parameters:<P>
*pConfFile: pointer to a char array. Containing the filename Filename has to be terminated with <20>\0<> character.<P>
<P>
<H4><A NAME="ss4.2.1.2">4.2.1.2 sua_registerInstance() </A>
</H4>
<P>
sua_registerInstance() is called to initialize one SUA instance. On the very first call, it will open raw
sockets for capturing SCTP packets (IPv4 and if possible, IPv6, too) from the network. An application may
register several instances with different sets of callback functions, but there should not be several instances
with the same subsystemnumber(local SSN).<P>
Definition:<P>
unsigned int sua_registerInstance<P>
( short local_ssn,<P>
Sua_ULP_CallBacks ulp_callback<P>
);<P>
The function returns the instance name of this new SUA instance.<P>
Parameters:<P>
short local_ssn: SSN used for registering the callback function<P>
Sua_ULP_CallBacks ulp_callback : callbackfunction to be used for that SSN<P>
<P>
<H4><A NAME="ss4.2.1.3">4.2.1.3 sua_unregisterInstance() </A>
</H4>
<P>
???
<P>
<H4><A NAME="ss4.2.1.4">4.2.1.4 sua_associate() </A>
</H4>
<P>
This function is called to set up one or more SCTP associations. It uses the info provided with the configuration file which was entered in the SUA database.<P>
Definition:<P>
unsigned int sua_associate ( );<P>
<P>
<H4><A NAME="ss4.2.1.5">4.2.1.5 sua_shutdown() </A>
</H4>
<P>
???
<P>
<H4><A NAME="ss4.2.1.6">4.2.1.6 sua_send() </A>
</H4>
<P>
sua_send() is used by the ULP to send data as SUA messages. There are quite a few parameters that can be
or must be passed along:<P>
Definition:<P>
unsigned int Send_sua_primitive( unsigned int primitive,<P>
unsigned int &sua_ConnId,<P>
sccp_QOS_str &QOS,<P>
sccp_addr_str &called_pty_address,<P>
sccp_addr_str &calling_pty_address,<P>
char *buffer,<P>
unsigned int len<P>
);<P>
The function returns an error code: -1 for send error, 1 for association error, 0 if successful.<P>
Parameters:<P>
Primitive: the primitive indicating to do CLDT, CODT, CORE, CORE, RELRE,RELCO processing.<P>
sua_ConnID: identifies the connection to be used in case of connection oriented transfer. The field is ignored as input in case of Connectionless CLDT and CORE.
it returns the specific connection identifier in case of the CORE primitive as output.<P>
QOS : specifies the QOS parameters needed with the primitive.<P>
Called_pty_address: provide destination/remote address for connectionless CLDT and connection oriented CORE. Ignored for other primitives <P>
Calling_pty_address: provide source/local address for connectionless CLDT and connection oriented CORE. Ignored for other primitives.<P>
*buffer: application data(memory space MUST be assigned by the application)<P>
Len : length of the application data.<P>
<P>
<H4><A NAME="ss4.2.1.7">4.2.1.7 sua_receive() </A>
</H4>
<P>
sua_receive() is called in response to the DataArrive-Notification to get the received data.<P>
Definition:<P>
unsigned int Receive_sua_primitive( unsigned int &primitive,<P>
unsigned int &sua_ConnId,<P>
sccp_QOS_str &QOS,<P>
sccp_addr_str &called_pty_address,<P>
sccp_addr_str &calling_pty_address,<P>
char *buffer,<P>
unsigned int len<P>
);<P>
It returns 1 if association does not exist, 0 if okay<P>
parameters:<P>
Primitive: the primitive indicating which msg type was received(ex. CLDT, CODT, CORE, CORE, RELRE,RELCO <20>)<P>
sua_ConnID: identifies the connection on which the data is received in case of connection oriented transfer. The field is ignored as input in case of Connectionless CLDT.<P>
QOS : returns the QOS parameters used with the primitive.<P>
Called_pty_address: returns destination/remote address for connectionless CLDT, CLDA and connection oriented CORE. Ignored for other primitives<P>
Calling_pty_address: returns source/local address for connectionless CLDT, CLDA and connection oriented CORE. Ignored for other primitives.<P>
*buffer: application data(memory space MUST be assigned by the application)<P>
Len : length of the application data.<P>
<P>
<H3><A NAME="ss4.2.2">4.2.2 SUA-to-ULP </A>
</H3>
<P>
<P>
<H4><A NAME="ss4.2.2.1">4.2.2.1 Sua address structure </A>
</H4>
<P>
Defines the structure of the source/calling party and the destination/called party address.<P>
The sockaddr, sockaddr_in and sockaddr_in6 address structure can be found in [4].<P>
union sockunion<P>
{ struct sockaddr sa;<P>
struct sockaddr_in sin;<P>
struct sockaddr_in6 sin6;<P>
unsigned char ch[SCTP_MAX_IP_LEN];<P>
};<P>
typedef enum { ITU14bit,<P>
ITU24bit,<P>
ANSI24bit<P>
} SS7pc_set;<P>
typedef struct { <P>
SS7pc_set family;<P>
uint32_t pc;<P>
} SS7_ITU14_str;<P>
/* define structure of SS7 MTP pointcode (ITU/ANSI/other...) */<P>
union SS7union<P>
{<P>
SS7_ITU14_str ITU14;<P>
SS7_ITU14_str ITU24;<P>
SS7_ITU14_str ANSI24;<P>
};<P>
typedef enum { no_pc_present,<P>
ipvx_pc_present, // IPvx(4 or 6) present in pc field<P>
ss7_pc_present // SS7 pointcode present in pc field<P>
} pointcode_set;<P>
typedef enum { no_name_present,<P>
hostname_present,<P>
GT_present<P>
} name_gt_set;<P>
typedef enum { no_sap_present,<P>
ssn_present,<P>
portnumber_present<P>
} application_SAP_set;<P>
typedef enum { include_nothing,<P>
include_pc_in_header,<P>
include_ssn_port_in_header<P>
} sua_header_set;<P>
typedef struct {<P>
pointcode_set pc;<P>
name_gt_set name_gt;<P>
application_SAP_set ssn_port;<P>
sua_header_set field_in_header;<P>
} addr_elements_str;<P>
typedef struct {<P>
SS7union ss7;<P>
sockunion ipvx;<P>
} pointcode_str;<P>
typedef char hostname_str[255];<P>
typedef char global_title_str[255]<P>;
typedef union {<P>
global_title_str GT;<P>
hostname_str HostName;<P>
}name_str;<P>
typedef short application_sap_str;<P>
typedef enum { route_on_ssn, // use pointcode for routing<P>
route_on_name_gt, // use gt/name for routing<P>
route_on_name_gt_next_office, // perform GTT in next node<P>
no_address_present // no routing requested<P>
} routing_type_set;<P>
typedef struct {<P>
addr_elements_str address_fields_present; // which fields are present?<P>
pointcode_str pc; // pointcode field<P>
name_str name; //global title/hostname field<P>
application_sap_str ssn; // application ssn/port<P>
routing_type_set routing_ind; // how must msg be routed<P>
short network_apperance;<P>
} sccp_addr_str;<P>
<P>
<H4><A NAME="ss4.2.2.2">4.2.2.2 sua Quality Of Service(QOS) structure</A>
</H4>
<P>
typedef enum { class0, // connectionless transport, non-sequenced
class1, // connectionless transport, sequenced
class2, // connectionoriented
class3 // connectionoriented with flow control
} protocol_class_set;
typedef struct {
protocol_class_set prot_class; // class 0, 1 or 2
bool in_sequence; // msg delivevered in sequence
short sequence_number; // = stream number
bool return_msg_on_error; // return a CLDR msg on err
short importance; // importance of msg(0..7)
short hopcounter; // hopcounter
} sccp_QOS_str;
<P>
<H4><A NAME="ss4.2.2.3">4.2.2.3 sua ULPcallbackFunctions </A>
</H4>
<P>
typedef struct {
void (*ulp_ClDataIndNotif) ( unsigned int local_sua_Id,
unsigned int primitive,
unsigned int datalen
);
void (*ulp_ConnIndNotif) ( unsigned int local_sua_id,
unsigned int local_sua_ref,
unsigned int datalen
);
void (*ulp_ConnConfIndNotif) ( unsigned int local_sua_id,
unsigned int local_sua_ref,
unsigned int datalen
);
void (*ulp_ConnDataIndNotif) ( unsigned int local_sua_id,
unsigned int local_sua_ref,
unsigned int datalen
);
void (*ulp_DisConnIndNotif) ( unsigned int local_sua_id,
unsigned int local_sua_ref,
unsigned int reason,
unsigned int datalen
);
} Sua_ULP_CallBacks;
<H2><A NAME="ss4.3">4.3 SUA light API</A>
</H2>
This is a Siemens specific interface.
WARNING: The SUA and the SUAL structures, callbackfunctions, config files and functions cannot be mixed with each other.
<P>
<H3><A NAME="ss4.3.1">4.3.1 SUAL address structure</A>
</H3>
<P>
typedef struct sual_PeerAddr {
int AddrType; /* predefined values for AddrType to indicate which
type is used in uPeerAddr: SUAL_ADDRTYPE_IPV4,
SUAL_ADDRTYPE_IPV6 */
union uPeerAddr {
struct in_addr ip4;
struct in6_addr ip6;
} uPeerAddr;
} sual_PeerAddr_t;
typedef enum {
SUAL_ADDRTYPE_IPV4,
SUAL_ADDRTYPE_IPV6
} sual_IpAddrType_t;
<P>
<H3><A NAME="ss4.3.1">4.3.2 SUAL ULPcallbackFunctions</A>
</H3>
<P>
/* SUAL_ULP_CallBacks definitions */
typedef struct sual_ULPcallbackFunctions {
void (*ConnIndNotif)( sual_id_t sual_ConnId,
sual_PeerAddr_t *pPeerAddr,
uint UserDataLen
);
void (*ConnConfNotif)( sual_id_t sual_ConnId,
uint UserDataLen
);
void (*CoDataIndNotif)( sual_id_t sual_ConnId,
uint UserDataLen
);
void (*DisconnIndNotif)( sual_id_t sual_ConnId,
reason_t reason,
uint UserDataLen
);
void (*ClDataIndNotif)( sual_id_t sual_DataId,
uint ControlNumer,
sual_PeerAddr_t *pPeerAddr,
uint UserDataLen
);
} sual_ULPcallbackFunctions_t;
<P>
<H3><A NAME="ss4.3.3">4.3.3 SUAL sual_init ()</A>
</H3>
<P>
extern int sual_init(
unsigned char *pConfFile
);
<P>
<H3><A NAME="ss4.3.4">4.3.4 SUAL sual_RegisterSUAL_Instance ()</A>
</H3>
<P>
extern sual_InstId_t sual_RegisterSUAL_Instance(
sual_port_t LocalPort,
sual_ULPcallbackFunctions_t *pULPcallbackFunctions
);
<P>
<H3><A NAME="ss4.3.5">4.3.5 SUAL sual_ConnReq ()</A>
</H3>
<P>
sual_id_t
sual_ConnReq(
sual_id_t InstId,
sual_PeerAddr_t *pPeerAddr,
unsigned char *pUserData,
uint UserDataLen
);
<P>
<H3><A NAME="ss4.3.6">4.3.6 SUAL sual _ConnResp () </A>
</H3>
<P>
6.6.6
int
sual_ConnResp(
sual_id_t InstId,
sual_id_t sual_ConnId,
unsigned char *pUserData,
uint UserDataLen
);
<P>
<H3><A NAME="ss4.3.7">4.3.7 SUAL sual_DisconnReq () </A>
</H3>
<P>
int
sual_DisconnReq(
sual_id_t InstId,
sual_id_t sual_ConnId,
unsigned char *pUserData,
uint UserDataLen
);
<P>
<H3><A NAME="ss4.3.8">4.3.8 SUAL sual_CoDataRead () </A>
</H3>
<P>
int
sual_CoDataRead(
sual_id_t InstId,
sual_id_t sual_ConnId,
unsigned char *pBuff,
uint BuffLen
);
<P>
<H3><A NAME="ss4.3.9">4.3.9 SUAL sual_ClDataRead () </A>
</H3>
<P>
int
sual_ClDataRead(
sual_id_t InstId,
sual_DataId_t DataId,
unsigned char *pBuff,
uint BuffLen
);
<P>
<H3><A NAME="ss4.3.10">4.3.10 SUAL sual_CoDataReq () </A>
</H3>
<P>
int
sual_CoDataReq(
sual_id_t InstId,
sual_id_t sual_ConnId,
unsigned char *pUserData,
uint UserDataLen
);
<P>
<H3><A NAME="ss4.3.11">4.3.11 SUAL sual_ClDataReq () </A>
</H3>
<P>
int
sual_ClDataReq(
sual_id_t InstId,
sual_PeerAddr_t *pPeerAddr,
uint ControlNumber,
unsigned char *pUserData,
uint UserDataLen
);
<P>
<P>
<HR>
<A HREF="index-5.html">Next</A>
<A HREF="index-3.html">Previous</A>
<A HREF="index.html#toc4">Contents</A>
</BODY>
</HTML>