src/lib/protocols/status-report/StatusReportProtocol.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2013-2017 Nest Labs, Inc.
   5  *    All rights reserved.
   6  *
   7  *    Licensed under the Apache License, Version 2.0 (the "License");
   8  *    you may not use this file except in compliance with the License.
   9  *    You may obtain a copy of the License at
  10  *
  11  *        http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  *    Unless required by applicable law or agreed to in writing, software
  14  *    distributed under the License is distributed on an "AS IS" BASIS,
  15  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  *    See the License for the specific language governing permissions and
  17  *    limitations under the License.
  18  */
  19
  20 /**
  21  *    @file
  22  *      This file defines an object for reading and writing CHIP
  23  *      Status Reports.
  24  *
  25  *      Status Reports are used in CHIP for over-the-wire status and
  26  *      error reporting that can act as a notification or confirmation
  27  *      in response to a request or command.
  28  *
  29  *      The format of a status report is:
  30  *      @code
  31  *        | <profile ID> | <status code> | <additional status info> |
  32  *      @endcode
  33  *
  34  */
  35
  36 #ifndef _STATUS_REPORT_PROTOCOL_H
  37 #define _STATUS_REPORT_PROTOCOL_H
  38
  39 #include <message/CHIPMessageLayer.h>
  40 #include <support/DLLUtil.h>
  41
  42 /**
  43  *   @namespace chip::Protocols::StatusReporting
  44  *
  45  *   @brief
  46  *     This namespace includes all interfaces within CHIP for the
  47  *     CHIP Status Reporting subprofile, which is part of and within
  48  *     the CHIP Common profile.
  49  */
  50
  51 namespace chip {
  52 namespace Protocols {
  53 namespace StatusReporting {
  54
  55 /*
  56  * in-memory, a status report, at its most basic, is a CHIP profile
  57  * ID and status code pair. then there's the option of chaining on
  58  * more status information as TLV.
  59  */
  60
  61 class DLL_EXPORT StatusReport
  62 {
  63 public:
  64     StatusReport();
  65     ~StatusReport();
  66
  67     CHIP_ERROR init(uint32_t aProtocolId, uint16_t aCode, ReferencedTLVData * aInfo = nullptr);
  68
  69     /*
  70      * this version of the intializer is provided as a convenience in
  71      * the case where we want to make a status report that reports an
  72      * internal error.
  73      */
  74
  75     CHIP_ERROR init(CHIP_ERROR aError);
  76
  77     CHIP_ERROR pack(PacketBuffer * aBuffer, uint32_t maxLen = 0xFFFFFFFFUL);
  78     uint16_t packedLength();
  79     static CHIP_ERROR parse(PacketBuffer * aBuffer, StatusReport & aDestination);
  80
  81     bool operator==(const StatusReport & another) const;
  82
  83     bool success();
  84
  85     /*
  86      * here are some static convenience methods for adding metadata
  87      */
  88
  89     static CHIP_ERROR StartMetaData(chip::TLV::TLVWriter & aWriter);
  90     static CHIP_ERROR EndMetaData(chip::TLV::TLVWriter & aWriter);
  91
  92     static CHIP_ERROR AddErrorCode(chip::TLV::TLVWriter & aWriter, CHIP_ERROR aError);
  93
  94     // data members
  95
  96     uint32_t mProtocolId;
  97     uint16_t mStatusCode;
  98     CHIP_ERROR mError;
  99     ReferencedTLVData mAdditionalInfo;
 100 };
 101
 102 } // namespace StatusReporting
 103 } // namespace Protocols
 104 } // namespace chip
 105
 106 #endif // _STATUS_REPORT_PROTOCOL_H