[Telepathy] TelepathyQt4: State of the Connection

[Olli Salli]

On Thu, Feb 5, 2009 at 12:17 PM, Olli Salli <ollisal at gmail.com> wrote:
> Hi,
>
> I have to run now, will provide insight on how I would cleanly
> implement the desired behavior later on - stay tuned. And please
> review my contacts branch :)

Ok, I'm back, so beware foul current Connection implementation. Thanks
for the review, that branch has since been merged, and TelepathyQt4
now sports full-featured high-level Contact objects.

My 2 cents on the "desired behavior":

Assumptions:
  - Connection can be ready for use in two states - before it's
connected, and when it's connected
  - Connection has optional features
    - Each of these features can be at least partially usable in both
the pre-connected and connected states
      - including the simple case of being not usable in one of the
states (usually Disconnected) while completely usable in the other
(usually Connected)
    - May need state download
      - May need independent state download in both the offline and
online cases (eg. interfaces need to be downloaded again)
    - Have dependencies
      - May need specific Connection interfaces
        - So depend on interface download (which should be core)
          - eg. SimplePresence support works only if
C.I.SimplePresence is present
      - May depend on other features
         - If we decide to make ContactAttributeInterfaces/other
Contacts functionality an optional feature (might make sense),
SelfContact will depend on it
         - In either case, SelfContactAvatar etc will depend on SelfContact
    - Might stay fixed for the connection's lifetime, so don't want
change notification for all of them
      - eg. ContactAttributeInterfaces - should be downloaded once
when the Connection goes online, and not be touched after that

We previously decided on IRC that the public API should have:
  - PendingOperation *becomeReady(Features)
    - will only ever finish when
      - Core (non-feature) download for the current state is complete
      - The requested features download for the current state is complete
    - the connection state can change between the time becomeReady()
is called and the time it would be ready to finish
      - have to check the finishing criteria at the finish time, not
when creating the PendingOperation
        - eg. Connection offline -> becomeReady(F) -> core and half of
F downloaded for offline -> connection online -> core and F downloaded
again from the start for online -> finished
        - NOT: offline -> becomeReady(F) -> core and half of F DLed
for offline -> online -> the rest of F DLed for online -> finished
        - AND NEITHER: offline -> becomeReady(F) -> core and half of F
DLed for offline -> online -> central introspect queue cleared ->
finished with half of F still missing
  - bool isReady(Features)
    - quite simply, should tell that "if I had called becomeReady just
now, would it have finished immediately AND successfully, without
doing anything else affecting the state of the Connection object?"
  - statusChanged(newStatus)
    - note: no reason - this is only useful for the connection
becoming disconnected, and is more appropriately signaled by the base
class invalidated() signal
    - is only emitted when:
      - core has been downloaded for the new state
      - features previously asked for by becomeReady in ANY state have
been downloaded for the new state
    - note that the emission criteria *is exactly equivalent to when
isReady(<union of all features in previous becomeReady calls>) would
return true*
    - DON'T DO:
      - emit statusChanged for Connected, and later on emit misc
signals for all the features being retrieved - otherwise you need
logic handling for factorial(numberOfFeaturesYouAskedFor) event
occurrence orders in user code!
  - accessors for the data provided for each Feature
  - change notification for the data provided for each Feature for the
data which might change
    - and NONE other

More on how I would implement this in the next mail.

-- 

Br,
Olli Salli