/**
 * @file     baseprotocol.h
 * @brief    base protocol (FIXME: derived from filename)
 * @license  GNU General Public License 3.0 - see LICENSE.txt
 */

#pragma once

#include "message.h"

#ifdef __cplusplus
extern "C" {
#endif


/**
 *  @enum	base_protocol_type
 *  
 *  @brief	TODO
 *  
 */
typedef enum _base_protocol_type {
    BASE_SIGN = 0,

    BASE_SYNC = 1,
    BASE_KEYRESET = 2
} base_protocol_type;


/**
 *  <!--       base_decorate_message()       -->
 *  
 *  @brief Decorate a message with payload
 *  
 *  @param[in]     session    session handle
 *  @param[in,out] msg        message to decorate (contains return result on success)
 *  @param[in]     type       base protocol type
 *  @param[in]     payload    payload to send
 *  @param[in]     size       size of payload
 *  @param[in]     fpr        optional key to sign or NULL
 *  
 *  @retval PEP_STATUS_OK     on success 
 *  @retval error_status      on failure
 *  
 *  @ownership 
 *  - On success (and only then), ownership of the payload is assigned to the msg structure
 *  - Ownership of the msg remains with the caller
 *  
 */

PEP_STATUS base_decorate_message(
        PEP_SESSION session,
        message *msg,
        base_protocol_type type,
        char *payload,
        size_t size,
        const char *fpr
    );


/**
 *  <!--       base_prepare_message()       -->
 *  
 *  @brief Prepare a sync message with payload
 *  
 *  @param[in]     session    session handle
 *  @param[in]     me         identity to use for the sender
 *  @param[in]     partner    identity to use for the receiver
 *  @param[in]     type       base protocol type
 *  @param[in]     payload    payload to send
 *  @param[in]     size       size of payload
 *  @param[in]     fpr        optional key to sign or NULL
 *  @param[out]    result     returned message with payload on success
 *  
 *  @retval PEP_STATUS_OK       on success
 *  @retval error_status        on failure
 *  
 *  @ownership 
 *  - On (and only on) success, ownership of payload is assigned to the result structure
 *  - Ownership of the result goes to the caller
 *  
 */

PEP_STATUS base_prepare_message(
        PEP_SESSION session,
        const pEp_identity *me,
        const pEp_identity *partner,
        base_protocol_type type,
        char *payload,
        size_t size,
        const char *fpr,
        message **result
    );


/**
 *  <!--       base_extract_message()       -->
 *  
 *  @brief Extract a sync message from a pEp message
 *  
 *  @param[in]     session    session handle
 *  @param[in]     msg        message to analyze
 *  @param[in]     type       base protocol type to extract
 *  @param[out]    size       size of extracted payload, or 0 if not found
 *  @param[out]    payload    extracted payload, if sync message is found. 
 *                            otherwise, NULL
 *  @param[out]    fpr        if message was correctly signed then fpr of signature's
 *                            key, otherwise NULL
 *  
 *  @retval PEP_STATUS_OK     if no error occurred, whether or not sync message was found
 *  @retval error_status      any other value on error
 *  
 *  @ownership
 *  - Payload may point to msg attachment, but the ownership does not change
 *  - If fpr != NULL the ownership goes to the caller
 * 
 *  @todo Volker, expand this definition from sync message. What do we call these? Administrative messages? - K
 *  
 */

PEP_STATUS base_extract_message(
        PEP_SESSION session,
        message *msg,
        base_protocol_type type,
        size_t *size,
        const char **payload,
        char **fpr
    );


/**
 *  <!--       try_base_prepare_message()       -->
 *  
 *  @brief Prepare a sync message with payload. This is the internal function to be used by 
 *         asynchronous network protocol implementations. This function differs from 
 *         base_prepare_message in that it calls messageToSend(NULL) in case there is a missing 
 *         or wrong passphrase, but more explanation is required here.
 *  
 *  @param[in]     session    session handle
 *  @param[in]     me         identity to use for the sender
 *  @param[in]     partner    identity to use for the receiver
 *  @param[in]     type       base protocol type
 *  @param[in]     payload    payload to send
 *  @param[in]     size       size of payload
 *  @param[in]     fpr        optional key to sign or NULL
 *  @param[out]    result     returned message with payload on success
 *  
 *  @ownership 
 *  - On (and only on) success, ownership of payload is assigned to the result structure
 *  - Ownership of the result goes to the caller
 * 
 *  @todo Volker, I need a better explanation of the use case here to document correctly - K
 * 
 *  @see base_prepare_message()
 */

PEP_STATUS try_base_prepare_message(
        PEP_SESSION session,
        const pEp_identity *me,
        const pEp_identity *partner,
        base_protocol_type type,
        char *payload,
        size_t size,
        const char *fpr,
        message **result
    );

#ifdef __cplusplus
}
#endif