import/export interface for Bonobo

[Dan Winship <danw helixcode com>]

Right now in Evolution, the mail component and the html editor
component speak to each other via PersistStream. However, this is
inadequate, because sometimes the mail component wants to get
text/html out of the editor, and sometimes it wants text/plain (and
sometimes it wants both).

So here is a proposal for a new interface, Bonobo::Porter, for objects
which can potentially import and export multiple kinds of data
(including compound documents).

    /* Bonobo::Porter - an object that can import and export data */
    
    module Bonobo {
    
    interface Porter : Bonobo::Unknown {
    
            exception BadType {};
    
            exception BadName {};
    
            /**
             * import:
             * @name: a URI associated with the data to import.
             * @available_types: the MIME types the data is available in
             * @stream: a Bonobo::Stream that the data will be written to
             *
             * Used to request that the Porter import data of a given
             * type. The Porter will raise BadType if it can't import any
             * of the available types, or BadName if it does not like
             * @name for whatever reason.
             *
             * The effect of calling this twice with different @names is
             * not entirely specified: it may cause the Porter to open a
             * second window, it may fill in data for a "subdocument" of
             * the main document (as in the case of an HTML image), or it
             * may discard the earlier data.
             *
             * Returns: the MIME type to send the data in.
             */
            string import (in string name,
                           in sequence<string> available_types,
                           in Bonobo::Stream stream)
                    raises (BadType, BadName);
    
            /**
             * export:
             * @name: a URI associated with the data to export.
             * @desired_types: the MIME types the caller will accept
             * @stream: a Bonobo::Stream that the data will be written to
             * @subdocs: on return, a list of subdocuments contained in
             * the exported document.
             *
             * Used to request that the Porter export the data associated
             * with @name, in one of the given types. A type can have "*"
             * for subtype if the caller will accept any subtype of the
             * type, or "*" for the whole type if it will accept any type
             * of data at all. If the Porter can not or will not export
             * the named data, it can raise BadName.
             *
             * Returns: the MIME type the data was sent in.
             */
            struct item {
                    string name;
                    string type;
            };
            string export (in string name,
                           in sequence<string> desired_types,
                           in Bonobo::Stream stream,
                           out sequence<item> subdocs)
                    raises (BadType, BadName);
    };


The idea is that the user clicks send/reply/forward, the mail
component generates a plain text or HTML draft, according to
circumstances and user preferences, and it asks the editor to import
it. The user edits it, possibly includes some images, and then clicks
"send", which tells the editor to signal the mail component that it's
done. Then the mail component calls "export" on the editor to get the
original document, and if it tells it about subdocuments, it fetches
those as well.

If the mail component is sending multipart/alternative, it will call
export twice, the first time asking for <"text/html", "text/plain">,
and the second time with <"text/plain"> (assuming the first time
succeeded and returned "text/html"--if it was talking to some editor
that didn't speak text/html, such as Gnomacs maybe, then it would get
back "text/plain" the first time and not call a second time and send
plain text.)

Is this a good interface?

-- Dan