| /* |
| * Copyright (c) 2016, The OpenThread Authors. |
| * All rights reserved. |
| * |
| * Redistribution and use in source and binary forms, with or without |
| * modification, are permitted provided that the following conditions are met: |
| * 1. Redistributions of source code must retain the above copyright |
| * notice, this list of conditions and the following disclaimer. |
| * 2. Redistributions in binary form must reproduce the above copyright |
| * notice, this list of conditions and the following disclaimer in the |
| * documentation and/or other materials provided with the distribution. |
| * 3. Neither the name of the copyright holder nor the |
| * names of its contributors may be used to endorse or promote products |
| * derived from this software without specific prior written permission. |
| * |
| * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND |
| * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
| * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
| * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY |
| * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
| * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
| * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND |
| * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
| * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| */ |
| |
| /** |
| * @file |
| * This file includes definitions for an HDLC-lite encoder and decoder. |
| */ |
| |
| #ifndef HDLC_HPP_ |
| #define HDLC_HPP_ |
| #include <openthread/config.h> |
| #include <openthread/types.h> |
| |
| namespace ot { |
| |
| /** |
| * @namespace ot::Hdlc |
| * |
| * @brief |
| * This namespace includes definitions for the HDLC-lite encoder and decoder. |
| * |
| */ |
| namespace Hdlc { |
| |
| /** |
| * This class implements the HDLC-lite encoder. |
| * |
| */ |
| class Encoder |
| { |
| public: |
| |
| /** |
| * This class defines a write iterator into a buffer used by Encoder. |
| * |
| * Hdlc users should sub-class this to add the actual buffer space. |
| */ |
| class BufferWriteIterator |
| { |
| public: |
| |
| /** |
| * This method writes a byte to the buffer and updates the iterator (if space is available). |
| * |
| * @retval OT_ERROR_NONE Successfully wrote the byte and updates the iterator. |
| * @retval OT_ERROR_NO_BUFS Insufficient buffer space. |
| * |
| */ |
| otError WriteByte(uint8_t aByte); |
| |
| /** |
| * This method checks if there is buffer space available to write @p aWriteLength bytes. |
| * |
| * param[in] aWriteLength Number of bytes to write. |
| * |
| * @retval true Enough buffer space available to write the requested number of bytes. |
| * @retval false Insufficient buffer space to write the requested number of bytes. |
| * |
| */ |
| bool CanWrite(uint16_t aWriteLength) const; |
| |
| protected: |
| |
| BufferWriteIterator(void); ///< Protected constructor to ensure no direct instantiation. |
| |
| uint8_t *mWritePointer; ///< A pointer to current write position in the buffer. |
| uint16_t mRemainingLength; ///< Number of remaining bytes available to write. |
| }; |
| |
| /** |
| * This constructor initializes the object. |
| * |
| */ |
| Encoder(void); |
| |
| /** |
| * This method begins an HDLC frame and puts the initial bytes into a buffer at the given @p aIterator. |
| * |
| * @param[inout] aIterator A reference to a buffer write iterator. On successful exit, the iterator is updated. |
| * |
| * @retval OT_ERROR_NONE Successfully started the HDLC frame. |
| * @retval OT_ERROR_NO_BUFS Insufficient buffer space available to start the HDLC frame. |
| * |
| */ |
| otError Init(BufferWriteIterator &aIterator); |
| |
| /** |
| * This method encodes a single byte into a buffer at @p aIterator. |
| * |
| * If there is no space to add the byte, the write iterator remains the same. |
| * |
| * @param[in] aInByte A byte to encode and add. |
| * @param[inout] aIterator A reference to a write buffer iterator. On successful exit, the iterator is updated. |
| * |
| * @retval OT_ERROR_NONE Successfully encoded and added the byte. |
| * @retval OT_ERROR_NO_BUFS Insufficient buffer space available to encode and add the byte. |
| * |
| */ |
| otError Encode(uint8_t aInByte, BufferWriteIterator &aIterator); |
| |
| /** |
| * This method encodes the frame into a buffer at @p aIterator. |
| * |
| * This method returns success only if there is space in buffer to encode the entire frame. If there is no space |
| * to encode the entire frame, the write iterator remains the same. |
| * |
| * @param[in] aInBuf A pointer to the input buffer. |
| * @param[in] aInLength The number of bytes in @p aInBuf to encode. |
| * @param[inout] aIterator A reference to a write buffer iterator. On successful exit, the iterator is updated. |
| * |
| * @retval OT_ERROR_NONE Successfully encoded the HDLC frame. |
| * @retval OT_ERROR_NO_BUFS Insufficient buffer space available to encode the HDLC frame. |
| * |
| */ |
| otError Encode(const uint8_t *aInBuf, uint16_t aInLength, BufferWriteIterator &aIterator); |
| |
| /** |
| * This method finalizes an HDLC frame. |
| * |
| * @param[inout] aIterator A reference to a write buffer iterator. On successful exit, the iterator is updated. |
| * |
| * @retval OT_ERROR_NONE Successfully ended the HDLC frame. |
| * @retval OT_ERROR_NO_BUFS Insufficient buffer space available to end the HDLC frame. |
| * |
| */ |
| otError Finalize(BufferWriteIterator &aIterator); |
| |
| private: |
| uint16_t mFcs; |
| }; |
| |
| /** |
| * This class implements the HDLC-lite decoder. |
| * |
| */ |
| class Decoder |
| { |
| public: |
| /** |
| * This function pointer is called when a complete frame has been formed. |
| * |
| * @param[in] aContext A pointer to arbitrary context information. |
| * @param[in] aFrame A pointer to the frame. |
| * @param[in] aFrameLength The frame length in bytes. |
| * |
| */ |
| typedef void (*FrameHandler)(void *aContext, uint8_t *aFrame, uint16_t aFrameLength); |
| |
| /** |
| * This function pointer is called when an error has occurred. |
| * |
| * @param[in] aContext A pointer to arbitrary context information. |
| * @param[in] aError An error code describing the error. |
| * @param[in] aFrame A pointer to the frame. |
| * @param[in] aFrameLength The frame length in bytes. |
| * |
| */ |
| typedef void (*ErrorHandler)(void *aContext, otError aError, uint8_t *aFrame, uint16_t aFrameLength); |
| |
| /** |
| * This constructor initializes the decoder. |
| * |
| * @param[in] aOutBuf A pointer to the output buffer. |
| * @param[in] aOutLength Size of the output buffer in bytes. |
| * @param[in] aFrameHandler A pointer to a function that is called when a complete frame is received. |
| * @param[in] aContext A pointer to arbitrary context information. |
| * |
| */ |
| Decoder(uint8_t *aOutBuf, uint16_t aOutLength, FrameHandler aFrameHandler, ErrorHandler aErrorHandler, |
| void *aContext); |
| |
| /** |
| * This method streams bytes into the decoder. |
| * |
| * @param[in] aInBuf A pointer to the input buffer. |
| * @param[in] aInLength The number of bytes in @p aInBuf. |
| * |
| */ |
| void Decode(const uint8_t *aInBuf, uint16_t aInLength); |
| |
| private: |
| enum State |
| { |
| kStateNoSync = 0, |
| kStateSync, |
| kStateEscaped, |
| }; |
| State mState; |
| |
| FrameHandler mFrameHandler; |
| ErrorHandler mErrorHandler; |
| void *mContext; |
| |
| uint8_t *mOutBuf; |
| uint16_t mOutOffset; |
| uint16_t mOutLength; |
| |
| uint16_t mFcs; |
| }; |
| |
| } // namespace Hdlc |
| } // namespace ot |
| |
| #endif // HDLC_HPP_ |