/*
 *
 *    Copyright (c) 2013-2017 Nest Labs, Inc.
 *    All rights reserved.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

/**
 *    @file
 *      This file declares a class that contains state related to an
 *      ongoing Weave Bulk Data Transfer. It is used by the
 *      BdxProtocol and BdxServer classes.
 *
 */

#ifndef _WEAVE_BDX_TRANSFER_STATE_H
#define _WEAVE_BDX_TRANSFER_STATE_H

#include <Weave/Profiles/bulk-data-transfer/Development/BDXManagedNamespace.hpp>
#include <Weave/Profiles/bulk-data-transfer/Development/BDXConstants.h>
#include <Weave/Profiles/bulk-data-transfer/Development/BDXMessages.h>

namespace nl {
namespace Weave {
namespace Profiles {
namespace WeaveMakeManagedNamespaceIdentifier(BDX, kWeaveManagedNamespaceDesignation_Development) {

// The default size we set a transfer's maxBlockSize to
#define DEFAULT_MAX_BLOCK_SIZE 256

struct BDXTransfer; // forward declaration for inclusion in callbacks

// typedefs for handler types needed below

/**
 * @brief
 *  Callback invoked when receiving a SendInit message.
 *
 * Its job is to determine if you want to accept the SendInit and, if so, set
 * aXfer->mIsAccepted=true so that the protocol will send an accept message to
 * the initiator. The BDXTransfer object is initiated to default settings.
 * This is a good place to attach any application-specific state (open file
 * handles, etc.) to aXfer->mAppState. You should also attach the necessary
 * handlers for e.g. block handling to the BDXTransfer object at this point.
 * If an error code other than WEAVE_NO_ERROR is returned, the transfer is
 * assumed to be rejected and the protocol will handle sending a reject message
 * with the code.
 *
 * @param[in]   aXfer           Pointer to the BDXTransfer associated with this transfer
 * @param[in]   aSendInitMsg    Pointer to the SendInit message that we are processing
 */
typedef uint16_t (*SendInitHandler)(BDXTransfer *aXfer, SendInit *aSendInitMsg);

/**
 * @brief
 *  Callback invoked when receiving a ReceiveInit message.
 *
 * Its job is to determine if you want to accept the Receive and, if so, set
 * aXfer->mIsAccepted=true so that the protocol will send an accept message
 * to the initiator. The BDXTransfer object is initiated to default settings.
 * This is a good place to attach any application-specific state (open file
 * handles, etc.) to aXfer->mAppState. You should also attach the necessary
 * handlers for e.g. block handling to the BDXTransfer object at this point.
 * If an error code other than kStatus_Success is returned, the transfer is
 * assumed to be rejected and the protocol will handle sending a reject message
 * with the code.
 *
 * @param[in]   aXfer               Pointer to the BDXTransfer associated with this transfer
 * @param[in]   aReceiveInitMsg     Pointer to the ReceiveInit message that we are processing
 */
typedef uint16_t (*ReceiveInitHandler)(BDXTransfer *aXfer, ReceiveInit *aReceiveInitMsg);

/**
 * @brief
 *  Callback invoked when a previously sent SendInit is accepted by the destination.
 *
 * You may wish to use this opportunity to open files or allocate resources for
 * the transfer if you did not do so when initiating it.
 *
 * @param[in]   aXfer               Pointer to the BDXTransfer associated with this transfer
 * @param[in]   aSendAcceptMsg      Pointer to the SendAccept message that we are processing
 */
typedef WEAVE_ERROR (*SendAcceptHandler)(BDXTransfer *aXfer, SendAccept *aSendAcceptMsg);

/**
 * @brief
 *  Callback invoked when a previously sent ReceiveInit is accepted by the destination.
 *
 * You may wish to use this opportunity to open files or allocate resources for
 * the transfer if you did not do so when initiating it.
 *
 * @param[in]   aXfer               Pointer to the BDXTransfer associated with this transfer
 * @param[in]   aReceiveAcceptMsg   Pointer to the ReceiveAccept message that we are processing
 */
typedef WEAVE_ERROR (*ReceiveAcceptHandler)(BDXTransfer *aXfer, ReceiveAccept *aReceiveAcceptMsg);

/**
 * @brief
 *  Invoked if one of the previous Init messages was rejected by the destination.
 *
 * @note
 *  Use this handler to provide feedback to your application about how to adjust
 *  a future request to make it successful. It should also close the BDXTransfer here.
 *
 * @param[in]   aXfer               Pointer to the BDXTransfer associated with this transfer
 * @param[in]   aReport             Pointer to the StatusReport message rejection that we are processing
 */
typedef void (*RejectHandler)(BDXTransfer *aXfer, StatusReport *aReport);

/**
 * @brief
 *     Get a block of data to be transmitted.
 *
 *  The caller provides the buffering space (buffer and length of the
 *  buffer, passed in by reference).  Callee (user application) SHOULD
 *  use the provided buffer, but for backward compatibility reasons,
 *  may return its own buffer.  Callee must not provide more than the
 *  `aLength` of bytes.  On return, `aLength` contains the actual
 *  number of bytes read into the buffer.
 *
 * @param[in] aXfer           The BDXTransfer associated with this ongoing
 *                            transfer
 * @param[inout] aLength      The length of data read and stored in this
 *                            block. On call to the function contains
 *                            the length of the of the buffer passed
 *                            in the `aDataBlock`.  On return, the
 *                            variable contains the length of data
 *                            actually read.
 * @param[inout] aDataBlock The pointer to the block of data. On
 *                            input, it contains the framework-
 *                            provided buffer; the callee may use that
 *                            space to fill the buffer, or provide its
 *                            own buffering space (for backward
 *                            compatibility applications). Applications
 *                            using provided buffer must not assume
 *                            any alignment.
 * @param[out] aLastBlock     True if the block should be sent as a
 *                            `BlockEOF` and the transfer completed,
 *                            false otherwise
 */
//TODO: define a contract for how to tell the caller not to send the block and/or
//that we encountered an error
typedef void (*GetBlockHandler)(BDXTransfer *aXfer,
                                uint64_t *aLength,
                                uint8_t **aDataBlock,
                                bool *aLastBlock);

/**
 * @brief
 *  Handle the block of data pointed to by aDataBlock of length aLength.
 *  Likely this will involve writing it to a file and closing said file if isLastBlock is true.
 *
 * @param[in]   aXfer       The BDXTransfer associated with this ongoing transfer
 * @param[in]   aLength     The length of data read and stored in the specified block
 * @param[in]   aDataBlock  The actual block of data
 * @param[in]   aLastBlock  True if the block was received as a BlockEOF and the
 *                          transfer completed, false otherwise. If true,
 *                          the programmer should probably finalize any file handles,
 *                          keeping in mind that the XferDoneHandler will be called
 *                          after this
 */
typedef void (*PutBlockHandler)(BDXTransfer *aXfer, uint64_t aLength,
                                uint8_t *aDataBlock, bool aLastBlock);

/**
 * @brief
 *  Handle TransferError messages received or sent by BDX.
 *
 * @note
 *  The BDX transfer is presumed to be potentially recoverable (possibly temporary e.g. out of
 *  PacketBuffers at the moment) and so the option of calling Shutdown() is left
 *  to the application programmer and the callbacks they define.
 *TODO: verify this and reconcile it with the language in the BDX document, which states:
 *  "[A TransferError] Can be sent at any time by either party to prematurely
 *  end the bulk data transfer."
 *
 * @note
 *   To determine if this TransferError was sent by this entity or its counterpart,
 *   inspect the aXfer->mAmInitiator member.
 *
 * @param[in]   aXfer           Pointer to the BDXTransfer associated with this transfer
 * @param[in]   aXferError      Pointer to the StatusReport message error that we are processing
 */
typedef void (*XferErrorHandler)(BDXTransfer *aXfer, StatusReport *aXferError);

/**
 * @brief
 *  Handle cases where the transfer is finished.
 *
 * @note
 *  To determine whether this transfer was aborted prematurely or completed
 *  successfully (that is, a BlockEOF or BlockEOFAck was received), inspect the
 *  aXfer->mIsCompletedSuccessfully member.
 *
 * @param[in]   aXfer           Pointer to the BDXTransfer associated with this transfer
 */
typedef void (*XferDoneHandler)(BDXTransfer *aXfer);

/**
 * @brief
 *  This handler is called any time a weave error is encountered that cannot
 *  directly be returned via error codes to user-application-defined control flow.
 *
 *  That is, if an error occurs within another handler whose signature has return
 *  type void (e.g. in response to an incoming Weave message or even dispatched
 *  by the protocol), this handler will be called so that the user can determine
 *  whether the transfer can be recovered and continue or if they should call
 *  Shutdown(). Note that it is possible for an error to occur before a BDXTransfer
 *  is initialized (e.g. already too many allocated transfer objects).  In such a case,
 *  said error will be logged by Weave and the protocol will handle cleaning up any
 *  necessary state that it allocated.
 *
 * @param[in]   aXfer           Pointer to the BDXTransfer associated with this transfer
 * @param[in]   anErrorCode     The error code that we need to process
 */

typedef void (*ErrorHandler)(BDXTransfer *aXfer, WEAVE_ERROR anErrorCode);

struct BDXHandlers
{
    SendAcceptHandler       mSendAcceptHandler;
    ReceiveAcceptHandler    mReceiveAcceptHandler;
    RejectHandler           mRejectHandler;
    GetBlockHandler         mGetBlockHandler;
    PutBlockHandler         mPutBlockHandler;
    XferErrorHandler        mXferErrorHandler;
    XferDoneHandler         mXferDoneHandler;
    ErrorHandler            mErrorHandler;
};

/** This structure contains data members representing an active BDX transfer.
 * These objects are used by the BdxProtocol to maintain protocol state.
 * They are managed by the BdxServer, which handles creating and initializing
 * new transfers, including managing Connections and ExchangeContexts.
 *
 * @note:
 * The handlers attached to this object are specified by the end application
 * so that multiple transfers may be open simultaneously that each support different
 * application logic.
 */
struct BDXTransfer
{
    ExchangeContext *   mExchangeContext;
    void *              mAppState;

