src/messaging/Channel.h

   1 /*
   2  *
   3  *    Copyright (c) 2021 Project CHIP Authors
   4  *
   5  *    Licensed under the Apache License, Version 2.0 (the "License");
   6  *    you may not use this file except in compliance with the License.
   7  *    You may obtain a copy of the License at
   8  *
   9  *        http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  *    Unless required by applicable law or agreed to in writing, software
  12  *    distributed under the License is distributed on an "AS IS" BASIS,
  13  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  *    See the License for the specific language governing permissions and
  15  *    limitations under the License.
  16  */
  17
  18 /**
  19  *    @file
  20  *      This file defines the API classes for to CHIP Channel.
  21  *
  22  *      Channel is a object to abstract all low layer dependencies of an
  23  *      exchange, including secure session, transport connection and network
  24  *      status.
  25  *
  26  *      Channel is not connection. Channel can abstract both connection
  27  *      oriented and connectionless transports, It contains information to send
  28  *      and receive messages via exchanges. For example, when using
  29  *      connectionless transport, channel will contain peer address and session
  30  *      key; when using connection oriented transport, channel will contain
  31  *      connection handle and session key.
  32  *
  33  *      Channel is not session. Session do persistent through cold reboot, but
  34  *      channel doesn't. Applications must re-establish channels after a cold
  35  *      reboot.
  36  *
  37  *      Because channel is a local concept, peer device is not able aware of
  38  *      channel establishment events. Instead, peer device is able to aware
  39  *      session establishment events, connection establishment events for
  40  *      connection oriented transport and message received events for
  41  *      connectionless transport.
  42  */
  43
  44 #pragma once
  45
  46 #include <inet/IPAddress.h>
  47 #include <transport/raw/MessageHeader.h>
  48
  49 namespace chip {
  50 namespace Messaging {
  51
  52 /**
  53  *  @brief
  54  *    The ChannelBuilder object provides information to build a Channel.
  55  *
  56  *    ChannelBuilder can be used by application to provide information to
  57  *    request a channel to a peer. When a channel is requested via
  58  *    ExchangeManager::EstablishChannel, a ChannelHandle will be return to
  59  *    represent the state of the channel
  60  *
  61  *    The ChannelBuilder object should be short-live and it is only used within
  62  *    ExchangeManager::EstablishChannel call, after the call its state will be
  63  *    copied into an internal object represented by ChannelHandle, then the
  64  *    ChannelBuilder can be safely released.
  65  */
  66 class ChannelBuilder
  67 {
  68 public:
  69     enum class TransportPreference
  70     {
  71         kConnectionless,
  72         kPreferConnectionOriented, // will fallback to connectionless if TCP is not supported
  73         kConnectionOriented,       // will fail if TCP is not supported
  74
  75         kDefault = kConnectionless,
  76     };
  77
  78     ChannelBuilder & SetPeerNodeId(NodeId peerNodeId)
  79     {
  80         mPeerNodeId = peerNodeId;
  81         return *this;
  82     }
  83     NodeId GetPeerNodeId() const { return mPeerNodeId; }
  84
  85     ChannelBuilder & SetTransportPreference(TransportPreference preference)
  86     {
  87         mTransportPreference = preference;
  88         return *this;
  89     }
  90     TransportPreference GetTransportPreference() const { return mTransportPreference; }
  91
  92     uint16_t GetPeerKeyID() const { return mCaseParameters.mPeerKeyId; }
  93     ChannelBuilder & SetPeerKeyID(uint16_t keyId)
  94     {
  95         mCaseParameters.mPeerKeyId = keyId;
  96         return *this;
  97     }
  98
  99     Optional<Inet::IPAddress> GetForcePeerAddress() const { return mForcePeerAddr; }
 100     ChannelBuilder & SetForcePeerAddress(Inet::IPAddress peerAddr)
 101     {
 102         mForcePeerAddr.SetValue(peerAddr);
 103         return *this;
 104     }
 105
 106 private:
 107     NodeId mPeerNodeId                       = kUndefinedNodeId;
 108     TransportPreference mTransportPreference = TransportPreference::kDefault;
 109     struct
 110     {
 111         uint16_t mPeerKeyId;
 112     } mCaseParameters;
 113
 114     Optional<Inet::IPAddress> mForcePeerAddr;
 115 };
 116
 117 class ExchangeContext;
 118 class ExchangeDelegate;
 119
 120 enum class ChannelState
 121 {
 122     kNone,
 123     kPreparing,
 124     kReady,
 125     kClosed,
 126     kFailed,
 127 };
 128
 129 class ChannelContextHandleAssociation;
 130
 131 /**
 132  *  @brief
 133  *    ChannelHandle is a reference to a channel. An active ChannelHandle will
 134  *    keep the channel available and ready for use, such that a message can be
 135  *    sent immediately to the peer.
 136  *
 137  *    The ChannelHandle controls the lifespan of the channel. When the handle
 138  *    is released, the channel will be flagged as pending close, and if there
 139  *    is no active exchange which is using the channel, the channel will be
 140  *    closed.
 141  *
 142  *    The ChannelHandle will track channel status, and notify applications
 143  *    when the channel state changes via ChannelDelegate.
 144  */
 145 class ChannelHandle
 146 {
 147 public:
 148     explicit ChannelHandle(ChannelContextHandleAssociation * association = nullptr) : mAssociation(association) {}
 149     ~ChannelHandle() { Release(); }
 150
 151     // non copyable
 152     ChannelHandle(const ChannelHandle &) = delete;
 153     ChannelHandle & operator=(const ChannelHandle &) = delete;
 154
 155     // movable
 156     ChannelHandle(ChannelHandle && that)
 157     {
 158         Release();
 159         this->mAssociation = that.mAssociation;
 160         that.mAssociation  = nullptr;
 161     }
 162     ChannelHandle & operator=(ChannelHandle && that)
 163     {
 164         Release();
 165         this->mAssociation = that.mAssociation;
 166         that.mAssociation  = nullptr;
 167         return *this;
 168     }
 169
 170     ChannelState GetState() const;
 171
 172     /*
 173      * @brief
 174      *  Create a new exchange on the channel.
 175      *
 176      * @pre GetState() == ChannelState::kReady
 177      */
 178     ExchangeContext * NewExchange(ExchangeDelegate * delegate);
 179
 180     void Release();
 181
 182 private:
 183     ChannelContextHandleAssociation * mAssociation;
 184 };
 185
 186 /**
 187  *  @brief
 188  *    Callback receiver interface of channels
 189  */
 190 class ChannelDelegate
 191 {
 192 public:
 193     virtual ~ChannelDelegate() {}
 194
 195     virtual void OnEstablished()        = 0;
 196     virtual void OnClosed()             = 0;
 197     virtual void OnFail(CHIP_ERROR err) = 0;
 198 };
 199
 200 } // namespace Messaging
 201 } // namespace chip