Server Library

SMSCserverCIMD2

Overview

TypeSMSCserverCIMD2
Namespacesmscs.CIMD2
ParentComponent
InterfacesISMSCserverCIMD2

SMSCserverCIMD2 class implements CIMD2 protocol messaging.

Methods

cimd2FinalizeServer Stop listening to the incoming connections.
cimd2InitializeServer Start listening to the incoming connections.
cimd2SendDeliverMessage Deliver message to the client.
cimd2SendDeliverStatusReport Deliver status report to the client.
cimd2SendLoginResponse Send response to the login message.
cimd2SendRAW Send raw CIMD2 message.
cimd2SendSubmitMessageResponse Send response to a submitted message.
tcpAcceptConnection Accept incomming connection.
tcpCloseAllConnections Closes all active connections maintained by the component.
tcpCloseConnection Close either incomming or existing connection.

Events

OnTcpConnected Event triggered on client connection on network protocol (TCP/IP) level.
OnTcpDisconnected Event triggered on client disconnection on network protocol (TCP/IP) level.
OnCimd2RAWReceived Event triggered on non interpreted (RAW) message receive.
OnCimd2LoginReceived Event triggered on receive of login message.
OnCimd2DeliverResponseReceived Event triggered on receive of a response to message delivered to the client.
OnCimd2SubmitMessageReceived Event triggered on receive of a message submitted by client.
OnCimd2TraceProtocol Event triggered on every CIMD2 protocol message exchanged between component and the SMSC.

Properties

KeepAliveInterval Connection keep-alive timing.
ThrottleRate Message throttling limit parameter.

Public instance methods

cimd2FinalizeServer

Stop listening to the incoming connections.

int cimd2FinalizeServer();

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means Network Error Code.

See Also

cimd2InitializeServer

Start listening to the incoming connections.

int cimd2InitializeServer(string LocalHost, int LocalPort, string ExtendedParameters);

Parameters

LocalHost

Either numeric or symbolic address of local interface that the component should listen on. In most cases should be set to the address of the local host e.g. "127.0.0.1" or left empty to listen on all interfaces.

LocalPort

Port number on which the component should listen to the incoming connections.

ExtendedParameters

Allows passing additional parameters to the function call. For the description and syntax of parameters that can be passed this way see Extended Parameters.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means Network Error Code.

See Also

cimd2SendDeliverMessage

Deliver message to the client.

int cimd2SendDeliverMessage(uint ClientID, uint TransactionNumber, string Destination, string Originator, string Content, EncodingEnum Encoding, string UserDataHeader, int Options, DateTime TimeStamp, string ExtendedParameters);

Parameters

ClientID

Client connection identifier.

TransactionNumber

Transaction identifier.

Destination

Message recipient identifier. Usually this is mobile phone number in fully qualified format.

Originator

Message sender identifier. Usually this is is number of the SMSC's account (a short GSM number). This parameter can also be an alphanumeric string or general phone number where permitted.

Content

The text or content of the message to be sent. The conversion of the characters transferred by parameter to the mobile infrastructure alphabet is done according to the value passed via Encoding parameter.

Encoding

Decides on the which conversion is applied to the Content parameter to convert it to the character set supported by message. Possible values as per EncodingEnum type definition.

UserDataHeader

User Data Header (UDH) for the message. The header must be passed as a byte string in hexadecimal format. For example: "06050415831583" is 7 bytes large header.

Options

Options that can be set to submitted message as per SubmitOptionEnum type definition. It is possible to set more than one option by using the OR operator on the chosen option values.

TimeStamp

Time of the reception of the message by the SMSC.

ExtendedParameters

Allows passing additional parameters to the function call. For the description and syntax of parameters that can be passed this way see Extended Parameters.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means Network Error Code.

See Also

cimd2SendDeliverStatusReport

Deliver status report to the client.

int cimd2SendDeliverStatusReport(int ClientID, int TransactionNumber, DateTime MessageTimeStamp, string Destination, int StatusCode, int StatusErrorCode, DateTime TimeStamp, string ExtendedParameters);

Parameters

ClientID

Client connection identifier.

TransactionNumber

Transaction identifier.

MessageTimeStamp

Time stamp which identifies message.

Destination

Message recipient identifier. Usually this is mobile phone number in fully qualified format.

StatusCode

See CIMD2 Error Codes chapter Status Code section for list of possible values.

StatusErrorCode

If StatusCode indicates error this field carries reason code for the error. See CIMD2 Error Codes chapter Status Error Code section for list of possible values.

TimeStamp

The time and date at which the short message reached it’s final state.

ExtendedParameters

Allows passing additional parameters to the function call. For the description and syntax of parameters that can be passed this way see Extended Parameters.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means Network Error Code.

