Update to the Weather DataEngine 'Ion' API

[Andrew Coles]

I'm just writing a few notes on the changes Shawn and I made to the Weather Ion API due to a bug where a dropped network connection would lead to uninitialised junk being sent to plasmoids.  It was reported in the context of KDE 4.2, and though it can't be fixed there so easily, by hooking into Solid, in 4.3 the necessary information can be obtained.  I'm sending this to the list as there a few ions in playground, and at least one more of not in playground that I've heard is being developed.

The executive summary is that you need to add one slot to your ion, and emit a signal when it's done its job.  The slot is called reset() - as the name suggests, it resets the ion.  When it's done, emit resetCompleted(this,bool) where the bool is true if the reset was successful, or false otherwise.  In practice, the code for resetCompleted will need to do one of two things:

i) For ions which don't fetch a complete list of places, and only use the network to get a forecast or query with a suggested location string, clear all the existing data, and emit resetCompleted(this,true).

ii) For ions which fetch a list of place names off the 'net when the ion is first called (e.g. environment canada), clear all the existing data, grab the list of places again, then emit resetCompleted(this,true) if the download was successful; or resetCompleted(this,false) otherwise.

That's it.  The way it's written means the ions don't need to know /anything/ about whether the network is up.  The weather engine will hold onto requests until such a time as the network is available.  The bool of resetCompleted allows it to cope with the connection being dropped during list download - if this is false, it will still hold onto the request before passing it on.  Both forecast request and location checks are queued.  So, for instance, if it's asked whether there's any forecast data for London, it will hold off answering until it can find out - libplasmaweather will just sit there patiently.  Shawn tested it in ridiculous situations - three weather plasmoids going at once, kill the 'net, search, bring it back up, click okay, take it down, click okay, bring it back up....

Andrew