Subject: C-Client callback needs context support (IMAP & IMSP)

From: "Sohan C. Ramakrishna-Pillai" <[email-masked]>
Date: Wed, 16 Mar 1994 13:30:04 -0500 (EST)

Currently the mm_* routines are used to return various information bits
to the mail application. These routines, however, have been designed on
the assumption that all such callbacks will be handled by a single main
routine or thread or context, which is obviously insufficient for a
multi-context situation.
The simplest remedy would be to pass along an extra argument, a generic
void *context
or
void *callbackhandler
pointer along with all the mail_* routines to be passed on to the mm_*
callbacks appropriately.
One could also conceivably assume that a one-to-one mapping exists
between a context and a MAILSTREAM (or SUPPORTSTREAM) and pass along a
pointer to the MAILSTREAM (or SUPPORTSTREAM) to the callbacks, but it
may be more general to pass along a separate context in case future
extensions/changes make it necessary to invalidate such an assumption.
___
Sohan C. Ramakrishna-Pillai
Office: UCC 181	Phone: x6406 [(412)268-6406]

Don't get suckered in by the comments -- they can be terribly
misleading.  Debug only code.
                -- Dave Storer

---

From: Chris Newman <[email-masked]>
Date: Wed, 16 Mar 1994 14:53:50 -0500 (EST)

All the mm_* callbacks I added with the IMSP c-client API pass back
either an address book structure or a SUPPORTSTREAM.

By request of Adam Treister, the abook_open routine takes a third argument
which is a generic pointer that can be extracted from the address book
structure in future calls with the "abook_generic()" call.

I propose the following changes:

1) I add a way to store and retrieve a generic pointer in a SUPPORTSTREAM
   structure.  This allows context without changing any of the calls.

2) The IMSP API shares the mm_log() callback that IMAP uses.  I propose that
   an optional third argument be added to mm_log().  This third argument
   would be the generic pointer from the SUPPORTSTREAM/MAILSTREAM that
   generated the error (or NULL if there is no context to the error).

Although the IMSP API also shares the mm_login() callback that IMAP
uses, I don't believe any change would be needed to support callbacks
on that.

The other mm_* calls that c-client makes are entirely in Mark's court.

		- Chris

---

From: "Sohan C. Ramakrishna-Pillai" <[email-masked]>
Date: Thu, 17 Mar 1994 12:04:49 -0500 (EST)

Excerpts from mail: 16-Mar-94 Re: C-Client callback needs.. Chris Newman
(1029*)
> The other mm_* calls that c-client makes are entirely in Mark's court.

Given that essentially all mm_* callbacks will need a context pointer
and some of the IMAP c-client's mm_* routines are being reused by IMSP,
IMHO, it would be best if the IMSP API tacks on the context pointer as
well. Since both SUPPORTSTREAMs and MAILSTREAMs and potentially other
objects are to be used in the callbacks, binding the context to any of
these objects is not a good idea - still potentially extensible in a
limited sense (see below), but in an inelegant fashion e.g. in mm_log.
Making IMSP maintain a separate set of callback functions is a
possibility, but is inefficient w.r.t. reuse of the generic callbacks
like mm_log. The best way seems to be to include a context pointer with
each of the c-client calls to be passed on to the callback functions.
Storing the generic pointer in the address book and SUPPORTSTREAMs is
also technically feasible, but then we would need to document a uniform
convention whereby all objects, including MAILSTREAMS, will provide
access to the context. Can be done easily in a C++ environment, less
easily with C. Also, while this is sufficient for our purposes, this has
the drawback of binding a context to a stream(-like) object, and maybe I
am being paranoid, but I am not sure that future extensions or
applications may find this constraining - e.g. a future multithreaded
multiplexed access to some stream(-like) object, maybe. Tacking on the
context to the APIs avoids this drawback and is therefore more flexible
and, IMHO, superior.
So, to summarize:
The feasible solutions seem to be
1. pass context to c-client calls thru to callbacks.
2. uniform documented convention to associate context with stream(-like)
objects and access them and pass stream(-like) objects to callbacks as
well.
We can live with 2. for now, but 1. would be simpler and technically
preferable.
___
Sohan C. Ramakrishna-Pillai
Office: UCC 181 Phone: x6406 [(412)268-6406]

Try to get all of your posthumous medals in advance.