tny_header_get_uid

[Philip Van Hoof <spam pvanhoof be>]

I have implemented the tny_header_get_uid in a way that it wont return
NULL for the header instance of TnyMsg anymore.

This will make the header instances work with TnyFolder operations.

I still highly recommend against using them on TnyFolder operations and
I am therefore keeping the documentation about this in tact.

Once a message was received, it has nothing to do with the summary
anymore. Messages are what I call "offline entities", summary items are
what I can "online entities".

The summary when being online is always synchronised with what is really
online on the service. When being offline, it will be synchronised. For
example a feature like deleting a message when you are offline,
therefore, works with Tinymail. Although these features need a lot
testing (because I don't trust Evolution's support on this either, as
this is code that came with Evolution's Camel into Tinymail).

The uid of a TnyMsg instance (after getting the TnyHeader) can, if the
conditions are right, be different. Some examples:

A TnyMsg can have been moved to another TnyFolder, the UID of the TnyMsg
instance, that came from the summary of its original TnyFolder, will
point to a completely different UID on the new TnyFolder.

If the developer still uses that TnyMsg instance, or for example the
TnyHeader instance that he got with the TnyMsg instance, then he can
remove the wrong message from the wrong folder.

On API usage, everything would look fine: The developer will probably
thing: how can this be wrong? I just used the API AS IS.

Yet it would be wrong, logically.

This is why I am keeping the documentation as-is in place. You should
not use the TnyHeader instance that you get from a TnyMsg instance with
the operations on TnyFolder, because you can get it wrong easily.

I know people want to stand on their head and start acting crazy caused
by this. I really advise these people to think with a clear mind about
this and then reconsider the head-dancing.

I can give them a few A4 papers with reasons why it's a bad idea.

You either have a offline message, or a online summary item. Both the
message and the summary item can be used while the connectivity state is
either offline or online. 

I want Tinymail to support both connection states for the summary item
entity, and none for the message entity .. when dealing with TnyFolder
operations.

SO: don't use a TnyHeader that came from a TnyMsg with a TnyFolder.

I will most likely fix this API quirk in the next API release of
Tinymail. I have already agreed with a few people that the TnyHeader API
is not going to change for the API of the 1.0 release anymore.


And I am, totally, indeed, aware that this is an API quirk in Tinymail.



-- 
Philip Van Hoof, software developer
home: me at pvanhoof dot be 
gnome: pvanhoof at gnome dot org 
http://www.pvanhoof.be/blog