Re: tny_header_get_uid

[Philip Van Hoof <spam pvanhoof be>]

Note that my current idea is to split TnyHeader up into two interfaces
(these are Tinymail 2.0 API ideas, that are not going to be in the final
Tinymail 1.0 API, as agreed with a few people and projects being done on
top of Tinymail):

TnySummaryItem and TnyHeader 

TnyMsgHeader will implement TnyHeader
TnyFolderSummaryItem will implement TnySummaryItem and TnyHeader

TnyHeader will not have the get_uid property
TnySummaryItem will have the get_uid property and will extend the
TnyHeader interace (each TnySummaryItem will also be a TnyHeader)

TnyFolder will only work with TnySummaryItem instances, it wont work
with just TnyHeader instances.

TnyMsg will return a TnyHeader as its get_header property.

tny_folder_get_headers will be renamed to tny_folder_get_summary_items
and will most likely get a 'query' parameter.

I will listen to people on this subject, although I "will" also fix this
API quirk (so Tinymail's 2.0 API "wont" be compatible with the 1.0's
API, although I will "try" to keep it ABI compatible I "wont" make this
a promise right now)

Note that I "am" being very clear and that this "is" on purpose indeed.


On Sun, 2007-06-03 at 14:18 +0200, Philip Van Hoof wrote:
> 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