Subject: Re:Proposal for c-client API for IMSP

From: Adam Treister <[email-masked]>
Date: Fri, 17 Dec 93 11:01:53 -0800

Chris,

I read over your proposal last night, and am in general agreement all the way
down the line.  A few requests tho'

1) I'll probably write object wrappers around the address book and options
calls.  So my mm_address callback will look something like this:

void mm_address(abook ab, char *name, fielddata *fdata, int count)
{
    AddressBookObject* obj = EXTRACT_PARENT(ab);
    obj->ProcessCallback(name, fdata, count);
}

To do this, I need to bury my object pointer in your structures.  So I'd like to
see the open calls support a "parent" pointer.

abook *abook_open(SUPPORTSTREAM *s, char *abook_name, void* parent);

MAILSTREAM *mailbox_open(SUPPORTSTREAM *s, char *name, char *options, void*
parent);

2) keyvalue

>      typedef struct keyvalue {
>          char *key, *value;
>      } keyvalue;

The keyvalue pairs are general enough to do anything we want, but there are a
few extra conventions that would make things easier on the client.

a) a "list" keyvalue to enable atomic processing of multiple elements
b) a "tagged" keyvalue to allow order-independent grammars to be defined.

Both of these are in Apple's Object Model, which is architecturally very
similar.  I could build anything out of your keyvalue, but it makes things a lot
easier to add a few more low level tools to the box.  I think this necessitates
reserving a few keys so the toolbox can recognize them and process accordingly.
In addition to LIST and TAG, I can see gains to reserving ADDRESS and
ADDRESSBOOK as keys to facillitate representation of distribution lists, and
hierarchical address books.

3)  My final comment is that this model fits my needs for most any application
that wants location-independence!  Do you know of any reason why an application
that is not using IMAP could not use IMSP and this API to provide the address
book and options functionality?

Adam

---

From: Chris Newman <[email-masked]>
Date: Wed, 19 Jan 1994 12:43:23 -0500 (EST)

I forgot to get to this message over the holidays...

In message <[email-masked]>, 
 Adam Treister <[email-masked]> writes:
> To do this, I need to bury my object pointer in your structures.  So I'd
> like to see the open calls support a "parent" pointer.
>

A good idea, although I'm not sure referring to it as "parent" is the
right thing to do.  For flexability, why don't I just make it a
generic data void pointer (e.g. void *data).

> similar.  I could build anything out of your keyvalue, but it makes things a
> lot easier to add a few more low level tools to the box.  I think this
> necessitates reserving a few keys so the toolbox can recognize them
> and process accordingly.

I don't really understand what you're asking for here.  The IMSP model
for an address book is that each address book entry is a set of
keyvalue pairs (in an arbitrary order).  What would the values of a
"list" or "tagged" keyvalue be?  Could you give me an example of their use?
Does this merit IMSP spec or API level support, or would it work as a
client convention?

> hierarchical address books.

The IMSP spec reserves "email" for a CRLF separated list of email
addresses, and "members" for a CRLF separated list of names of other
address book entries.  The purpose of the abook_expand() API call is
to ensure that all clients resolve both the "email" and "members"
fields correctly.

At present, I think burying address books in address book entries is
getting a bit too complex.  Since address book entry keys are
arbitrary, this can always be added as a convention or later feature
if there is demand.

> 3) My final comment is that this model fits my needs for most any
> application that wants location-independence!  Do you know of any
> reason why an application that is not using IMAP could not use IMSP
> and this API to provide the address book and options functionality?

The only tricky part is to keep the options namespace from getting
confused.  Otherwise, I'd say yes.  In fact, one of the reasons for
separating the IMSP functionality from IMAP is that it provides
services that are potentially useful to non-IMAP protocols (POP2,
POP3, NNTP, etc).

		- Chris

---

From: Adam Treister <[email-masked]>
Date: Wed, 19 Jan 94 10:55:51 -0800

#1
Chris:
>   A good idea, although I'm not sure referring to it as
>   "parent" is the right thing to do.  For flexability, why
>   don't I just make it a generic data void pointer (e.g.
>   void *data).

No argument...Would a pointer by any other name, not dereference so sweet?

#2

Chris:
  
>   I don't really understand what you're asking for here.
>   The IMSP model for an address book is that each address
>   book entry is a set of keyvalue pairs (in an arbitrary
>   order).  What would the values of a
>   "list" or "tagged" keyvalue be?  Could you give me an
>   example of their use? Does this merit IMSP spec or API
>   level support, or would it work as a client convention?

