/* -*- Mode: IDL; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
/*
 * Evolution-Composer.idl: Mail composer interfaces for Evolution
 *
 * Author:
 *   Dan Winship <danw@ximian.com>
 * 
 * (C) 2000 Ximian, Inc.
 */

#include <Bonobo.idl>

module GNOME {
module Evolution {
	
	interface Composer : Bonobo::Unknown {
		struct Recipient {
			string name;	/* UTF-8 */
			string address;
		};
		typedef sequence<Recipient> RecipientList;

		typedef sequence<char> AttachmentData;

		enum MultipartType {
			MIXED,
			ALTERNATIVE
		};

		/**
		 * setHeaders:
		 * @from: the "From" account or address
		 * @to: the "To" recipients
		 * @cc: the "CC" recipients
		 * @bcc: the "Bcc" recipients
		 * @subject: the subject of the message
		 *
		 * Sets the composer headers. Any of @to, @cc, and
		 * @bcc may be an empty list, and @subject may be an
		 * empty string. If @from is empty or invalid, the
		 * default account will be used. Otherwise is
		 * specifies an account name or email address to send
		 * from.
		 **/
		void setHeaders (in string from, in RecipientList to,
				 in RecipientList cc, in RecipientList bcc,
				 in string subject);

		/**
		 * setMultipartType:
		 * @type: a multipart subtype
		 *
		 * Sets the kind of multipart message that is being
		 * created.
		 *
		 * If @type is MIXED (the default), setBody()
		 * will create the body, and attachMIME() and
		 * attachData() will create attachments.
		 *
		 * If @type is ALTERNATIVE, setBody() will create
		 * text/plain alternative, and each following
		 * attachMIME() or attachData() call will create
		 * another alternative.
		 *
		 * Other values of @type are not currently supported,
		 * although "related" probably should be.
		 **/
		void setMultipartType (in MultipartType type);

		/**
		 * setBody:
		 * @body: the body
		 * @mime_type: the MIME type of @body
		 *
		 * Sets the body of the composer to @body. If
		 * @mime_type is something other than "text/plain" or
		 * "text/html", the composer will not be editable
		 * and it will not attempt to assign a non-UTF8
		 * character set to the data. However, @mime_type may
		 * include parameters in that case.
		 **/
		void setBody (in string body, in string mime_type);

		/**
		 * attachMIME:
		 * @data: the attachment data
		 *
		 * This adds an attachment to the composer. @data
		 * should be a fully-formed MIME body part.
		 **/
		exception CouldNotParse {};
		void attachMIME (in string data)
			raises (CouldNotParse);

		/**
		 * attachData:
		 * @content_type: the Content-Type header
		 * @filename: the suggested filename, or ""
		 * @description: a description of the data, or ""
		 * @show_inline: whether the attachment should be
		 * displayed inline or not.
		 * @data: the raw attachment data
		 *
		 * This adds @data as an attachment, using the provided
		 * information to generate MIME headers. @content_type
		 * may contain just a MIME content type, or it may
		 * contain a complete Content-Type header. @filename
		 * is a filename for the Content-Disposition header
		 * @description (if not "") provides the
		 * Content-Description, and @show_inline determines if the
		 * Content-Disposition is "inline" or "attachment".
		 *
		 * If you need to specify headers or values other than
		 * what this function can do, you will need to generate
		 * all of the MIME headers yourself and use
		 * add_attachment ().
		 **/
		void attachData (in string content_type,
				 in string filename,
				 in string description,
				 in boolean show_inline,
				 in AttachmentData data);

		/**
		 * show:
		 *
		 * Shows the composer and lets the user edit things
		 * and send the message.
		 **/
		void show ();


		/**
		 * send:
		 *
		 * Send the message without showing the user the composer
		 **/
		void send ();
	};
};
};
