coap.hpp

Go to the documentation of this file.

/*
 *  Copyright (c) 2016, The OpenThread Authors.
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *  1. Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *  2. Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *  3. Neither the name of the copyright holder nor the
 *     names of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef COAP_HPP_
#define COAP_HPP_

#include "openthread-core-config.h"

#include <openthread/coap.h>

#include "coap/coap_header.hpp"
#include "common/debug.hpp"
#include "common/locator.hpp"
#include "common/message.hpp"
#include "common/timer.hpp"
#include "net/ip6.hpp"
#include "net/netif.hpp"
#include "net/udp6.hpp"

namespace ot {

class ThreadNetif;

namespace Coap {

enum
{
    kAckTimeout                 = OPENTHREAD_CONFIG_COAP_ACK_TIMEOUT,
    kAckRandomFactorNumerator   = OPENTHREAD_CONFIG_COAP_ACK_RANDOM_FACTOR_NUMERATOR,
    kAckRandomFactorDenominator = OPENTHREAD_CONFIG_COAP_ACK_RANDOM_FACTOR_DENOMINATOR,
    kMaxRetransmit              = OPENTHREAD_CONFIG_COAP_MAX_RETRANSMIT,
    kNStart                     = 1,
    kDefaultLeisure             = 5,
    kProbingRate                = 1,

    // Note that 2 << (kMaxRetransmit - 1) is equal to kMaxRetransmit power of 2
    kMaxTransmitSpan            = kAckTimeout * ((2 << (kMaxRetransmit - 1)) - 1) *
                                  kAckRandomFactorNumerator / kAckRandomFactorDenominator,
    kMaxTransmitWait            = kAckTimeout * ((2 << kMaxRetransmit) - 1) *
                                  kAckRandomFactorNumerator / kAckRandomFactorDenominator,
    kMaxLatency                 = 100,
    kProcessingDelay            = kAckTimeout,
    kMaxRtt                     = 2 * kMaxLatency + kProcessingDelay,
    kExchangeLifetime           = kMaxTransmitSpan + 2 * (kMaxLatency) + kProcessingDelay,
    kNonLifetime                = kMaxTransmitSpan + kMaxLatency
};

OT_TOOL_PACKED_BEGIN
class CoapMetadata
{
    friend class CoapBase;

public:

    CoapMetadata(void):
        mDestinationPort(0),
        mResponseHandler(NULL),
        mResponseContext(NULL),
        mNextTimerShot(0),
        mRetransmissionTimeout(0),
        mRetransmissionCount(0),
        mAcknowledged(false),
        mConfirmable(false) {};

    CoapMetadata(bool aConfirmable, const Ip6::MessageInfo &aMessageInfo,
                 otCoapResponseHandler aHandler, void *aContext);

    otError AppendTo(Message &aMessage) const {
        return aMessage.Append(this, sizeof(*this));
    };

    uint16_t ReadFrom(const Message &aMessage) {
        return aMessage.Read(aMessage.GetLength() - sizeof(*this), sizeof(*this), this);
    };

    int UpdateIn(Message &aMessage) const {
        return aMessage.Write(aMessage.GetLength() - sizeof(*this), sizeof(*this), this);
    }

    bool IsEarlier(uint32_t aTime) const { return (static_cast<int32_t>(aTime - mNextTimerShot) > 0); };

    bool IsLater(uint32_t aTime) const { return (static_cast<int32_t>(aTime - mNextTimerShot) < 0); };

private:
    Ip6::Address          mSourceAddress;         
    Ip6::Address          mDestinationAddress;    
    uint16_t              mDestinationPort;       
    otCoapResponseHandler mResponseHandler;       
    void                  *mResponseContext;      
    uint32_t              mNextTimerShot;         
    uint32_t              mRetransmissionTimeout; 
    uint8_t               mRetransmissionCount;   
    bool                  mAcknowledged: 1;       
    bool                  mConfirmable: 1;        
} OT_TOOL_PACKED_END;

class Resource : public otCoapResource
{
    friend class CoapBase;

public:
    enum
    {
        kMaxReceivedUriPath = 32,   
    };

    Resource(const char *aUriPath, otCoapRequestHandler aHandler, void *aContext) {
        mUriPath = aUriPath;
        mHandler = aHandler;
        mContext = aContext;
        mNext = NULL;
    }

    Resource *GetNext(void) const { return static_cast<Resource *>(mNext); };

private:
    void HandleRequest(Header &aHeader, Message &aMessage, const Ip6::MessageInfo &aMessageInfo) const {
        mHandler(mContext, &aHeader, &aMessage, &aMessageInfo);
    }
};

class EnqueuedResponseHeader
{
public:
    EnqueuedResponseHeader(void): mDequeueTime(0), mMessageInfo() {}

    EnqueuedResponseHeader(const Ip6::MessageInfo &aMessageInfo):
        mDequeueTime(TimerMilli::GetNow() + TimerMilli::SecToMsec(kExchangeLifetime)),
        mMessageInfo(aMessageInfo) {}

    otError AppendTo(Message &aMessage) const { return aMessage.Append(this, sizeof(*this)); }

    uint16_t ReadFrom(const Message &aMessage) {
        return aMessage.Read(aMessage.GetLength() - sizeof(*this), sizeof(*this), this);
    }

    static void RemoveFrom(Message &aMessage) {
        assert(aMessage.SetLength(aMessage.GetLength() - sizeof(EnqueuedResponseHeader)) == OT_ERROR_NONE);
    }

    bool IsEarlier(uint32_t aTime) const { return (static_cast<int32_t>(aTime - mDequeueTime) > 0); }

    uint32_t GetRemainingTime(void) const;

    const Ip6::MessageInfo &GetMessageInfo(void) const { return mMessageInfo; }

private:
    uint32_t mDequeueTime;
    const Ip6::MessageInfo mMessageInfo;
};

class ResponsesQueue
{
public:
    ResponsesQueue(otInstance &aInstance, Timer::Handler aHandler, void *aContext);

    void EnqueueResponse(Message &aMessage, const Ip6::MessageInfo &aMessageInfo);

    void DequeueOldestResponse(void);

    void DequeueAllResponses(void);

    otError GetMatchedResponseCopy(const Header &aHeader,
                                   const Ip6::MessageInfo &aMessageInfo,
                                   Message **aResponse);

    otError GetMatchedResponseCopy(const Message &aRequest,
                                   const Ip6::MessageInfo &aMessageInfo,
                                   Message **aResponse);

    const MessageQueue &GetResponses(void) const { return mQueue; }

    void HandleTimer(void);

private:
    enum
    {
        kMaxCachedResponses = OPENTHREAD_CONFIG_COAP_SERVER_MAX_CACHED_RESPONSES,
    };

    void DequeueResponse(Message &aMessage) { mQueue.Dequeue(aMessage); aMessage.Free(); }

    MessageQueue mQueue;
    TimerMilli   mTimer;
};

class CoapBase: public InstanceLocator
{
    friend class ResponsesQueue;

public:
    typedef otError(* Interceptor)(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo, void *aContext);

    otError Start(uint16_t aPort);

    otError Stop(void);

    uint16_t GetPort(void) { return mSocket.GetSockName().mPort; };

    otError AddResource(Resource &aResource);

    void RemoveResource(Resource &aResource);

    /* This function sets the default handler for unhandled CoAP requests.
     *
     * @param[in]  aHandler   A function pointer that shall be called when an unhandled request arrives.
     * @param[in]  aContext   A pointer to arbitrary context information. May be NULL if not used.
     */
    void SetDefaultHandler(otCoapRequestHandler aHandler, void *aContext);

    Message *NewMessage(const Header &aHeader, uint8_t aPriority = kDefaultCoapMessagePriority);

    otError SendMessage(Message &aMessage, const Ip6::MessageInfo &aMessageInfo,
                        otCoapResponseHandler aHandler = NULL, void *aContext = NULL);

    otError SendReset(Header &aRequestHeader, const Ip6::MessageInfo &aMessageInfo) {
        return SendEmptyMessage(OT_COAP_TYPE_RESET, aRequestHeader, aMessageInfo);
    };

    otError SendHeaderResponse(Header::Code aCode, const Header &aRequestHeader, const Ip6::MessageInfo &aMessageInfo);

    otError SendAck(Header &aRequestHeader, const Ip6::MessageInfo &aMessageInfo) {
        return SendEmptyMessage(OT_COAP_TYPE_ACKNOWLEDGMENT, aRequestHeader, aMessageInfo);
    };

    otError SendEmptyAck(const Header &aRequestHeader, const Ip6::MessageInfo &aMessageInfo) {
        return (aRequestHeader.GetType() == OT_COAP_TYPE_CONFIRMABLE ?
                SendHeaderResponse(OT_COAP_CODE_CHANGED, aRequestHeader, aMessageInfo) :
                OT_ERROR_INVALID_ARGS);
    }

    otError SendNotFound(const Header &aRequestHeader, const Ip6::MessageInfo &aMessageInfo) {
        return SendHeaderResponse(OT_COAP_CODE_NOT_FOUND, aRequestHeader, aMessageInfo);
    }

    otError AbortTransaction(otCoapResponseHandler aHandler, void *aContext);

    void SetInterceptor(Interceptor aInterceptor, void *aContext) {
        mInterceptor = aInterceptor;
        mContext = aContext;
    }

    const MessageQueue &GetRequestMessages(void) const { return mPendingRequests; }

    const MessageQueue &GetCachedResponses(void) const { return mResponsesQueue.GetResponses(); }

