/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * 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 "nsIMsgSendReport.idl"
#include "nsISupports.idl"

interface nsIMsgCompFields;
interface nsIMsgIdentity;
interface nsIOutputStream;
interface nsIX509Cert;

/**
 * Callback type for use with asyncFindCertByEmailAddr.
 */
[scriptable, function, uuid(6149d7d3-14bf-4280-8451-60fb48263894)]
interface nsIDoneFindCertForEmailCallback : nsISupports {
  /**
   * Called after a searching for a certificate is done.
   *
   * @param emailAddress     - The email address that was used as the key
   *                           to find this certificate.
   * @param cert             - The valid certificate that was found,
   *                           or null, if no valid cert was found.
   */
  void findCertDone(in AUTF8String emailAddress,
                    in nsIX509Cert cert);
};

/**
 * An instance of this type is related to exactly one email message
 * while the user is composing it.
 * Besides remembering flags and providing helper code, it is used to
 * cache information about valid S/MIME encryption certificates that
 * were found and which may be used at send time.
 */
[scriptable, uuid(245f2adc-410e-4bdb-91e2-a7bb42d61787)]
interface nsIMsgComposeSecure : nsISupports
{
    /**
     * Set to true if the outgoing message shall be signed.
     */
    attribute boolean signMessage;

    /**
     * Set to true if the outgoing message shall be encrypted.
     */
    attribute boolean requireEncryptMessage;

    /***************************************************************************
     * The following functions are called during message creation by nsMsgSend,
     * after the message source is completely prepared.
     ***************************************************************************/

    /**
     * Determine if encryption and/or signing is required.
     *
     * @param aIdentity   - The sender's identity
     * @param compFields  - Attributes of the composed message
     *
     * @return - Returns true if the creation of the message requires us to go through
     *           some encryption work, and false otherwise.
    */
    boolean requiresCryptoEncapsulation(in nsIMsgIdentity aIdentity, in nsIMsgCompFields aCompFields);

    /**
     * Start encryption work. Called before the encrypted data is processed.
     *
     * @param aStream     - Output stream that takes the resulting data
     * @param aRecipients - RFC 2047-encoded list of all recipients (To:, Cc:, Bcc:, ... fields), separated by "," or ", "
     *                      Recipients contain name and email addresses, just like they will be put into the message headers
     * @param compFields  - Attributes of the composed message
     * @param aIdentity   - The sender's identity
     * @param sendReport  - Report feedback to the user
     * @param aIsDraft    - True if send operation saves draft/template/etc., false if message is really sent (or sent later)
     */
    void beginCryptoEncapsulation(in nsIOutputStream aStream, in string aRecipients, in nsIMsgCompFields aCompFields, in nsIMsgIdentity aIdentity, in nsIMsgSendReport sendReport, in boolean aIsDraft);

    /**
     * Process a part of the message data. Called multiple times, usually for every
     * line of the data to be encrypted
     *
     * @param aBuf  - Buffer holding the data to be processed
     * @param aLen  - Length of the buffer (number of characters)
     */
    void mimeCryptoWriteBlock(in string aBuf, in long aLen);

    /**
     * End encryption work. Called after the encrypted data is processed.
     *
     * @param aAbort      - True if the send operation was aborted
     * @param sendReport  - Report feedback to the user
     */
    void finishCryptoEncapsulation(in boolean aAbort, in nsIMsgSendReport sendReport);

    /**
     * Is information about a valid encryption certificate for the given
     * email address already available in the cache?
     *
     * @param emailAddress     - The email address to check.
     *
     * @return - True if a valid cert is known by the cache.
     */
    boolean haveValidCertForEmail(in AUTF8String emailAddress);

    /**
     * If a valid encryption certificate for the given email address
     * is already known by the cache, then return the NSS database
     * key of that certificate.
     *
     * @param emailAddress     - The email address to check.
     *
     * @return - NSS db key of the valid cert.
     */
    ACString getCertDBKeyForEmail(in AUTF8String emailAddress);

    /**
     * Remember the given certificate database key in our cache. The
     * given certDBey (as used with nsIX509CertDB) must reference a
     * valid encryption certificate for the given email address.
     *
     * @param emailAddress     - The email address that is related to
     *                           the given certDBKey.
     * @param certDBKey        - The certificate database key.
     */
    void cacheValidCertForEmail(in AUTF8String emailAddress,
                                in ACString certDBKey);

    /*
     * Asynchronously find an encryption certificate by email address. Calls
     * `findCertDone` function on the provided `nsIDoneFindCertForEmailCallback`
     * with the results of the operation.
     *
     *  @param emailAddress     - The email address to be used as the key
     *                            to find the certificate.
     *  @param callback         - A callback of type nsIDoneFindCertForEmailCallback,
     *                            function findCertDone will be called with
     *                            the result of the operation.
     */
    [must_use]
    void asyncFindCertByEmailAddr(in AUTF8String emailAddress,
                                  in nsIDoneFindCertForEmailCallback callback);
};