src/app/Command.h

   1 /*
   2  *
   3  *    Copyright (c) 2020-2021 Project CHIP Authors
   4  *    All rights reserved.
   5  *
   6  *    Licensed under the Apache License, Version 2.0 (the "License");
   7  *    you may not use this file except in compliance with the License.
   8  *    You may obtain a copy of the License at
   9  *
  10  *        http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *    Unless required by applicable law or agreed to in writing, software
  13  *    distributed under the License is distributed on an "AS IS" BASIS,
  14  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *    See the License for the specific language governing permissions and
  16  *    limitations under the License.
  17  */
  18
  19 /**
  20  *    @file
  21  *      This file defines Base class for a CHIP IM Command
  22  *
  23  */
  24
  25 #pragma once
  26
  27 #include <core/CHIPCore.h>
  28 #include <messaging/ExchangeContext.h>
  29 #include <messaging/ExchangeMgr.h>
  30 #include <messaging/Flags.h>
  31 #include <protocols/Protocols.h>
  32 #include <support/BitFlags.h>
  33 #include <support/CodeUtils.h>
  34 #include <support/DLLUtil.h>
  35 #include <support/logging/CHIPLogging.h>
  36 #include <system/SystemPacketBuffer.h>
  37 #include <system/TLVPacketBufferBackingStore.h>
  38
  39 #include <app/InteractionModelDelegate.h>
  40 #include <app/MessageDef/CommandDataElement.h>
  41 #include <app/MessageDef/CommandList.h>
  42 #include <app/MessageDef/InvokeCommand.h>
  43
  44 namespace chip {
  45 namespace app {
  46
  47 class Command
  48 {
  49 public:
  50     enum class CommandRoleId
  51     {
  52         SenderId  = 0,
  53         HandlerId = 1,
  54     };
  55
  56     enum class CommandState
  57     {
  58         Uninitialized = 0, //< The invoke command message has not been initialized
  59         Initialized,       //< The invoke command message has been initialized and is ready
  60         AddCommand,        //< The invoke command message has added Command
  61         Sending,           //< The invoke command message  has sent out the invoke command
  62     };
  63
  64     enum class CommandPathFlags : uint8_t
  65     {
  66         kEndpointIdValid = 0x01, /**< Set when the EndpointId field is valid */
  67         kGroupIdValid    = 0x02, /**< Set when the GroupId field is valid */
  68     };
  69
  70     /**
  71      * Encapsulates arguments to be passed into SendCommand().
  72      *
  73      */
  74     struct CommandParams
  75     {
  76         CommandParams(chip::EndpointId endpointId, chip::GroupId groupId, chip::ClusterId clusterId, chip::CommandId commandId,
  77                       const BitFlags<CommandPathFlags> & flags) :
  78             EndpointId(endpointId),
  79             GroupId(groupId), ClusterId(clusterId), CommandId(commandId), Flags(flags)
  80         {}
  81
  82         chip::EndpointId EndpointId;
  83         chip::GroupId GroupId;
  84         chip::ClusterId ClusterId;
  85         chip::CommandId CommandId;
  86         BitFlags<CommandPathFlags> Flags;
  87     };
  88
  89     /**
  90      *  Initialize the Command object. Within the lifetime
  91      *  of this instance, this method is invoked once after object
  92      *  construction until a call to Shutdown is made to terminate the
  93      *  instance.
  94      *
  95      *  @param[in]    apExchangeMgr    A pointer to the ExchangeManager object.
  96      *  @param[in]    apDelegate       InteractionModelDelegate set by application.
  97      *
  98      *  @retval #CHIP_ERROR_INCORRECT_STATE If the state is not equal to
  99      *          CommandState::NotInitialized.
 100      *  @retval #CHIP_NO_ERROR On success.
 101      *
 102      */
 103     CHIP_ERROR Init(Messaging::ExchangeManager * apExchangeMgr, InteractionModelDelegate * apDelegate);
 104
 105     /**
 106      *  Shutdown the CommandSender. This terminates this instance
 107      *  of the object and releases all held resources.
 108      *
 109      */
 110     void Shutdown();
 111
 112     /**
 113      * Finalize Command Message TLV Builder and finalize command message
 114      *
 115      * @return CHIP_ERROR
 116      *
 117      */
 118     CHIP_ERROR FinalizeCommandsMessage();
 119
 120     chip::TLV::TLVWriter & CreateCommandDataElementTLVWriter();
 121     CHIP_ERROR AddCommand(chip::EndpointId aEndpintId, chip::GroupId aGroupId, chip::ClusterId aClusterId,
 122                           chip::CommandId aCommandId, BitFlags<CommandPathFlags> Flags);
 123     CHIP_ERROR AddCommand(CommandParams & aCommandParams);
 124     CHIP_ERROR AddStatusCode(const Protocols::SecureChannel::GeneralStatusCode aGeneralCode, Protocols::Id aProtocolId,
 125                              const uint16_t aProtocolCode);
 126
 127     /**
 128      * Gets the inner exchange context object, without ownership.
 129      *
 130      * @return The inner exchange context, might be nullptr if no
 131      *         exchange context has been assigned or the context
 132      *         has been released.
 133      */
 134     const Messaging::ExchangeContext * GetExchangeContext() const { return mpExchangeCtx; }
 135
 136     CHIP_ERROR Reset();
 137
 138     virtual ~Command() = default;
 139
 140     bool IsFree() const { return (nullptr == mpExchangeCtx); };
 141     virtual CHIP_ERROR ProcessCommandDataElement(CommandDataElement::Parser & aCommandElement) = 0;
 142
 143 protected:
 144     CHIP_ERROR ClearExistingExchangeContext();
 145     void MoveToState(const CommandState aTargetState);
 146     CHIP_ERROR ProcessCommandMessage(System::PacketBufferHandle && payload, CommandRoleId aCommandRoleId);
 147     void ClearState();
 148     const char * GetStateStr() const;
 149
 150     Messaging::ExchangeManager * mpExchangeMgr = nullptr;
 151     Messaging::ExchangeContext * mpExchangeCtx = nullptr;
 152     InteractionModelDelegate * mpDelegate      = nullptr;
 153     chip::System::PacketBufferHandle mCommandMessageBuf;
 154     uint8_t mCommandIndex = 0;
 155
 156 private:
 157     friend class TestCommandInteraction;
 158     chip::System::PacketBufferHandle mpBufHandle;
 159     InvokeCommand::Builder mInvokeCommandBuilder;
 160     CommandState mState;
 161
 162     chip::System::PacketBufferHandle mCommandDataBuf;
 163     chip::System::PacketBufferTLVWriter mCommandMessageWriter;
 164     chip::System::PacketBufferTLVWriter mCommandDataWriter;
 165 };
 166 } // namespace app
 167 } // namespace chip