[Mono-list] CS-Mail-API

[Jeffrey Stedfast]

Hey,

Sorry I didn't respond sooner.

First, is there a tool or something I can use to "display" this other
than a text editor? I'm just not used to reading APIs in XML format...
:-)

Okay, now for some comments...

	<enum name="AddressType">
		<member name="EmailAddress"/>
		<member name="InternetAddress"/>
		<member name="NewsAddress"/>
	</enum>

What's an InternetAddress? Anyways, that's not my biggest concern -
which is that the classes don't seem to address addresses like:

MONO: miguel@ximian.com, mono-list@ximian.com;

These days you rarely ever see this, but at my last job I came accross
this quite a lot.

	<enum name="MessageFlags">
		<member name="None"/>
		<member name="Seen"/>
		<member name="Answered"/>
		<member name="Flagged"/>
		<member name="Deleted"/>
		<member name="Draft"/>
		<member name="Recent"/>
		<member name="UserDefined"/>
	</enum>

This shouldn't be an enum since you can theoretically have more than a
single flag marked. For example, a message could be Seen and Answered.
We use a bit field in Camel to handle this.

	<enum name="FolderType">
		<member name="Folders"/>
		<member name="Message"/>
		<member name="Both"/>
	</enum>

This might be better as a bitfield too? It might be nicer if the names
were something more like CAN_HOLD_FOLDERS and CAN_HOLD_MESSAGES (I'm
partial to caps for enums but my point here is actually the clarity of
what the value means - myFolder.type == Folders just doesn't convey the
meaning the same way myFolder.type == CanHoldFolders).

The reason I suggest a bitfield for this is that it makes it easier to
do something like:

if (myFolder.type & CAN_HOLD_FOLDERS) {
   scan_for_subfolders ();
}

sure, you can do it by doing:

if (myFolder.type == CAN_HOLD_FOLDERS || myFolder.type == CAN_HOLD_BOTH)
but it's more typing.

	<enum name="MessageSortStyle">
		<member name="Default"/>
		<member name="From"/>
		<member name="Size"/>
		<member name="Date"/>
		<member name="Subject"/>
	</enum>

there should probably be a way of extending this? In Evolution, we have
a lot more ways of sorting than just these (as do many mail clients).
Actually I'm not convinced that csMail should even worry about sorting.
This can be done at a higher level.

Same for FolderSortStyle.

	<enum name="ProviderType">
		<member name="Store"/>
		<member name="Transport"/>
	</enum>

yet another bitfield probably? Example: NNTP is both a provider and a transport.

	<enum name="ReciepientType">

type-o :-)

In class ContentType what is ctor? Oh, constructor?
Just smack me :-)

Is ContentType::Equals() for matching exactly? In Evolution, we do:

header_content_type_is (content_type, "text", "*")

It doesn't use regex or anything complex like that, the rule is that if
the string is "*" then it's a wildcard else it's not. This is very
useful when traversing MIME parts looking for a text part for example
:-)

In class EMailAddress, why do we care about 'host'? I can't think of a
reason why you wouldn't want to just refer to the entire addr-spec. I
guess it's no big deal though.

class EMailAddressList:

A good convenience function to have here would be to have a ToString
method that gave you the encoded address and one that gave you the
non-encoded (display version?) address.

Also, it seems that there is no way to get the entire EMailAddressList
as a single string? This would also be useful.

class Folder:

<property name="Messages" type="Message[]" allow="get;"/>

this is gonna require a ton of memory for a folder of any considerable
size. I suggest having a method to instead just get a summary of
messages. Imagine:

class MessageInfo {
   string from;
   string to;
   string cc;
   string bcc;  /* is this even really needed?? */
   string subject;
   string message_id;
   string references;  /* needed for proper threading */
   DateType sent_date; /* date in Date: header */
   DateType rcvd_date; /* date received, if different from sent_date */
   Uint32 flags;       /* bitfield of Seen/Deleted/etc */

   ...
};

This will require much much less memory and would also be considerably
faster to "load" (especially in the IMAP case) since it will require so
much less I/O.

Oh, my bad... farther down you have a GetMessages() method that only
gets specific messages that you request. However, you still have no way
to get a summary like I suggested above for constructing a message-list
in a client application so I guess what I said above still applies.

	<class name="FolderAddress">

This class looks exactly the same as URLName, so this should probably be
scrapped.

<class name="Message">

Okay... most of my comments for this class are uncertain... the ideas
are just the way I'm used to doing things and not necessarily "wrong".

For example, I don't think we really need Message::Flags (which also
means we won't need Message::IsSet()). But to get rid of the IsSet()
method, we'd need a method on the folder to get this info. You should
probably have a method for getting the MessageInfo based on a message or
a UID or an index.

A message's flags are really just metadata and not really part of the
message at all. Or at least that's my paradign.

Message::IsExpunged() sorta follows the same idea...why do we need this?
If we have an instance of the message, do we really care? I dunno,
perhaps it could be useful.

<method name="SaveChanges" type="abstract"/>

This method doesn't really make sense for spools, of course SaveChanges
could be implemented to delete the original message and append the new
form of the message to the end of the spool?

I don't think the message needs to reference the folder either, however
doing so could simplify things.

Anyways, that's all I can think of at the moment.

Jeff

On Thu, 2002-06-27 at 08:55, Gaurav Vaish wrote:
> Hello everybody,
>  I have now released the first version (not draft) of the API.
> 
>  I would like some comments on it, especially from geeks of evolution/camel (if here) and ppl like AjayD.
>  ;-)
> 
>  I am also attaching a copy of the same here.
> 
> 
> Cheers,
> Gaurav Vaish
> 
> 
> ____________________________________________________________
> Win a first-class trip to New Orleans and vacation Elvis Style!.
> Enter NOW!
> http://r.lycos.com/r/sagel_mail/http://www.elvis.lycos.com/sweepstakes/
-- 
Jeffrey Stedfast
Evolution Hacker - Ximian, Inc.
fejj@ximian.com  - www.ximian.com