Methods
| DeliverStoredMessages | (as: Stored_Message_Tokens) | → | nothing | |
| ExpungeMessages | (as: Stored_Message_Tokens) | → | nothing | |
| SetStorageState | (b: Out_Of_Storage) | → | nothing |
Signals
| MessagesExpunged | (as: Stored_Message_Tokens) |
Properties
| StoredMessages | as (Protocol_Message_Token_List) | Read only |
Description
This connection interface expands on the Messages interface on Text channels to support store-and-forward messaging protocols like email or SMS. A store-and-forward protocol stores incoming messages persistently—either locally, or on a network server—until a client explicitly expunges the message.
Note that this interface is intended only for situations where guaranteed storage is a regulatory requirement, such as cellular handsets. Most applications interested in incoming messages but which do not have regulatory requirements on storage guarantees should simply register as an Observer for Text channels and listen for the MessageReceived signal, and not concern themselves with this interface.
When a persistently-stored incoming message is first announced in an
emission of MessageReceived,
it MUST contain the stored
Message_Header_Key, mapped to True, and
include a message-token. Clients should pass this token to
ExpungeMessages when they want to remove
the message from the permanent storage; thus, message-tokens
produced by connections implementing this interface MUST uniquely
identify a message.
Clients may request re-delivery of stored messages by calling DeliverStoredMessages; additionally, the CM or protocol MAY choose to re-deliver persistent messages at other times (such as at device start-up). When the message is re-announced by MessageReceived, its message-token MUST be identical to its value in previous announcements, and it SHOULD also contain a rescued header (just as if a channel had been closed with the message still in PendingMessages).
If the client runs out of storage for incoming messages, it may call
SetStorageState(True) to
ask the protocol to pause receiving new messages; when space is
available once again, the client should call
SetStorageState(False) to ask the protocol to resume
receiving messages.
Exactly one client must be responsible for ensuring incoming messages are stored using this interface. This interface does not attempt to ensure that this is the case; the results of multiple client calling ExpungeMessages is undefined and will probably lead to data loss and lawsuits.
Rationale:
We could imagine some kind of elaborate API whereby the CM knows how many processes are interested in persistently logging messages and only acks them to the network when all interested clients have received them. But in practice there will be only one (on the N900, it's the messaging-ui's Observer head). We can always extend this later if we need to.
Methods
DeliverStoredMessages (as: Stored_Message_Tokens) → nothing
Parameters
- Stored_Message_Tokens — as (Protocol_Message_Token_List)
Ask the connection manager or server to redeliver some stored messages. For each token, if the corresponding message is currently in the PendingMessages property of a Text channel, the CM SHOULD do nothing; if not, an appropriate Text channel should be spawned and the message should be re-announced by MessageReceived.
Rationale:
It's pointless to re-announce messages which are already pending on a text channel.
Possible Errors
- Invalid Argument
ExpungeMessages (as: Stored_Message_Tokens) → nothing
Parameters
- Stored_Message_Tokens — as (Protocol_Message_Token_List)
Expunge messages from permanent storage.
Possible Errors
- Invalid Argument
SetStorageState (b: Out_Of_Storage) → nothing
Parameters
- Out_Of_Storage — b
True if client has run out of memory to store the incoming
messages. The protocol will then pause receiving new messages as if it
had run out of storage space itself.
If False, the protocol will try to resume receiving new
messages.
Ask the connection manager to pause or continue reception of incoming messages. Note that most protocols, including SMS, eventually try to resume receiving messages even if the client has indicated that it is out of memory.
Signals
MessagesExpunged (as: Stored_Message_Tokens)
Parameters
- Stored_Message_Tokens — as
Properties
StoredMessages — as (Protocol_Message_Token_List)
A list of message-token values for permanently stored incoming messages that have not been expunged. Its items can be removed using ExpungeMessages. When MessageReceived is emitted by a channel on this connection, the message-token of that message is added to this property; entries being removed from this property are signalled by MessagesExpunged.
Until expunged, the permanently stored messages MAY be presented to the clients again when the Connection restarts, or by calling DeliverStoredMessages.