protected:
    CoapBase(otInstance &aInstance, Timer::Handler aRetransmissionTimerHandler,
             Timer::Handler aResponsesQueueTimerHandler);

    void HandleRetransmissionTimer(void);

    void HandleResponsesQueueTimer(void) { mResponsesQueue.HandleTimer(); }

    virtual otError Send(Message &aMessage, const Ip6::MessageInfo &aMessageInfo);

    virtual void Receive(Message &aMessage, const Ip6::MessageInfo &aMessageInfo);

    Ip6::UdpSocket mSocket;

private:
    enum
    {
        kDefaultCoapMessagePriority = Message::kPriorityLow,
    };

    static void HandleUdpReceive(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo);

    Message *CopyAndEnqueueMessage(const Message &aMessage, uint16_t aCopyLength,
                                   const CoapMetadata &aCoapMetadata);
    void DequeueMessage(Message &aMessage);
    Message *FindRelatedRequest(const Header &aResponseHeader, const Ip6::MessageInfo &aMessageInfo,
                                Header &aRequestHeader, CoapMetadata &aCoapMetadata);
    void FinalizeCoapTransaction(Message &aRequest, const CoapMetadata &aCoapMetadata, Header *aResponseHeader,
                                 Message *aResponse, const Ip6::MessageInfo *aMessageInfo, otError aResult);

    void ProcessReceivedRequest(Header &aHeader, Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
    void ProcessReceivedResponse(Header &aHeader, Message &aMessage, const Ip6::MessageInfo &aMessageInfo);

    otError SendCopy(const Message &aMessage, const Ip6::MessageInfo &aMessageInfo);
    otError SendEmptyMessage(Header::Type aType, const Header &aRequestHeader,
                             const Ip6::MessageInfo &aMessageInfo);

    MessageQueue mPendingRequests;
    uint16_t mMessageId;
    TimerMilli mRetransmissionTimer;

    Resource *mResources;

    void           *mContext;
    Interceptor    mInterceptor;
    ResponsesQueue mResponsesQueue;

    otCoapRequestHandler mDefaultHandler;
    void *mDefaultHandlerContext;
};

class Coap: public CoapBase
{
public:
    Coap(otInstance &aInstance);

private:
    static Coap &GetOwner(const Context &aContext);
    static void HandleRetransmissionTimer(Timer &aTimer);
    static void HandleResponsesQueueTimer(Timer &aTimer);
};

#if OPENTHREAD_ENABLE_APPLICATION_COAP

class ApplicationCoap: public CoapBase
{
public:
    ApplicationCoap(otInstance &aInstance);

private:
    static ApplicationCoap &GetOwner(const Context &aContext);
    static void HandleRetransmissionTimer(Timer &aTimer);
    static void HandleResponsesQueueTimer(Timer &aTimer);
};

#endif

}  // namespace Coap
}  // namespace ot

#endif  // COAP_HPP_