// p≡p Message API

// Copyleft (c) 2019, p≡p foundation
// this file is under GNU General Public License 3.0
// see LICENSE.txt

// written by Volker Birk


protocol session {
    method encrypt_message
        doc="encrypt message in memory"
    {
        // parms

        supply message src
        doc="""
            message to encrypt - usually in-only, but can be in-out for
            unencrypted messages; in that case, we may attach the key and
            decorate the message
            """;

        use hash_list extra doc="extra keys for encryption";

        create message dst
        doc="""
            pointer to new encrypted message or #NV if no encryption could
            take place
            """

        use encformat format doc="encrypted format";

        // flags

        flags {
            flag default 0x0;
            flag force_encryption 0x1;
        }

        // exceptions

        throws key_has_ambig_name
            doc="at least one of the receipient keys has an ambiguous name";

        throws unencrypted
        doc="""
            on demand or no recipients with usable key, is left unencrypted,
            and key is attached to it 
            """
    }
}