src/app/util/client-api.h

   1 /**
   2  *
   3  *    Copyright (c) 2020 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  *
  20  *    Copyright (c) 2020 Silicon Labs
  21  *
  22  *    Licensed under the Apache License, Version 2.0 (the "License");
  23  *    you may not use this file except in compliance with the License.
  24  *    You may obtain a copy of the License at
  25  *
  26  *        http://www.apache.org/licenses/LICENSE-2.0
  27  *
  28  *    Unless required by applicable law or agreed to in writing, software
  29  *    distributed under the License is distributed on an "AS IS" BASIS,
  30  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  31  *    See the License for the specific language governing permissions and
  32  *    limitations under the License.
  33  */
  34 /***************************************************************************/
  35 /**
  36  * @file
  37  * @brief API for generating command buffer.
  38  *******************************************************************************
  39  ******************************************************************************/
  40
  41 #pragma once
  42
  43 #include "af-types.h"
  44
  45 /*
  46    @addtogroup command
  47    @{
  48  */
  49
  50 /** @name Client API functions */
  51 // @{
  52
  53 /**
  54  * @brief Function that fills in the buffer with command.
  55  *
  56  * Fills the outgoing ZCL buffer and returns the number
  57  * of bytes used in a buffer. Uses the buffers that
  58  * were previously set with emberAfSetExternalBuffer.
  59  *
  60  * @param frameControl Byte used for frame control.
  61  * @param clusterId Cluster ID of message.
  62  * @param commandId Command ID of message.
  63  * @param format String format for further arguments to the function.
  64  *   Format values are:
  65  *     - '0' - '9' and 'A' - 'G': Pointer to a buffer containing 0--16 raw
  66  *            bytes.  The data is copied as is to the destination buffer.
  67  *     - 'u': uint8_t.
  68  *     - 'v': uint16_t. The bytes are copied in little-endian format to the
  69  *            destination buffer.
  70  *     - 'x': int24u. The bytes are copied in little-endian format to the
  71  *            destination buffer.
  72  *     - 'w': uint32_t. The bytes are copied in little-endian format to the
  73  *            destination buffer.
  74  *     - 'l': Pointer to a buffer containing a ZigBee long string, with the
  75  *            first two bytes of the buffer specifying the length of the string
  76  *            data in little-endian format. The length bytes and the string
  77  *            itself are both included as is in the destination buffer.
  78  *     - 's': Pointer to a buffer containing a ZigBee string, with the first
  79  *            byte of the buffer specifying the length of the string data. The
  80  *            length byte and the string itself are both included as is in the
  81  *            destination buffer.
  82  *     - 'L': Pointer to a buffer containing a long string followed by an
  83  *            uint16_t specifying the length of the string data. The length
  84  *            bytes in little-endian format will precede the string itself in
  85  *            the destination buffer.
  86  *     - 'S': Pointer to a buffer containing a string followed by an uint8_t
  87  *            specifying the length of the string data. The length byte will
  88  *            precede the string itself in the destination buffer.
  89  *     - 'b': Pointer to a buffer containing a sequence of raw bytes followed
  90  *            by an uint16_t specifying the length of the data. The data is
  91  *            copied as is to the destination buffer. The length is not
  92  *            included.
  93  */
  94 uint16_t emberAfFillExternalBuffer(uint8_t frameControl, chip::ClusterId clusterId, chip::CommandId commandId, const char * format,
  95                                    ...);
  96
  97 /**
  98  * @brief Function that fills in the buffer with manufacturer-specific command.
  99  *
 100  * Fills the outgoing ZCL buffer and returns the number
 101  * of bytes used in a buffer. Uses the buffers that
 102  * were previously set with emberAfSetExternalBuffer.
 103  *
 104  * @param frameControl Byte used for frame control.
 105  * @param clusterId Cluster ID of message.
 106  * @param manufacturerCode Manufacturer code of message.
 107  * @param commandId Command ID of message.
 108  * @param format String format for further arguments to the function.
 109  *   Format values are:
 110  *     - '0' -- '9' and 'A' -- 'G': Pointer to a buffer containing 0--16 raw
 111  *            bytes. The data is copied as is to the destination buffer.
 112  *     - 'u': uint8_t.
 113  *     - 'v': uint16_t. The bytes are copied in little-endian format to the
 114  *            destination buffer.
 115  *     - 'x': int24u. The bytes are copied in little-endian format to the
 116  *            destination buffer.
 117  *     - 'w': uint32_t. The bytes are copied in little-endian format to the
 118  *            destination buffer.
 119  *     - 'l': Pointer to a buffer containing a ZigBee long string, with the
 120  *            first two bytes of the buffer specifying the length of the string
 121  *            data in little-endian format. The length bytes and the string
 122  *            itself are both included as is in the destination buffer.
 123  *     - 's': Pointer to a buffer containing a ZigBee string, with the first
 124  *            byte of the buffer specifying the length of the string data. The
 125  *            length byte and the string itself are both included as is in the
 126  *            destination buffer.
 127  *     - 'L': Pointer to a buffer containing a long string followed by an
 128  *            uint16_t specifying the length of the string data. The length
 129  *            bytes in little-endian format will precede the string itself in
 130  *            the destination buffer.
 131  *     - 'S': Pointer to a buffer containing a string followed by an uint8_t
 132  *            specifying the length of the string data. The length byte will
 133  *            precede the string itself in the destination buffer.
 134  *     - 'b': Pointer to a buffer containing a sequence of raw bytes followed
 135  *            by an uint16_t specifying the length of the data. The data is
 136  *            copied as is to the destination buffer. The length is not
 137  *            included.
 138  */
 139 uint16_t emberAfFillExternalManufacturerSpecificBuffer(uint8_t frameControl, chip::ClusterId clusterId, uint16_t manufacturerCode,
 140                                                        chip::CommandId commandId, const char * format, ...);
 141
 142 /**
 143  * @brief Function that registers the buffer to use with the fill function.
 144  * Registers the buffer for use with the emberAfFillExternalBuffer function.
 145  *
 146  * @param buffer Main buffer for constructing message.
 147  * @param bufferLen Available length of buffer.
 148  * @param responseLengthPtr Location where length of message will be written into.
 149  * @param apsFramePtr Location where APS frame data will be written.
 150  */
 151 void emberAfSetExternalBuffer(uint8_t * buffer, uint16_t bufferLen, uint16_t * responseLengthPtr, EmberApsFrame * apsFramePtr);
 152
 153 /**
 154  * @brief Stateless function that fills the passed buffer with command data.
 155  *
 156  * Stateless method, that fill the passed buffer.
 157  * Used internally by emberAfFillExternalBuffer, but can be used
 158  * for generic buffer filling.
 159  */
 160 uint16_t emberAfFillBuffer(uint8_t * buffer, uint16_t bufferLen, uint8_t frameControl, chip::CommandId commandId,
 161                            const char * format, ...);
 162
 163 #if !defined(DOXYGEN_SHOULD_SKIP_THIS)
 164 // The buffer used for filling ZCL Messages.
 165 extern uint8_t * emAfZclBuffer;
 166 // Max length of the buffer.
 167 extern uint16_t emAfZclBufferLen;
 168 // Pointer to where this API should put the length.
 169 extern uint16_t * emAfResponseLengthPtr;
 170 // The APS frame accompanying the ZCL message.
 171 extern EmberApsFrame * emAfCommandApsFrame;
 172 #endif
 173
 174 // Generated macros.
 175
 176 #define emberAfAppendToExternalBuffer(...) emberAfPutBlockInResp(__VA_ARGS__)
 177
 178 /** @} END Client API functions */
 179
 180 /** @} END addtogroup
 181  */