Server Library

SMSCserverUCP

Overview

TypeSMSCserverUCP
Namespacesmscs.UCP
ParentComponent
InterfacesISMSCserverUCP

SMSCserverUCP class implements UCP protocol messaging.

Methods

tcpAcceptConnection Accept incomming connection.
tcpCloseAllConnections Closes all active connections maintained by the component.
tcpCloseConnection Close either incomming or existing connection.
ucpFinalizeServer Stop listening to the incoming connections.
ucpInitializeServer Start listening to the incoming connections.
ucpSendDeliverMessage Deliver message to the client.
ucpSendDeliverStatusReport Deliver status report to the client.
ucpSendLoginResponse Send response to the login message.
ucpSendRAW Send raw UCP message.
ucpSendSubmitMessageResponse Send response to a submitted message.

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.
OnUcpRAWReceived Event triggered on non interpreted (RAW) message receive.
OnUcpLoginReceived Event triggered on receive of login message.
OnUcpDeliverResponseReceived Event triggered on receive of a response to message delivered to the client.
OnUcpSubmitMessageReceived Event triggered on receive of a message submitted by client.
OnUcpTraceProtocol Event triggered on every UCP protocol message exchanged between component and the SMSC.

Properties

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

Public instance methods

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

ucpFinalizeServer

Stop listening to the incoming connections.

int ucpFinalizeServer();

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

ucpInitializeServer

Start listening to the incoming connections.

int ucpInitializeServer(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

ucpSendDeliverMessage

Deliver message to the client.

int ucpSendDeliverMessage(uint ClientID, uint TransactionNumber, string Destination, string Originator, string Content, EncodingEnum Encoding, string UserDataHeader, int Options);

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.

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

ucpSendDeliverStatusReport

Deliver status report to the client.

int ucpSendDeliverStatusReport(uint ClientID, uint TransactionNumber, DateTime DeliveryTimeStamp, string Destination, string Originator, int DeliveryStatus, int ReasonCode, string Text, DateTime TimeStamp);

Parameters

ClientID

Client connection identifier.

TransactionNumber

Transaction identifier.

DeliveryTimeStamp

The time and date at which the short message reached its final state.

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.

DeliveryStatus

See UCP Error Codes chapter Delivery Status section for list of possible values.

ReasonCode

Failure reason in the process of delivering the message. See UCP Error Codes chapter Reason Code section for list of possible values.

Text

The text or content of the status report message received. In some configurations contains additional information or commentary on error codes returned.

TimeStamp

Time stamp which identifies message.

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

ucpSendLoginResponse

Send response to the login message.

int ucpSendLoginResponse(uint ClientID, uint TransactionNumber, ucpResponseType ResponseType, uint ErrorCode, string SystemMessage);

Parameters

ClientID

Client connection identifier.

TransactionNumber

Transaction identifier.

ResponseType

Response Type.

ErrorCode

Error Code as defined in Error Code section.

SystemMessage

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

ucpSendRAW

Send raw UCP message.

int ucpSendRAW(uint ClientID, uint TransactionNumber, string OperationClass, uint OperationType, string Payload);

Parameters

ClientID

Client connection identifier.

TransactionNumber

Transaction identifier.

OperationClass

UCP command identifier.

OperationType

UCP 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

ucpSendSubmitMessageResponse

Send response to a submitted message.

int ucpSendSubmitMessageResponse(uint ClientID, uint TransactionNumber, ucpResponseType ResponseType, uint ErrorCode, string Destination, DateTime TimeStamp);

Parameters

ClientID

Client connection identifier.

TransactionNumber

Transaction identifier.

ResponseType

Response Type.

ErrorCode

Error Code as defined in Error Code section.

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.

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

OnUcpRAWReceived

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

See Also

OnUcpLoginReceived

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 ucpSendLoginResponse should be called to pass response to the client.

See Also

OnUcpDeliverResponseReceived

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

OnUcpSubmitMessageReceived

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

See Also

OnUcpTraceProtocol

This event allows to log all messages exchanged on the UCP 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 ucpSendDeliverMessage, ucpSendDeliverStatusReport, ucpSendSubmitMessageResponse functions. If the value is set to zero component does not limit the rate of delivered messages.