/* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
interface nsIMailChannel;
interface nsIURI;

/**
 * nsISimpleMimeConverter provides an interface for rendering raw mime objects
 * as HTML. It's used to provide converters for mime types not handled
 * directly by the mime code.
 * "text/calendar" - see calendar/base/src/CalMimeConverter.sys.mjs
 * "text/vcard"    - see mailnews/addrbook/modules/VCardUtils.sys.mjs
 */
[scriptable, uuid(FC6E8234-BBF3-44A1-9802-5F023A929173)]
interface nsISimpleMimeConverter : nsISupports
{
    // uri of message getting displayed
    attribute nsIURI uri;

    // mailChannel of message getting displayed
    attribute nsIMailChannel mailChannel;

    /**
     * Render mime data into HTML.
     * NOTE: it is important that this function doesn't do anything which
     * would allows other events to processed on the thread (that means
     * calls to NS_ProcessNextEvent()). Using a synchronous XMLHttpRequest
     * is a prime example - it spins the thread queue, processing other
     * events while it waits.
     *
     * It's an issue because it's likely that convertToHTML() is being called
     * in response to data coming in from an async inputstream. Letting other
     * events be handled on the thread means that more data might come in
     * from the stream, recursively calling the nsIStreamListener
     * onDataAvailable() handler we're already inside! And it's tricky to
     * track down this kind of problem - it only occurs if the data is big
     * enough that it comes through in multiple chunks.
     * See bug 1679299.
     */
    AUTF8String convertToHTML(in ACString contentType,
                              in AUTF8String data);
};

%{C++

#define NS_SIMPLEMIMECONVERTERS_CATEGORY "simple-mime-converters"

%}