I don't know if I can do this one justice, in the limited time I have but its a
case where the anticipated modes of usage may justify another layer of
complexity in the structures.  I've included some typedefs from Apples
AppleEvent structures in the hope that it'll give an example.  (Read new Inside
Mac volume on InterApplication Communication, for more explanation on their
usage)

I guess this is a convention since the client would be requesting a double, but
the second element would be a list.  But by having conventions in place, we can
offer cross client functionality like Get_Fax_Number(treister) or
How_Many_Names_In_List(c-client), that without some sort of standard, each
client would only be able to provide for records it created.

------------------ Taken from AppleEvent.h -------------

(these are all 4 byte codes defined by apple,  eg 'TEXT', 'aevt', 'quit'
--Adam)

typedef unsigned long AEEventClass;
typedef unsigned long AEEventID;
typedef unsigned long AEKeyword;
typedef ResType DescType;

struct AEDesc {
 	DescType descriptorType;
 	Handle dataHandle;
};
typedef struct AEDesc AEDesc;

struct AEKeyDesc {
	AEKeyword descKey;
	AEDesc descContent;
};
typedef struct AEKeyDesc AEKeyDesc;

typedef AEDesc AEAddressDesc;								/* an AEDesc which contains address data
*/
typedef AEDesc AEDescList;									/* a list of AEDesc's is a special kind of
AEDesc */
typedef AEDescList AERecord;								/* AERecord is a list of keyworded AEDesc's
*/
typedef AERecord AppleEvent;								/* an AERecord that contains an AppleEvent
*/

>   
>   The IMSP spec reserves "email" for a CRLF separated list
>   of email addresses, and "members" for a CRLF separated
>   list of names of other address book entries.  The
>   purpose of the abook_expand() API call is to ensure that
>   all clients resolve both the "email" and "members"
>   fields correctly.

No argument these are the most important cases, but there are other lists that
mailstrom uses, that in theory should be shared across clients.  eg:
(Preferred-Fonts (Browser (Geneva 10 Bold)) (ReadWindow (Courier 12 Plain))
(Telemetry (Monaco 9 plain))).  Yes, I can parse these lists myself, but the
most effective way to get these things to be cross client is to build it into
c-client.

Let me close out this subject by recommending that we NOT try to incorporate it
into any current versions, but table it for future enhancements.  I'm not sure
what percentage of users actively use more than one client regularly, AND care
that the look and feel is consistant.  Chances are its easier to write some
utility that translates one clients preference set to another, than it is to
agree on universal conventions at this early stage.

Adam

---

From: Chris Newman <[email-masked]>
Date: Fri, 21 Jan 1994 10:13:33 -0500 (EST)

Adam Treister <[email-masked]> writes:
> I don't know if I can do this one justice, in the limited time I
> have but its a case where the anticipated modes of usage may justify
> another layer of complexity in the structures.  I've included some
> typedefs from Apples AppleEvent structures in the hope that it'll
> give an example.  (Read new Inside Mac volume on InterApplication
> Communication, for more explanation on their usage)

I'm afraid pointing to apple events as an example isn't going to
convince me.  When I added them to my basic application skeleton, I
found them so complex that I almost decided not to bother supporting
them...  I wouldn't want that to happen with IMSP.

> I guess this is a convention since the client would be requesting a
> double, but the second element would be a list.  But by having
> conventions in place, we can offer cross client functionality like
> Get_Fax_Number(treister) or How_Many_Names_In_List(c-client), that
> without some sort of standard, each client would only be able to
> provide for records it created.

I think parsing of user-visible fields beyond "email" and "members"
will be a dangerous thing for a client to do.  There are all sorts of
character set and internationalization issues to worry about (e.g. I
believe some countries list their phone numbers in reverse order from
what the US does)...

> No argument these are the most important cases, but there are other
> lists that mailstrom uses, that in theory should be shared across
> clients.  eg: (Preferred-Fonts (Browser (Geneva 10 Bold))
> (ReadWindow (Courier 12 Plain)) (Telemetry (Monaco 9 plain))).  Yes,
> I can parse these lists myself, but the most effective way to get
> these things to be cross client is to build it into c-client.

We definitely need to work out some system for registry of generic
options and the prefixes used for client-specific options.

		- Chris