The simple messaging interface allows the sending and receiving of simple (plain/unformatted) text messages. All of its features are also available in the more powerful rich text interface, which is not complex for plain text messaging. Where possible you should use the newer interface instead.
The methods of this interface are a possible candidate for future deprecation.
The rich text interface, Messages provides all of the functionality that is provided by this interface. The Messages interface is not significantly more complex for the case of simple text messaging, and should be used in preference to this interface.
Receiving messages using the simple interface is more or less identical to using the rich interface (see Section 8.1.2 ― Receiving Messages).
The connection manager will create a new text channels for the incoming chat. Clients will be notified via the usual mechanism (see Section 6.2 ― Incoming Channels). Filter on the new channels for channels of type Channel_Type_Text (see Example 8-2).
Incoming messages are announced with the Received signal on the Channel.Type.Text interface. This is emitted at the same time as Messages.MessageReceived (if for some reason you have both signals connected).
The format for Received is:
| Parameter | Type | Description |
|---|---|---|
| ID | Unsigned integer | The ID used to acknowledge the message, this is the same ID as pending-message-id in the rich interface. |
| Timestamp | Unix timestamp | The time the message was received. The same as message-received. |
| Sender | Handle_Type_Contact | The handle of the message sender. The same as message-sender. |
| Type | Channel_Text_Message_Type | The type of the message: normal, action, notice, auto-reply or delivery report. The same as message-type. |
| Flags | Channel_Text_Message_Flags | Message flags. See Section 8.2.1.1 ― Message Flags. |
| Text | String | The message content as plain text. |
When the channel is created, there may already be pending messages (the messages that created the channel in the first place). The pending messages can be read by calling ListPendingMessages. The Clear parameter should always be set to False (see Section 8.2 ― Simple Messaging Interface). The return type of ListPendingMessages is an array of structs with members the same as the parameters of Received.
Pending messages are acknowledged by a call to AcknowledgePendingMessages, citing the message IDs given by the Received signal. Messages should only be acknowledged after they have been parsed and displayed.
You must always acknowledge a received message, but you should only do so after you have attempted to parse it.
Failure to acknowledge a message will result in a new channel being created with the pending messages when the current channel is closed.
It's posssible that a bug in your application's message parser could cause an application crash. You should attempt to parse the message before acknowledging it. Thus, if your application has a crash, the message will still be pending when the client reloads.
A message may have one or several flags applied to it (as a bitwise OR). These flags have similar meaning to boolean headers that may be present in the rich text interface. They are documented in the spec as the type Channel_Text_Message_Flags. The current flags are documented in Table 8-1.
| Flag | Messages header equivalent | Description |
|---|---|---|
| Truncated | truncated | The incoming message was truncated to a shorter length by the server or the connection manager. |
| Non_Text_Content | - | The incoming message contained non-text content which cannot be represented by this interface. The intention is that if this flag is set, clients should inform the user that part of the message was not understood. |
| Scrollback | scrollback | The incoming message was part of a replay of message history. |
| Rescued | rescued | The incoming message has been seen in a previous channel during the lifetime of the Connection, but had not been acknowledged when that channel closed, causing this channel to open. |
Sending a text message is done using the Send method, which takes a message type (Channel_Text_Message_Type) and a plain text message to send, on an establish text channel (Channel.Type.Text). The receipient(s) of the message are set by the channel, which might either be a one-to-one chat or a chatroom.
If you don't already have one, setting up a new text channel is documented in Section 6.5 ― Text Channels.
All messages sent to a chatroom channel will be transmitted to all members of the chatroom.
To send a private message to a single member of a chatroom (for example, an IRC private message), a whole new channel must be created with that contact as the target.
Similarly, if you are sent a private message. This will appear as a new channel (announced by the signal NewChannels) and not in an existing chatroom you share with that user.