    // data members related to the transfer handling
    uint8_t             mTransferMode;
    // Version being used for this transfer
    uint8_t             mVersion;
    // TODO: perhaps compact these more efficiently as flags to save memory?
    bool                mIsInitiated;
    bool                mIsAccepted;
    bool                mIsCompletedSuccessfully; // true iff a BlockEOF or BlockEOFAck was received
    bool                mAmInitiator;
    bool                mAmSender;
    bool                mIsWideRange; // true is widths and offsets are 64 bits
    bool                mFirstQuery; // true if we haven't received our first query
    //TODO: bool mAckRcvd;  // may want to keep track of ACKs to support
                            // retransmission of old blocks in the future
    //TODO: int mSendFlags; // may want to configure SendFlags to be used in calls to
                            // SendMessage, e.g. to support WRMP

    /** file/block related data members
     * TODO: remove this? or should we just establish a contract of what
     * this string might look like and how it will be used?
     * Specifically, is it backed by an PacketBuffer?  If so, it probably
     * shouldn't stick around for the whole xfer as that takes up a pbuf
     */
    ReferencedString    mFileDesignator;
    uint16_t            mMaxBlockSize; // Max block size to be used during this transfer
    uint64_t            mStartOffset; // Offset to start at for transfer, typically 0
    uint64_t            mLength; // Expected length of the transfer, 0 if unkown
    uint64_t            mBytesSent; // How many bytes have been sent so far in this transfer
    /** The next block number we expect to receive a BlockQuery or BlockACK for
     * when sending (once the transfer has officially started).
     * When receiving, it is the next BlockSend we expect to receive
     * or the latest BlockQuery we sent (after the transfer has officially started
     * and the first query sent that is).
     */
    uint32_t            mBlockCounter;

