IM Service Extension

This is a draft document proposal. Please do not consider any part of this as an actual specification for an extension to the IM Service while this comment exists. If you are interested in this document and would like to discuss it, please join the "meanwhile-devel" list on the Contact page

Background

The IM Service provides for an IM Client ID to be specified by a client when establishing a conversation Channel. This identifier can indicate an implicit feature-set beyond the normal text/typing features of the Lotus Sametime Connect client. For example, use of the NotesBuddy identifier indicates support of HTML, MIME, multi-segment, and subject messages in addition to the text and typing messages of the standard client.

When creating a channel, the initiating client will select its most favorable identifier and specify it in the Channel Create Message. The recipient client can either accept or reject this channel based on that identifier. If the channel is rejected, the initiating client may attempt to create another channel with a different identifier, and continue doing this until the channel is accepted. Normally the very last identifier offered would be that of the standard client, which should be acceptable to all clients.

Problem

A problem with this approach is that it's all-or-nothing support for each set of features; eg. handling only HTML messages locally will not prevent the other client from sending MIME messages. Additionally, if a later revision of a client wished to add any features at all, the updated feature-set would require a whole new identifier. That is to say, if the feature set (A,B,C) was tied to an ID of 0x10, a feature set of (A,B,C,D) would require an all new ID, as would a feature of set of (B,C,D). Negotiation of supported identifiers would have to cascade through a large series of values before both sides of a conversation could agree on a set of features, even between different versions of the same client!

note: it would hypothetically be possible to specify up to 64 individual features using the bitset of the data type and data subtype fields of the IM Data Message, however the meaning of those 64 bits would have to be widely agreed-upon before-hand and recorded openly to prevent collisions.

Resolution

A resolution to this problem would be to explicitly rather than implicitly specify the features supported by initiating client. The accepting client would then simply reply with the intersection of offered features and locally supported features. Both sides would then have an explicit list of features that both sides could support. For example:

  • given two clients, foo and bar
  • foo supports features (A,B,C,D)
  • bar supports features (A,C,D,E)
  • foo initiates with bar, offering (A,B,C,D)
  • bar replies with the intersection of its features and the offered features, (A,C,D)
  • both clients can now safely use the features (A,C,D)

Implementation

This information could be embedded in the "additional" Opaque of the Channel Create Message and the Channel Accept Message. However, the official Lotus libraries do not expose the actual "additional" block, and in order for this solution to become accepted it needs to be feasible for use with the official toolkits. A more functionally acceptable solution would be a type of IM Data Message dedicated to offering/accepting feature lists. Unfortunately, this approach would still require the creation of a new identifier value, just to indicate the "feature" of supporting explicit features.

note: I'd probably use an im client type of 0xffff

note: I'd use a data message type of 0xffff to mean 'feature negotiation', with subtypes 0x00 for 'offered features' and 0x01 for 'accepted features'. It would be the channel creator's job to offer features first, and the recipient would be required to accept features. No other messages could be sent on the channel before feature negotiation was complete!

Features would need to be identified uniquely. As such, a short heirarchial name, such as "st.html" or "st.autoreply" would be ideal.

The offer of features could be as a list of (key:name) pairs, prefixed with a count of features in the list. For example:

uint32 0x0000ffff IM Data Message type (feature negotiation)
uint32 0x00000001 IM Data Message subtype (features offered)
Opaque uint16 0x0002 (two features follow in list)
uint16 0x0001 feature number 1
String "st.mime" name of feature number 1
uint16 0x0002 feature number 2
String "st.html" name of feature number 2

indicating the channel creator supports mime and html messages.

note: that when written to the actual opaque, each string would be prefixed with its own 16bit length header, in addition to the 16bit key value indicated above.

The accepted features could then simply be a list of keys, prefixed with a count of features in the list. Hence:

uint32 0x0000ffff IM Data Message type (feature negotiation)
uint32 0x00000002 IM Data Message subtype (features accepted)
Opaque uint16 0x0001 (one feature in the list)
uint16 0x0002 (accepted feature with key 0x02)

indicating that the channel recipient can support html message. Both sides of the conversation can now safely use text, typing, and NotesBuddy-style HTML as their features.

In order to prevent collisions in IM Data Message sub-types, it is recommended to use the negotiation key as the subtype when sending data for a feature. For instance, in the examples above, when sending a message using the "st.html" feature, the appropriate subtype would be 0x02. These mappings could differ between channels, as the association is arbitrary.

note: the example used a proposed data message type 0xfffe to mean "feature message". The subtype of the feature message would be the key value of the feature associated with the data in the message itself.

Using the examples from before:

uint32 0x0000fffe IM Data Message type (extended feature)
uint32 0x00000002 IM Data Message subtype
Opaque String "Some HTML-formatted text goes here."

would indicate that a message for feature 0x02 (in this case, st.html) was being sent. The subtype value is the key used in the offer and accept messages previously.

Features

Some initially defined features would help to get clients rolling, as such I'd suggest the following base feature set. It would not be necessary for a client to support all, or even any, of these features and still use is service extension method. These are simply offered as a good set of feature definitions to agree upon.

st.html an HTML-formatted message
st.mime a multi-part MIME message, HTML with inline images
st.subject sets the conversation topic/subject
st.autoreply plaintext automated reply
st.autoreply.html automated reply with HTML-formatting
st.pounce a plaintext automated pounce
st.pounce.html automated pounce with HTML-formatting
st.control.segment boundary for multi-segment messages

note: it may be worthwhile to specify multi-segment message control as a required message type, as it's a feature which should be utilized automatically by the API. Automatic breakup of large channel messages into smaller segments can save server resources.

Additional feature definitions can be added by any client, but should be prefixed with the client or project name, for instance "gaim.svg", "kopete.sound", "gpg.signed"

Toolbox
Favorite Categories