SMSLib can be setup to call specific methods (callbacks) for certain events, like when an inbound message is received.
Following are the available callbacks and the events that trigger them.
SMSLib can be set to call a user-defined method when a message is received by one of its active gateways. This defines an alternative method of receiving messages, instead of continously polling the modem with the readMessages()
method.
The user should implement a class based on the IInboundMessageNotification
interface. The process()
method of this interface is called with three (3) parameters:
The callback method is set by using the Service.setInboundNotification()
method.
Notes:
SMSLib can be set to call a user-defined method when a USSD datagram is received
The user should implement a class based on the IUSSDNotification
interface. The process()
method of this interface is called with two (2) parameters:
The callback method is set by using the Service.setUSSDNotification()
method.
If you sending messages via the queueMessage(s)
methods (i.e. you are using the async sending feature), you are also able to set a callback method so as SMSLib will call this upon successful or unsuccessful dispatch of a message.
The user should implement a class based on the IOutboundMessageNotification
interface. The process()
method of this interface is called with two (2) parameters:
The callback method is set by using the Service.setOutboundNotification()
method.
Notes:
queueMessage(s)
methods (i.e. if you are sending messages via the sendMessage(s)
methods) this callback will never be called.sendMessage()
methods.
SMSLib can be set to call a callback method once a voice call has been received by one of its active gateways.
The user should implement a class based on the ICallNotification
interface. The process()
method of this interface is called with two (2) parameters:
The callback method is set by using the Service.setCallNotification()
method.
Notes:
SMSLib can be set to call a method on every gateway status change.
The user should implement a class based on the IGatewayStatusNotification
interface. The process()
method of this interface is called with three (3) parameters:
The callback method is set by using the Service.setStatusNotification()
method.
If you sending messages via the queueMessage(s)
methods (i.e. you are using the async sending feature), you are also able to set a callback method so as SMSLib will call this after each gateway picks up a message from the queue and before it actually sends it out.
The user should implement a class based on the IQueueSendingNotification
interface. The process()
method of this interface is called with two (2) parameters:
The callback method is set by using the Service.setQueueSendingNotification()
method.
Notes:
IOutboundMessageNotification
once the message is actually sent or failed to be sent.When somebody sends you a big message, this message comes in parts. Sometimes, for unknown network reasons, some parts of a big message never arrive to you, so this message in question is never received completely. Those orphaned message parts are staying in your phone, consuming memory. If you receive too many "incomplete" message parts, those may take up all your modem's memory - effectively disabling it from receiving any other messages. Think something like DDoS...
SMSLib can identify orphaned parts by applying a very simple logic: If a message part is older than (N) hours, this is considered an orphaned message part. In this case, SMSLib will inform you of the situation, by calling the Orphaned notification method. The specific notification method needs to return true
or false
: if you return true
, the message part will be deleted in order to reclaim the lost modem memory. Otherwise (false
) SMSLib will leave it lying around and will try to match it later.
The hours that need to pass in order for a message part to be classified and treated as orphaned is the HOURS_TO_ORPHAN
configuration option (see Configuration parameters). The default setting is 72 hours.
The user should implement a class based on the IOrphanedMessageNotification
interface. The process()
method of this interface is called with two (2) parameters:
If you return true
, the message part will be deleted from the modem. If you return false
, the message part will be left as is.
The callback method is set by using the Service.setOrphanedMessageNotification()
method.
Notes:
IOrphanedMessageNotification
callback method, SMSLib will just leave the orphaned parts lying in memory (i.e. SMSLib will show the pre-v3.2.3 behavior).IOrphanedMessageNotification
method, please note that its important to remove the read messages from the phone once you read them! Do not leave read messages in your phone! There are two reasons behind this: First, the phone/modem does not have enough memory to act as a buffer for all your messaging needs. Store your messages elsewhere! If you phone's memory fills up, you won't be able to receive any more messages, as the new messages will be queued at your network's provider. Second, the logic that identifies messages as "orphaned" may select your real messages as orphaned. If you return true
from your callback method (thinking that this is garbage) you will lose your messages!