[Evolution-hackers] CamelFolder updates

[Dan Winship <danw helixcode com>]

I'd like to fix up camel-folder. Specifically:

1) Fix the glib precondition stuff, fix the gtk-doc comments, etc.

2) Remove deprecated methods:

   - async open/close mehthods

   - list_subfolders and get_uid_list because they explode on Very
     Large folders, whereas get_subfolder_info / get_message_info
     don't.

   - copy_message_to because it's a useless optimization

3) Make all of the capability checks use the same interface
   (overridable method whose default implementation checks a
   gboolean CamelFolder member)

4) Message numbers

   Message numbers are not thread safe (or, in the case of IMAP, safe
   against multiple concurrent accessors to the same folder).

   We've talked about removing the by_number interfaces, but some
   stores have no concept of UID, so if they're forced to implement
   "pretend" UIDs, they'll have nothing but message numbers to work
   with.

   Also, message numbers are used by camel_folder_get_message_info,
   which is used to get summary information which is needed to use the
   uid routines. The old solution of having the routine return summary
   info for the entire folder is potentially bad, because folders
   could be very very very very large.

   One possibility is to require that the message numbers in a
   CamelFolder can never change while the folder is open. This would
   mean that some Folders would need to keep a real to virtual message
   number map. Probably get_message_info would just ignore the holes
   in the numbering, such that asking for summary info for 1-5 when 3
   had been deleted would return 4 summary entries.

   That seems like it could be messy. Anyway, we need to do something
   here.

5) Get rid of the concept of non-existent folders. Move the folder
   creation code into CamelStore, and have camel_store_get_folder
   return an exception if you ask for a folder that doesn't exist.
   This gets rid of a lot of code that we're not taking any advantage
   of.

   Also move delete_folder into CamelStore.

6) Consider getting rid of the concept of closed folders. Currently
   "open", "create", "delete", and "delete_messages" are the only
   methods that require closed folders, but there's lots of checking
   of folder state that goes on that could be gotten rid of if we made
   it so camel_store_get_folder returns the folder in an "open" state,
   and had "close" happen automatically when all references to the
   folder went away.

-- Dan