[Telepathy] RFC: draft chat state interface specification

[Dafydd Harries]

This dract is heavily based upon the relevant Jabber specification[0].

class ChannelInterfaceChatState(dbus.service.Interface):
    """
    An interface for channels for receiving notifications of remote contacts'
    states, and for notifying remote contacts of the local state.

    The following states are defined:

     0 - CHAT_STATE_GONE
         The contact has effectively ceased participating in the chat.
     1 - CHAT_STATE_INACTIVE
         The contact has not been active for some time.
     2 - CHAT_STATE_ACTIVE
         The contact is actively participating in the chat.
     3 - CHAT_STATE_PAUSED
         The contact has paused composing a message.
     4 - CHAT_STATE_COMPOSING
         The contact is composing a message to be sent to the chat.

    Clients should assume that a contact's state is CHAT_STATE_INACTIVE unless
    they receive a notification otherwise.

    The CHAT_STATE_GONE state is treated differently to other states:

     - It is not used for multi-user chats;
     - It is implictly set when the channel is closed;
     - It may not be explicitly set.
    """

    @dbus.service.method(CHANNEL_TYPE_TEXT, in_signature='u', out_signature='')
    def SetState(self, state):
        """
        Set the local state and notify other members of the channel that it
        has changed.

        Parameters:
        state - the new local state
        """

    @dbus.service.signal(CHANNEL_TYPE_TEXT, signature='uu')
    def StateChanged(self, contact, state):
        """
        Emitted when somebody's state has changed. This includes local
        state.

        Parameters:
        contact - the contact whose state has changed
        state - their new state
        """

[0] http://www.jabber.org/jeps/jep-0085.html

-- 
Dafydd