MSN Protocol library ideas

Ideas:

  • Remove all KDE dependencies to obtain a library depends only by QT ( portable ).
  • Port the library to MSNP15.
  • Provide a stable binary compatible API. -> can't likely be provided in the same KMess revision. needs testing first.
  • Allow (scriptable) plugins to interact with this central class too.
  • Name it something like "libkmess-msn". love to have some branding in it. and "libmsn" is already taken.

Classes:

Which classes must be part of this library?

  • All classes in network/
  • Some basic session details currently found in Current Account.
  • need to town ChatMaster apart (will mostly re-appear as the central class below, or as internal utility of that central class)
  • need to get rid of CurrentAccount in the networking code (refer to the central class instead, see below).
  • need to get rid of the final GUI methods in the networking code (like KFileDialog::getSaveFileName()).

What shouldn't be done by this library:

  • Contact administration. Instead it just signals about all contacts, and let the app deside what to do with it.
  • Make assumptions over the way it's being used. The #1 error with designing an API is to make it specific for a specific use-case.

Central class design

In the library we shouldn't expose MsnSwithboardConnection or MsnNotificationConnection because we need to make changes to those classes with an MSN protocol upgrade/change. Instead we should provide a central class per which tracks all aspects of the msn session. This class instructs the NS, SB, SOAP and P2P classes to do their job. By letting this class handle all aspects of one MSN session, you can easily create a second instance to connect with multiple accounts at the same time.

Not sure about the class name yet, thinking about KMessMsnSession.

The resuling flow would become:

[app gui code] <--> KMessMsnSession <--> networking code

Since the central object shouldn't pass the references to the NS / SB classes, it will pass ID's instead (read: handles). That way the app code becomes easier, and the internal object structure is hidden from the external API users.

The handles will be generated from one central static counter, so you won't ever have duplicate ID's for different objects you can mix up.

Methods

Most envisioned methods.

The signals start with "got" and I think it's a good idea to return the ID of the central class in some of these signals. That way you can distinguish between the signals from different instances (=different msn sessions).

Instead of using "got" a "received" prefix would be more descriptive, but perhaps a bit too verbose and long too type?

Informative methods:

  • getProtocolVersion() // returns MSNP15
  • getClientCapabilities() // caps this library supports right now

Configuration:

  • setClientName( "KMess/2.0" ) // to display the app name in the clientcaps message.
  • setGlobalOptions( QMap ) // some settings which should be respected by the networking code
  • setProxyOptions() // to configure Qt networking classes.
  • setConnectivityOptions() // how to connect

Starting the session:

  • login( username, password ) // main startup, initiates the connection
  • logout()
  • isConnected()
  • getSessionId() // ID of this object, useful if you have multiple instances.
  • gotProfileData() [signal] // map/object with all profile fields.
  • gotConnected() [signal] // managed to connect with msn!

Configure user account:

  • setUserProperty( property, value ) // set name, phone number, etc..
  • gotUserProperty( sid, property, value) // received a PRP command
  • setDisplayPicture( file )
  • setStatus( ... ) // online, away, brb
  • setPersonalMessage( msg )
  • setNowPlaying( ... )

Notifications:

  • gotMailAnnouncement( sid, folder, subject, sender )
  • gotMailMoveAnnouncement( sid, srcfolder, destFolder, delta, newTotal )
  • statusChanged( sid, status )
  • contactStatusChanged( contact, status )
  • contactNowPlayingChanged( ... )
  • contactPersonalMessageChanged( ... )

List updates:

  • addContactGroup()
  • removeContactGroup()
  • renameContactGroup()
  • addContact()
  • removeContact()
  • blockContact()
  • unblockContact()
  • copyContact()
  • moveContact()
  • setContactProperty( contact, property, value )

Signals:

  • gotContactGroup( sid, gid, name )
  • contactAdded( contact, listType )
  • contactRemoved( contact, listType )
  • contactPropertyChanged( contact, property, newValue )

Chat sessions:

  • gotChatInvitation( sid, chatId, contact ) // auto accepted?
  • getContactsInChat( chatId )
  • getChatSessions()
  • getActiveChatSessions()

Chat session signals:

  • contactJoinedChat( chatId )
  • contactLeftChat( chatId )

Server errors:

  • gotServerError( code, description, chatId )
  • gotClientError( type, description, chatId )

Chat messages:

  • gotTypingNotification( chatId )
  • gotChatMessage( chatId, contact, type, message )
  • gotNudge( chatId, contact)

Sending chat messages:

  • sendChatMessage( chatId, format, message )

Msn Object receiving:

  • gotMsnObjectAnnouncement( id, type, filename, sha1d, sha1c ) // call downloadMsnObject() when you need it.
  • downloadMsnObject( id )
  • gotMsnObject( id, filedata )

Msn Object sending:

  • sendMsnObjectAnnouncement( chatId, type, filename, sha1d, sha1c )
  • gotMsnObjectRequest( chatId, sha1c )

Offline IM messages:

  • gotOfflineMessageAnnouncement( id, contact, remaining ) // call downloadOfflineMessage() when you like
  • downloadOfflineMessage( id )
  • gotOfflineMessage( id, runId, contact ) could use gotChatMessage() instead, unless this assumption limits the use.
  • send offline messages automatically? and notify the chat mode switched to offline?

Receiving files:

  • gotFileTransferInvitation( inviteId, chatId, contact, filename, filesize, preview )
  • acceptFileTransferInvitation( inviteId, saveFileTo )
  • abortInvitation( inviteId )
  • declineInvitation( inviteId )

Sending files: -> sendFile( contact, file ) -> completedFileSending( file )

Decibel integration

Task: find out how flexible decibel/telepathy is regarding this wish list. I noticed telepathy has an MSN extension somewhere, which makes me wonder how flexible it is at all. If we need a telepathy spec update to add a new message type, it wouldn't work very well for us.