From 5924d518565426b175a3b0c73bd929767732cae2 Mon Sep 17 00:00:00 2001 From: Boris Zbarsky Date: Tue, 25 May 2021 16:44:12 -0400 Subject: [PATCH] Clearly document lifetime expectations for CommandSender. (#7067) --- src/app/CommandSender.h | 11 ++++++++++- src/app/InteractionModelEngine.h | 2 +- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/src/app/CommandSender.h b/src/app/CommandSender.h index 093722b88550c0..aa0a47e7d2366f 100644 --- a/src/app/CommandSender.h +++ b/src/app/CommandSender.h @@ -46,13 +46,22 @@ class CommandSender : public Command, public Messaging::ExchangeDelegate { public: // TODO: issue #6792 - the secure session parameter should be made non-optional and passed by reference. + // Once SendCommandRequest returns successfully, the CommandSender will + // handle calling Shutdown on itself once it decides it's done with waiting + // for a response (i.e. times out or gets a response). + // + // If SendCommandRequest is never called, or the call fails, the API + // consumer is responsible for calling Shutdown on the CommandSender. CHIP_ERROR SendCommandRequest(NodeId aNodeId, Transport::AdminId aAdminId, SecureSessionHandle * secureSession = nullptr); +private: + // ExchangeDelegate interface implementation. Private so people won't + // accidentally call it on us when we're not being treated as an actual + // ExchangeDelegate. void OnMessageReceived(Messaging::ExchangeContext * apExchangeContext, const PacketHeader & aPacketHeader, const PayloadHeader & aPayloadHeader, System::PacketBufferHandle && aPayload) override; void OnResponseTimeout(Messaging::ExchangeContext * apExchangeContext) override; -private: CHIP_ERROR ProcessCommandDataElement(CommandDataElement::Parser & aCommandElement) override; }; diff --git a/src/app/InteractionModelEngine.h b/src/app/InteractionModelEngine.h index 2ed9e4967ce0a1..c2ff6ea0111a53 100644 --- a/src/app/InteractionModelEngine.h +++ b/src/app/InteractionModelEngine.h @@ -100,7 +100,7 @@ class InteractionModelEngine : public Messaging::ExchangeDelegate /** * Retrieve a CommandSender that the SDK consumer can use to send a set of commands. If the call succeeds, - * the consumer is responsible for calling Shutdown() on the CommandSender once it's done using it. + * see CommandSender documentation for lifetime handling. * * @param[out] apCommandSender A pointer to the CommandSender object. *