    // application-supplied handlers
    //TODO: make these private when BdxProtocol doesn't inspect them directly
    //before calling DispatchGetBlockHandler().  We'll have to remove that check
    //anyway if we move to a delegate model.
    BDXHandlers mHandlers;

    WEAVE_ERROR (*mNext)(BDXTransfer &); // Next action to take after the processing of the response

    void Shutdown(void);

    void Reset(void);

    bool IsAsync(void);

    bool IsDriver(void);

    void SetHandlers(BDXHandlers aHandlers);

    uint16_t GetDefaultFlags(bool aExpectResponse);

    /**
     * Dispatchers simply check whether a handler has been set and then call it if so.
     * Therefore, these should be used as the public interface for calling callbacks,
     * which should never be touched directly by outside applications.  It is
     * possible that a future revision of BDXTransfer will use a delegate object
     * rather than storing individual pointers to each of the callbacks.
     */

    WEAVE_ERROR DispatchReceiveAccept(ReceiveAccept *aReceiveAcceptMsg);
    WEAVE_ERROR DispatchSendAccept(SendAccept *aSendAcceptMsg);
    void DispatchRejectHandler(StatusReport *aReport);
    void DispatchPutBlockHandler(uint64_t aLength,
                                 uint8_t *aDataBlock,
                                 bool aLastBlock);
    void DispatchGetBlockHandler(uint64_t *aLength,
                                 uint8_t **aDataBlock,
                                 bool *aLastBlock);
    void DispatchErrorHandler(WEAVE_ERROR anErrorCode);
    void DispatchXferErrorHandler(StatusReport *aXferError);
    void DispatchXferDoneHandler(void);
};

/**
 * @brief
 *  GetBDXAckFlag returns the appropriate flag for the RequestAck field
 *  depending on the exchange context's connection (no request ack for TCP),
 *  and based on compile time support for WRMP.
 *
 * @param[in]   anEc           The exchange context we should get the flag based on
 *
 * @return 0 or kSendFlag_RequestAck
 */
inline uint16_t GetBDXAckFlag(ExchangeContext *anEc)
{
    uint16_t flags = 0;

#if WEAVE_CONFIG_BDX_WRMP_SUPPORT
    if (anEc->Con == NULL)
    {
        flags = ExchangeContext::kSendFlag_RequestAck;
    }
#endif

    return flags;
}

} // namespace BulkDataTransfer
} // namespace Profiles
} // namespace Weave
} // namespace nl

#endif // _WEAVE_BDX_TRANSFER_STATE_H