See Also

cimd2SendLoginResponse

Send response to the login message.

int cimd2SendLoginResponse(uint ClientID, uint TransactionNumber, uint ErrorCode, string ErrorMessage);

Parameters

ClientID

Client connection identifier.

TransactionNumber

Transaction identifier.

ErrorCode

Error Code as defined in CIMD2 Error Codes chapter Error Code section.

ErrorMessage

Readable error message returned to the client.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means Network Error Code.

See Also

cimd2SendRAW

Send raw CIMD2 message.

int cimd2SendRAW(uint ClientID, uint TransactionNumber, uint OperationCode, string Payload);

Parameters

ClientID

Client connection identifier.

TransactionNumber

Transaction identifier.

OperationCode

CIMD2 command identifier.

Payload

Message binary data (except header) in hexadecimal form.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means Network Error Code.

See Also

cimd2SendSubmitMessageResponse

Send response to a submitted message.

int cimd2SendSubmitMessageResponse(uint ClientID, uint TransactionNumber, string Destination, DateTime TimeStamp, uint ErrorCode, string ErrorMessage);

Parameters

ClientID

Client connection identifier.

TransactionNumber

Transaction identifier.

Destination

Message recipient identifier. Usually this is mobile phone number in fully qualified format.

TimeStamp

Time of the reception of the message by the SMSC.

ErrorCode

Error Code as defined in CIMD2 Error Codes chapter Error Code section.

ErrorMessage

Readable error message returned to the client.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means Network Error Code.

See Also

tcpAcceptConnection

Accept incomming connection.

int tcpAcceptConnection(int ClientID);

Parameters

ClientID

Client connection identifier.

Remarks

Function should be used inside OnTcpConnected event handling code.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means Network Error Code.

See Also

tcpCloseAllConnections

Closes all active connections maintained by the component.

void tcpCloseAllConnections();

tcpCloseConnection

Close either incomming or existing connection.

int tcpCloseConnection(int ClientID);

Parameters

ClientID

Client connection identifier.

Remarks

Function should be used inside OnTcpConnected event handling code.

Returns

If the function succeeds, the return value is zero. Negative return value means Internal Error Code. Positive value means Network Error Code.

See Also

Events

OnTcpConnected

The event informs that a clietn has connected to the server. It is then up to the server logic to decide whether to accept or reject such connection. In response to the event either tcpAcceptConnection or tcpCloseConnection should be called inside the event code.

See Also

OnTcpDisconnected

The event informs about the tear down of connection between the component and the SMSC on the network layer level (TCP). Such situation may be due to disconnection by SMSC (as per the rules of protocol after the timeout of inactivity of the component, in the case when connection is not kept alive) and in the case of disconnection for other reasons concerning functioning of the network layer.

See Also

OnCimd2RAWReceived

Event triggered on receive of a CIMD2 message that has not been decoded by any of the functionality serviced by the component.

See Also

OnCimd2LoginReceived

The event informs that the client has issued login message. User can analyze login message credentials and other parameters and decide whether to accept or reject client's communication. In event handler cimd2SendLoginResponse should be called to pass response to the client.

See Also

OnCimd2DeliverResponseReceived

The event informs that the client has confirmed a message delivered. The same event is fired for both a message and status report. To which message is this confirmation can be determined by SequenceNumber parameter.

See Also

OnCimd2SubmitMessageReceived

The event informs that the client has submitted a message to the server. Either cimd2SendSubmitMessageResponse should be called to pass response to the client.

See Also

OnCimd2TraceProtocol

This event allows to log all messages exchanged on the CIMD2 protocol level between the component and the SMSC. Protocol messages are passed as hexadecimally encoded Protocol Data Units (PDU) which is exact binary representation of protocol message.

See Also

Public properties

KeepAliveInterval

Connection keep-alive timing.

int KeepAliveInterval get; set;

Remarks

Value in seconds denoting time interval between packages keeping the connection alive in case no other packages are exchanged with the SMSC. It should be set according to the SMSC operator's instructions and the speed of Internet connection between the component and the SMSC. Typically, this value amounts to one third of the time after which the SMSC breaks the connection in case of lack of activity. When set to zero keep alive packets are never sent to the SMSC.

ThrottleRate

Message throttling limit parameter.

int ThrottleRate get; set;

Remarks

Determines maximum rate of messages submitted to the SMSC per second. If set to any value above 0 component counts number of messages submitted and limits the rate by waiting appropriate time inside cimd2SendDeliverMessage, cimd2SendDeliverStatusReport, cimd2SendSubmitMessageResponse functions. If the value is set to zero component does not limit the rate of delivered messages.