Client Library

Usage Overview

Communication Outline

The below diagram common for all protocols shows outline of functions and events flow during communication between the component and SMSC:

Communication outline diagram

Naming Convention

To make documentation universal protocol part of the name of functions and events is removed as in the examples below:

METHODS smppInitializeSession = InitializeSession
smppSubmitMessage = SubmitMessage

EVENTS OnSmppMessageReceived = OnMessageReceived
OnSmppStatusReportReceived = OnStatusReportReceived

Session Maintenance

Typical schema of cooperation between the component and the SMSC starts with establishing a connection on the network level with tcpConnect function.

After the connection has been established, session with the SMSC should be initialized. To initialize a session use InitializeSession. For most protocols it is an equivalent of login procedure which authenticates client to the SMSC. FinalizeSession function, if present in particular the protocol, is adequately an equivalent of logout procedure.

The tcpDisconnected event signals the end of the connection between a component and the SMSC. It is invoked in the case of disconnection due to use of the function tcpDisconnect, when the connection is terminated by the SMSC, as well as in the case of disconnection for any other reasons.

Submitting and Receiving Messages

The connection with the SMSC is active from the moment of correct execution of the InitializeSession function. This means ability to send messages using SubmitMessage function. If during sending of the message soRequestStatusReport option is chosen - the SMSC will be submitting, using the OnStatusReportReceived event, information about the message delivery status commonly referred to as status reports.

After initialization of the connection, the SMSC will start delivery of messages stored on the account that is bound with the user. The messages stored on the account will be sent using the OnMessageReceived event. Messages that will be received by the SMSC from mobile phones during the connection, will also be instantly delivered using the OnMessageReceived event.

Messages in the SMSC are stored until they are retrieved by client application. Maximum storage time is usually up to 72 hours. When the client's application has finished the procedure of picking up messages, the message is removed from the SMSC and it will no be reported any more. The message is also considered by the SMSC to be delivered correctly at the end of the OnMessageReceived code. The performance of the user code responsible for handling the OnMessageReceived event affects the overall performance of the messages handling process. It hinders the possibility of loosing the message in case there is a critical error in the code responsible for the OnMessageReceived event.

The time spent within the event handling code should be short enough not to exceed the SMSCs communication timeout. Otherwise the component may not confirm the receive of the message on time thus causing the message to be unnecessarily resent by SMSC. It indicates that the messages should rather not be processed or responded to within the OnMessageReceived handler code. Instead the fact of receiving the message should be registered in the database or elsewhere, and then a response message should be send from the application's main message loop.

Receiving Status Reports

When message is submitted to the SMSC it receives a unique Message ID. Message ID may be, depending on the protocol and configuration of the SMSC a single string identifier or a number or a combination of more than one field. The SMSC takes care of it's uniqueness and thus guarantees that the status reports returned via OnStatusReportReceived can always be matched with appropriate submissions.

Properties

The property ResponseTimeOut is responsible for determining how long the component waits for response from the SMSC during the communication process. If during an exchange of data packages with the SMSC, there is a delay exceeding the wait time reckoned by value assigned to this property, the function, which was being executed will end functioning returning an error code.

Typically, after some time of inactivity of the component the SMSC breaks up the connection. Property KeepAliveInterval tells the component that it has to keep the connection with the SMSC alive by sending a dedicated package each number of inactivity seconds equal to the property's value. If the KeepAliveInterval property is set to 0 the connection activity is not maintained.

In practical situations the value of the KeepAliveInterval property should be set to about one third of the time, after which the SMSC closes inactive connection.

Keeping connection alive is done automatically and it is performed so as to introduce the least possible traffic on the connection.

Error handling

The library is constructed in such a way that in the basic model there is no need to handle any error codes specific to a particular communication protocol. However if that would be of any use for the user the codes are returned by all the communication functions, particularly InitializeSession, SubmitMessage. This allows to handle some specific behaviour depending on SMSC and protocol specific error codes.

Similarly the error codes of the underlying network layer (Windows Sockets) are returned by the function tcpConnect in case of any error.

See Also

Library Reference, Session Maintenance, Submit Message, Receive Message, Receive Status Report, Error Codes