kopete/libkopete/API-TODO

   1 This file is a listing of (proposed) changes to be made to libkopete's API.
   2
   3
   4  Buddy Icons:
   5 ==============
   6
   7 Some support for buddy icons is needed in libkopete. Maybe just a simple contact property and a
   8 metacontact property computed from it will do.
   9
  10
  11  Properties:
  12 =============
  13
  14 The current properties system is a bit of a mess. With the PluginDataObjects, the ContactProperties,
  15 KopeteContact's serializeProperties, and the various properties which are stored specially but
  16 shouldn't be (such as KopeteGroup::expanded) it's hard to know where you are. I (Richard) would like
  17 to replace this whole set of different property systems with a unified one. The way I see this
  18 working is as follows:
  19 - An object is created for each property. That object represents the property, and knows how to read
  20   set store and manipulate that property.
  21 - Properties on objects supporting them (KopeteContact, KopeteMetaContact, KopeteGroup, and so on)
  22   will be accessed in a uniform manner, eg:
  23     contact(myProperty) = 42;
  24     metaContact(displayName) = i18n("Ford Prefect");
  25   The exact notation is not finalised yet. Maybe X[...] or X.property(...) would be clearer?
  26 - New types of properties with different serialization requirements and so on can easily be created
  27 - MetaContact properties can be computed from Contact properties (eg, for buddy icon, away message,
  28   idle time and so on) by writing an appropriate property class.
  29 - This system would be extended to plugin configuration, so plugin authors can easily deal with
  30   configuration variables without having to use strings as keys.
  31
  32
  33  KopeteMessageManager:
  34 =======================
  35
  36 KopeteMessageManager should allow any number of views to be attached, from 0
  37 to infinity.
  38
  39 A lot of code should be moved from the KopeteViewManager to the KopeteMessageManager.
  40 Allowing the creation of chatwindow plugin more easy
  41
  42 The chat window should be restructured so each ChatView object has its own
  43 send button.  (-that's not a part of the libkopete api-)
  44
  45
  46  KopeteMessage:
  47 ================
  48
  49 KopeteMessage should be reorganised to use QDomDocument or something similar
  50 to store its contents - the purpose of this is so libkopete can provide a
  51 uniform way of dealing with messages; the emoticon and link-adding filters
  52 don't then need to grok HTML in order to be able to mangle a message
  53
  54
  55  KopeteContactList
  56 ===================
  57
  58 Add to KopeteMetaContact a statusPixmap() function to return the pixmap
  59 associated with its name. Take implementation from KopeteMetaContactLVI.
  60 Use this function in the Kopete::MimeSourceFactory so we get MCs being
  61 grayed if they're idle in tooltips too.
  62
  63 KopeteContactList::removeGroup should remove the group from all
  64 metacontacts. Move code from KopeteContactListView to KopeteContactList for
  65 this.
  66
  67 KopeteContactList::findContact and KopeteMetaContact::findContact should maybe be removed,
  68 or at least contains ptr to accounts insteads of id.
  69
  70 KopeteContact::slotDeleteContact should be renamed, maybe return a bool to cancel the deletion of the contact.
  71
  72 Add an iconName() function to contacts, metacontacts and accounts returning a string that
  73 can be put in an <img src="%1"> in any rich text to give the appropriate icon. See the
  74 MimeSourceFactory.
  75
  76 KCL::selectedMetaContacts really doesn't belong here. A contact list shouldn't
  77 have a concept of selected items (this is action- and UI-specific knowledge).
  78 The only place this is used is when plugins' actions need to be enabled and
  79 disabled, or applied. Find a better way to do this UI-specific task.
  80 KCL::selectedGroups can be removed outright.
  81
  82
  83  KopeteEmoticon
  84 ================
  85
  86 Allow emoticons and emoticon sets to be flagged as being for only a specific protocol.
  87 Allow the user to have more than one emoticon set enabled at once, and to set priorities.
  88 This way, the user will be able to have a base theme, a set of MSN-specific emoticons, a
  89 set of Gadu-Gadu-specific emoticons and so on.
  90
  91 Possibly move emoticon support into a plugin?
  92
  93
  94  KopeteOnlineStatus
  95 ====================
  96
  97 Add an Unknown status to KopeteOnlineStatus for when the status of a
  98 contact is unknown (in the case that they've not authorised you, or the
  99 protocol does not provide presence information) and a status for Unreachable
 100 (in the case that your account is offline, etc). The crucial difference is
 101 that a contact with Unknown status may be reachable (though that contact
 102 should probably be avoided for messaging unless nothing else is available).
 103
 104 More granular away settings: see Bug 57297.
 105 The number of different global statuses (away / busy / be right back) should
 106 be extended to a configurable list where each element contains the name of the
 107 status, the default away message, and the KOS for every account)... though
 108 perhaps this would be better placed in an 'advanced status' plugin?
 109
 110 Add a way to register automatically KOS. The code for the right-click menu in
 111 the Kopete account tray is duplicated all over the place; this should be
 112 done automatically by the account tray code.
 113
 114
 115  KopeteAccount
 116 ===============
 117
 118 KopeteAccount::password should be split in two method: KopeteAccount::password which return the
 119 remembered password if any, but which does not try to ask it to the user.  and getPassword which
 120 acts like the acutal function.
 121
 122 <lilachaze> KopeteAccount will soon have no ::password. instead, use Kopete::PasswordedAccount,
 123             and acct.password().request(...) or acct.password().cachedValue()
 124
 125
 126  DCOP
 127 ======
 128 The DCOP interface needs to be totally re-done so as to be useful, and to hopefully not rely on
 129 display names. Obsolete functions previously used only for DCOP should be removed from KopeteContactList
 130 where applicable.
 131
 132
 133  KopeteTransferManager
 134 =======================
 135
 136 The file transfer mechanisms should be available to plugins... ie, a plugin should be able to
 137 both initiate file transfers, and intercept and possibly cancel file transfer requests, the exact
 138 same as plugins can ( will ) be able to filter KopeteMessages ( see below ).
 139
 140
 141  Message Processing
 142 ====================
 143
 144 Some sort of async message processing API needs to be designed and implemented
 145 Richard's proposal: (email questions to the list or to kde@metafoo.co.uk)
 146 - how do we order the various message filters available properly?
 147   they give us a processing stage, and an offset within that stage. the
 148   stages will be something like:
 149    for an incoming message:
 150       - Start     - message was just received (History)
 151       - ToSent    - convert from received format to sent format (GPG)
 152       - ToDesired - convert to how the user wants the message (Translator, AutoReplace)
 153          ToDesired+Before - Highlight
 154       - Format    - decorate the message (without changing the content) (Links, Emoticons, TextEffect)
 155       - Finished  - message is now ready for display (ChatWindow / MessageQueue)
 156    for an outgoing message:
 157       - Start     - user just hit Send
 158       - Parse     - process commands (CommandHandler, Alias, Now Listening)
 159          Parse+After - History
 160       - ToDesired - convert to how the user wanted to send (Translator, AutoReplace)
 161       - Format    - decorate the message (without changing the content) (TextEffect)
 162       - ToSent    - convert to the format to send in (GPG)
 163       - Finished  - message is now ready for sending (Protocols)
 164    There should be a number of offsets defined for when to do the
 165    processing, within a stage, such as:
 166       - Before    - before any other processing in this stage
 167       - VeryEarly
 168       - Early
 169       - Normal
 170       - Late
 171       - VeryLate
 172       - After     - after any other processing in this stage
 173 - how do we construct a set of message filters for a particular message
 174   manager?
 175    - message filters register themselves with the filter manager, with a
 176      message direction, a stage and an offset within that stage.
 177    - each registered message filter factory gets queried (in stage/offset
 178      order) by the object creating the filter chain. it either returns a
 179      new filter for the chain, or returns NULL (meaning this filter is not
 180      needed in this chain).
 181    - the signals in one filter are connected to the slots in the next. any
 182      sent/received message is handed to the first filter in the appropriate
 183      chain.
 184 - how long does a filter chain live for?
 185    - it's created when it's first needed (when a message is sent / received
 186      and no chain already exists to process it, or when a chatwindow is
 187      opened)
 188    - it's reference counted
 189    - the MessageQueue / ChatWindow holds a reference to its chains
 190    - the chain knows how many messages are in it (the messages unregister
 191      themselves when they're destroyed)
 192    - this makes it trivial to implement 65803 - stay in chatwindows when no
 193      window is open - just make the Kopete::Contact hold a reference to the
 194      receive chain
 195 - interactions with the chat manager
 196    - the chat manager (or possibly just 'chat') is an abstraction for a
 197      conversation between our client/user and some other computer/user. it's
 198      a bit like the message manager we have now, but more sophisticated.
 199    - the send and receive chains are fundamentally linked - they are owned
 200      by the same chat manager (which has a chainFor(MessageDirection)
 201      function)
 202    - when a chain's reference count drops to 0, it stays alive until
 203      all the messages in it have been processed, but calls to
 204      chainFor(Outgoing) will create a new chain. if we want, we can
 205      guarantee messages from the old chain get sent over the wire before
 206      ones from the new chain, but it's probably not essential.
 207 - interactions with a chat view
 208    - the ChatWindow component above is actually the ChatWindowFilter. it's
 209      owned by the filter chain, and so should not be a QWidget.
 210    - when a chat view is closed, it drops its reference to the various
 211      message chains. but the receive chain will still exist if there's an
 212      incoming message that's still being processed. therefore:
 213    - the chatwindow prompts you if you ask it to be closed and there are
 214      messages left in its receive chain
 215    - the chatwindow filter will *drop* messages that reach it if there's no
 216      chatview available to send them to. but that's ok since the user will
 217      already have been prompted about this.
 218 - problems with this design
 219    - when the receive chain is closed (refcount drops to 0), it's not
 220      necessarily the case that messages in it still need to be processed.
 221      for instance, if you don't use the History plugin, or all the messages
 222      are already past it, it probably doesn't matter if they're dropped. we
 223      should somehow allow the filters to prevent destruction of the part of
 224      the chain before them, and if none of them does, destroy it.
 225
 226
 227
 228  Invitation Handling Proposal:
 229 ===============================
 230
 231 Invitations is framework that allow others network applications (Games, Desktop
 232 Sharing, Video conference, [file transfer?], ...) to initiate the communication
 233 with kopete. (like Windows Messenger does)
 234
 235 The user has two ways to initiate such as thing:
 236
 237 - in the application itself, they could (with the help of KABC) select a
 238   contactable contact; the invitaiton is transported to Kopete.
 239 - in Kopete, in the chat window, an "tools" menu, with all possible actions.
 240
 241
 242
 243  Blacklist support:
 244 ====================
 245
 246 <roie> BlackList API is added. Protocols maintainers, please check if a contact
 247        is blocked before passing messages to MessageManager.
 248        I will also attach the GUI to block() and unblock() in the near future.