This guide is designed in order to give you the necessary information in order to start using SMSLib. Various support questions made it obvious that the documentation is lucking in some areas. Hopefully, this document will show you how to setup and use SMSLib in your applications.
Beyond this documentation, remember that there are two sample mini apps available, the SendMessage which simply sends a message and the ReadMessages which reads messages from your phone. Be sure to have a look as, sometimes, code speaks better than the documentation. And yes, like any other programmer out there, I hate writing documentation! I prefer to express myself by coding.
By the way, do not forget to view on javadoc documentation pages. My goal and pattern is to document all public methods that are of use to you. So if you find a method that is not documented in javadocs, chances are that you should not use it directly.
You primary interface with SMSLib is the Service class. The entire (almost) functionality of SMSLib is exposed via the Service's methods. You should create only one instance of the Service class in your application!
The Service itself is useless. Before starting the Service, you should define your gateways. Gateways refer to the physical devices or services which can send and/or receive messages. SMSLib has the following predefined gateways:
org.smslib.modem.SerialModemGateway): For modems which are connected via serial ports (or emulated serial ports, like USB etc).org.smslib.modem.IPModemGateway): for modems which are connected via IP interfacesorg.smslib.http.ClickatellHTTPGateway): for sending messages via Clickatell.org.smslib.http.BulkSmsHTTPGateway): for sending messages via BulkSMS.org.smslib.smpp.jsmpp.JSMPPGateway): for sending / receiving messages via the SMPP protocol.Each gateway has different initialization parameters (look at the javadocs for this). The point is to create one or more gateways (according to your setup) and add them to the Service using a syntax like this:
(Service).addGateway(new SerialModemGateway("modem.com1", "COM1", 57600, "Nokia", "6310i"));
Add as many gateways you wish. Once added, SMSLib will manage and use all of them via the rest of the Service class methods
Once you add all the necessary gateways, start the Service by issuing:
(Service).startService()
There are four (4) types of inbound messages that can be handled with SMSLib. These are:
InboundMessage).InboundBinaryMessage).InboundEncryptedMessage, see Encryption).StatusReportMessage, see Delivery reports).There are two ways to read messages:
readMessages() method of the Service class. SMSLib will iterate all defined gateways, collect messages from all and return them in a collection. Note that you will be blocked until SMSLib returns. There are many forms of the readMessages() call - choose the one according to your needs.Service. SMSLib will then automatically call you upon message reception. For more information, see Callback methods.There are again, four (4) types of messages that SMSLib can send. These are:
OutboundMessage).OutboundBinaryMessage).OutboundEncryptedMessage, see Encryption).OutboundWapSIMessage).Each message class has several properties, so check the javadoc for these. You can set the type, the encoding, the delivery report etc.
There are two ways to send a message:
sendMessage() method of the Service class. Note that you will be blocked until SMSLib returns. Upon return, you can examine the message object to see the fate of your message.queueMessage() family of methods to queue your message. Queueing a message returns control immediately to you. SMSLib keeps this message in internal queues and send its in the background. To learn about the fate of your message, you should setup a IOutboundMessageNotification callback method (see Callback methods).The asynchronous sending is covered in a bit more detail in the following section.
To send a message asynchronously, you use the queueMessage family of methods. To send a message at a specific time, you use the queueMessageAt family of methods.
Starting from v3.5, SMSLib queues can be set to operate in a non-persistent or persistent way. In the first case, queued messages are lost between SMSLib invocations (i.e. between Service restarts). This is the default operating mode, compatible with previous versions. If you set SMSLib to work in persistent mode, queued and scheduled messages are retained between SMSLib invocations.
The persistency mode is selected by setting the QUEUE_DIRECTORY parameter. Look at Configurations Parameters for more information on the use of the QUEUE_DIRECTORY parameter.
This section briefly describes the Routing and Balancing concepts. If you use only one Gateway, you may safely skip this section.
When you have more than one Gateways define, you may wonder from which Gateway an outbound message will be sent. SMSLib provides for both an automatic way and a manual way to define your routing.
In order to define the preferred Gateway according to your wishes, you can:
sendMessage() or queueMessage() methods which take the Gateway ID as a parameter. With these methods you can define which is the Gateway that you wish your message to be sent through.OutboundMessage object's setGatewayId() method in order to define your preferred Gateway at a message level.There is also the concept of the wildcard gateway. This is noted by the star character. By setting the gateway to the star character, you actually state that you are letting SMSLib decide which gateway to use.
SMSLib uses a Routing and a Balancing logic in order to automatically determine the gateway to use. Routing logic takes into consideration possible routing rules in order to decide which (of all gateways) are the candidate gateways. Then the Balancing logic gets applied in order to select the preferred of the candidate gateways. This specific gateway is then used for the dispatch of the specific message.
If this all sound complicated, don't be alarmed. SMSLib uses a default set of Routing/Balancing rules which works well all the time. The default Routing rule is actually a "use-any-of" rule, where all gateways are treated as candidates. The default Balancing rule is an implementation of the Round-Robin logic. So, when you have more than one Gateways, all of them are used in turns.