Callback Methods

Introduction

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.

Inbound Messages

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:

Inbound USSD messages

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.

Outbound Messages

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:

Inbound calls

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:

Gateway Status changes

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.

Queue Sending operation

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:

Orphaned message parts

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: