Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 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 : #pragma once
20 :
21 : #include <lib/core/Optional.h>
22 : #include <lib/support/BufferWriter.h>
23 : #include <optional>
24 : #include <protocols/Protocols.h>
25 : #include <protocols/secure_channel/Constants.h>
26 : #include <system/SystemClock.h>
27 : #include <system/SystemPacketBuffer.h>
28 :
29 : namespace chip {
30 : namespace Protocols {
31 : namespace SecureChannel {
32 :
33 : /**
34 : * Encapsulates the data included in a StatusReport message, and provides methods for writing to and reading from PacketBuffers
35 : * that contain StatusReport messages.
36 : */
37 : class DLL_EXPORT StatusReport
38 : {
39 : public:
40 : /**
41 : * Construct a StatusReport with zero-d out fields (for use before calling \c Parse() ).
42 : */
43 : StatusReport();
44 :
45 : /**
46 : * Construct a StatusReport with no additional ProtocolData.
47 : *
48 : * @param generalCode Required, one of the \c GeneralStatusCode values listed in \c secure_channel/Constants.h
49 : * @param protocolId Must specify a ProtocolId which consists of Vendor Id (upper 16 bits) and ProtocolId (lower 16 bits)
50 : * @param protocolCode A code defined by the specified protocol which provides more information about the status
51 : */
52 : StatusReport(GeneralStatusCode generalCode, Protocols::Id protocolId, uint16_t protocolCode);
53 :
54 : //
55 : /**
56 : * Construct a StatusReport with additional ProtocolData.
57 : *
58 : * @param generalCode Must specify a GeneralCode (see \c GeneralStatusCode )
59 : * @param protocolId Must specify a ProtocolId which consists of Vendor Id (upper 16 bits) and ProtocolId (lower 16 bits)
60 : * @param protocolCode A code defined by the specified protocol which provides more information about the status
61 : * @param protocolData A \c PacketBufferHandle containing the protocol-specific data
62 : */
63 : StatusReport(GeneralStatusCode generalCode, Protocols::Id protocolId, uint16_t protocolCode,
64 : System::PacketBufferHandle protocolData);
65 :
66 : /**
67 : * Read the contents of a \c PacketBuffer containing a StatusReport message and store the field values in this object.
68 : *
69 : * @note If there is additional data after the Protocol Code field in the message, it is assumed to be protocol-specific data.
70 : *
71 : * @note This method assumes that the Header of the message has already been consumed, and that \c PacketBuffer::Start() points
72 : * to the beginning of the StatusReport data.
73 : *
74 : * @param[in] buf A \c PacketBufferHandle containing the StatusReport message. This method will take ownership, and will
75 : * allocate a new PacketBuffer if any protocol-specific data exists.
76 : *
77 : * @return CHIP_ERROR Return an error if the message is malformed or buf is \c NULL
78 : */
79 : CHIP_ERROR Parse(System::PacketBufferHandle buf);
80 :
81 : /**
82 : * Write the StatusReport contents into a buffer using a \c BufferWriter
83 : *
84 : * @param[out] buf A \c BufferWriter which contains the buffer that will store the message fields.
85 : *
86 : * @return BufferWriter Return a reference to the \c BufferWriter
87 : */
88 : Encoding::LittleEndian::BufferWriter & WriteToBuffer(Encoding::LittleEndian::BufferWriter & buf) const;
89 :
90 : /**
91 : * Returns the minimum size of the buffer needed to write the message.
92 : */
93 : size_t Size() const;
94 :
95 7 : GeneralStatusCode GetGeneralCode() const { return mGeneralCode; }
96 6 : Protocols::Id GetProtocolId() const { return mProtocolId; }
97 6 : uint16_t GetProtocolCode() const { return mProtocolCode; }
98 : const System::PacketBufferHandle & GetProtocolData() const { return mProtocolData; }
99 :
100 : /**
101 : * Returns the minimum wait time if the status report is of type busy.
102 : * If status report is not busy, then this is an empty optional.
103 : */
104 2 : std::optional<System::Clock::Milliseconds16> GetMinimumWaitTime() const { return mMinimumWaitTime; }
105 :
106 : /**
107 : * Returns true if the status report is of type busy.
108 : */
109 : bool IsBusy() const;
110 :
111 : /**
112 : * Builds a busy status report with protocol data containing the minimum wait time.
113 : *
114 : * @param[in] minimumWaitTime Time in milliseconds before initiator retries the request
115 : *
116 : * @return Packet buffer handle which can be passed to SendMessage.
117 : */
118 : static System::PacketBufferHandle MakeBusyStatusReportMessage(System::Clock::Milliseconds16 minimumWaitTime);
119 :
120 : private:
121 : GeneralStatusCode mGeneralCode;
122 : Protocols::Id mProtocolId;
123 : uint16_t mProtocolCode;
124 : std::optional<System::Clock::Milliseconds16> mMinimumWaitTime;
125 : System::PacketBufferHandle mProtocolData;
126 : };
127 :
128 : } // namespace SecureChannel
129 : } // namespace Protocols
130 : } // namespace chip
|