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:

Gateway Id: The ID of the gateway which received a message.
Message Type: The type of the received message.
Message: The actual message received.

The callback method is set by using the Service.setInboundNotification() method.

Notes:

In case you receive a multi-part (big) message, the callback method will be called when all parts are received. The message will then be the complete, large message.
The correct operation of this method depends on the unsolicited modem indications and on the correct operation of the CNMI command. If you see that you are failing to receive messages using a callback method, probably the modem indications have not been setup correctly.
A alternate way of dealing with inbound messages is to use a callback method for receiving messages and also implement polling using a big polling interval.

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:

Gateway Id: The ID of the gateway which triggered this event.
Message: The actual message sent.

The callback method is set by using the Service.setOutboundNotification() method.

Notes:

If you are not using the queueMessage(s) methods (i.e. if you are sending messages via the sendMessage(s) methods) this callback will never be called.
Once called, the message parameter will be updated with the correct status. So you can query it in order to find out whether the message was actually sent or not, etc.

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:

Gateway Id: The ID of the gateway which received the voice call.
Caller Id: The caller id of the caller.

The callback method is set by using the Service.setCallNotification() method.

Notes:

The default SMSLib behavior when a voice call is received is to call any previously set callback method and then automatically hangup the call. This behavior cannot be changed.

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:

Gateway Id: The ID of the gateway which changed status.
Old Status: The old status.
New Status: The new status.

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:

Gateway Id: The ID of the gateway which triggered this event.
Message: The actual message which is about to be sent.

The callback method is set by using the Service.setQueueSendingNotification() method.

Notes:

Because the notification method is called with the actual message, the message which is about to be sent can be modified. This is both a feature and a security hole, so be careful!
For each message send via the background queues, you should expect one call to this method (before the message is sent) and one call to the IOutboundMessageNotification once the message is actually sent or failed to be sent.

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:

Gateway Id: The ID of the gateway which received the message part.
Message: The orphaned message part in question.

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:

If you do not implement the IOrphanedMessageNotification callback method, SMSLib will just leave the orphaned parts lying in memory (i.e. SMSLib will show the pre-v3.2.3 behavior).
If you choose to implement the 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!
The "orphaned" detection method has one important drawback that you should be aware of: assuming you left your modem switched off for a week, when you switch it on messages will start to arrive. Since all messages will be "old", this may trigger the "orphaning" logic which will mark probably correct message parts. So when you have your modem switched off for prolonged periods, be careful!!!