246 lines
9.0 KiB
C
246 lines
9.0 KiB
C
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
/* */
|
|
/* file: aPacket.h */
|
|
/* */
|
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
/* */
|
|
/* description: Definition for BrainStem packet. */
|
|
/* */
|
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
/* */
|
|
/* Copyright (c) 2018 Acroname Inc. - All Rights Reserved */
|
|
/* */
|
|
/* This file is part of the BrainStem release. See the license.txt */
|
|
/* file included with this package or go to */
|
|
/* https://acroname.com/software/brainstem-development-kit */
|
|
/* for full license details. */
|
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
|
|
|
#ifndef _aPacket_H_
|
|
#define _aPacket_H_
|
|
|
|
#include "aDefs.h"
|
|
#include "aError.h"
|
|
|
|
#define MAX_PACKET_BYTES 28
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// BrainStem Packet
|
|
|
|
/** \defgroup aPacket Packet Interface
|
|
* \ref aPacket "aPacket.h" Provides and interface for creating and destroying
|
|
* BrainStem Protocol packets.
|
|
*/
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Const value used to check packet validity.
|
|
extern const uint16_t VALIDPACKET;
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Struct for BrainStem packets.
|
|
|
|
/**
|
|
* the check member is for checking the validity of the packet structure in memory.
|
|
* Current size is used during link stream processing. Address, dataSize and data
|
|
* fulfill the requirements of the BrainStem protocol.
|
|
*/
|
|
typedef struct aPacket {
|
|
const uint16_t check;
|
|
uint8_t curSize; /* current number of data input */
|
|
uint8_t address; /* module address */
|
|
uint8_t dataSize; /* length of following data */
|
|
uint8_t data[MAX_PACKET_BYTES];
|
|
} aPacket;
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Typedef #aPacketMatchPacketProc.
|
|
|
|
/**
|
|
* This callback is used to match against packets in the FIFO.
|
|
* \param p - the que packet to match against.
|
|
* \param vpRef - Callback reference value.
|
|
* \return - uint8_t non-zero on a match and zero on a mismatch.
|
|
*/
|
|
typedef uint8_t (*aPacketMatchPacketProc) (const aPacket* p, const void* vpRef);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Check packet pointer for validity.
|
|
|
|
/**
|
|
* Checks to make sure a packet was allocated using aPacket_Create.
|
|
*
|
|
* \param packet - valid packet pointer.
|
|
* \return bool - True for valid false otherwise.
|
|
*/
|
|
aLIBEXPORT bool aVALIDPACKET(const aPacket* packet);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Create a BrainStem packet.
|
|
|
|
/**
|
|
* Create a BrainStem packet.
|
|
*
|
|
* \return aPacket - Pointer or NULL on error.
|
|
*/
|
|
aLIBEXPORT aPacket* aPacket_Create(void);
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Create a BrainStem packet, containing the given data.
|
|
|
|
/**
|
|
* Create a BrainStem packet with data.
|
|
*
|
|
* \param address - Module address of the BrainStem module.
|
|
* \param dataLength - The length of the data array.
|
|
* \param data - Pointer to the beginning of the packet data.
|
|
* \return aPacket - Pointer or NULL on error.
|
|
*/
|
|
aLIBEXPORT aPacket* aPacket_CreateWithData(const uint8_t address,
|
|
const uint8_t dataLength,
|
|
const uint8_t* data);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Create a copy of a BrainStem packet.
|
|
|
|
/**
|
|
* Create a copy of a BrainStem packet.
|
|
*
|
|
* \param packet - Packet to be copied
|
|
* \return aPacket - Pointer or NULL on error.
|
|
*/
|
|
aLIBEXPORT aPacket* aPacket_Copy(const aPacket* packet);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Extracts the cmd portion of the packet.
|
|
|
|
/**
|
|
* Create a copy of a BrainStem packet.
|
|
*
|
|
* \param packet - Packet to extract cmd from
|
|
* \param cmd - Value to be filled
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone - If the reset was successful.
|
|
* \retval aErrParam - If the packet is not valid.
|
|
*/
|
|
aLIBEXPORT aErr aPacket_GetCmd(const aPacket* packet, uint8_t* cmd);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Extracts the option portion of the packet.
|
|
|
|
/**
|
|
* Create a copy of a BrainStem packet.
|
|
*
|
|
* \param packet - Packet to extract option from
|
|
* \param option - Value to be filled
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone - If the reset was successful.
|
|
* \retval aErrParam - If the packet is not valid.
|
|
*/
|
|
aLIBEXPORT aErr aPacket_GetOption(const aPacket* packet, uint8_t* option);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Extracts the index portion of the packet.
|
|
|
|
/**
|
|
* Create a copy of a BrainStem packet.
|
|
*
|
|
* \param packet - Packet to extract option from
|
|
* \param index - Value to be filled
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone - If the reset was successful.
|
|
* \retval aErrParam - If the packet is not valid.
|
|
*/
|
|
aLIBEXPORT aErr aPacket_GetIndex(const aPacket* packet, uint8_t* index);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Reset an existing packet.
|
|
|
|
/**
|
|
* Zero out any data the packet contains.
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone - If the reset was successful.
|
|
* \retval aErrParam - If the packet is not valid.
|
|
*/
|
|
aLIBEXPORT aErr aPacket_Reset(aPacket* packet);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Accumulate a Byte into a packet.
|
|
|
|
/**
|
|
* A packet can be constructed byte by byte. the first byte added will
|
|
* be the BrainStem module address, the second byte the data length, and
|
|
* subsequent bytes will be data payload. This call will fail if more than
|
|
* datalength bytes are added, or if address is an invalid module address (i.e. an odd number).
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone - Adding the byte was successful.
|
|
* \retval aErrParam - The packet was invalid.
|
|
* \retval aErrPacket - The byte added violates the BrainStem protocol.
|
|
*/
|
|
aLIBEXPORT aErr aPacket_AddByte(aPacket* packet, const uint8_t byte);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Determine whether a packet is complete.
|
|
|
|
/**
|
|
* A packet can be constructed byte by byte. This call determines whether such a
|
|
* packet has been completed. It checks that dataSize is equal to the currentSize
|
|
* minus the Address and dataSize bytes.
|
|
*
|
|
* \return bool - True if complete false if not complete.
|
|
*/
|
|
aLIBEXPORT bool aPacket_IsComplete(const aPacket* packet);
|
|
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Retrieve a packet as a series of bytes
|
|
|
|
/**
|
|
* A packet can be constructed byte by byte. the first byte added will
|
|
* be the BrainStem module address, the second byte the data length, and
|
|
* subsequent bytes will be data payload.
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone - Adding the byte was successful.
|
|
* \retval aErrParam - The packet was invalid.
|
|
* \retval aErrOverrun - The packet is too large for the buffer.
|
|
*/
|
|
aLIBEXPORT aErr aPacket_GetBytes(const aPacket* packet, uint8_t* pData, const size_t nSize, size_t* bytesOut);
|
|
|
|
/////////////////////////////////////////////////////////////////////
|
|
/// Destroy a BrainStem packet.
|
|
|
|
/**
|
|
* Safely destroy a brainstem packet and deallocate the associated resources.
|
|
*
|
|
* \param packet - A pointer to a pointer of a valid packet. The packet pointer
|
|
* will be set to NULL on successful destruction of the packet.
|
|
*
|
|
* \return Function returns aErr values.
|
|
* \retval aErrNone - The packet was successfully destoryed.
|
|
* \retval aErrParam - The packetRef is invalid.
|
|
*/
|
|
aLIBEXPORT aErr aPacket_Destroy(aPacket** packet);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* _aPacket_H_ */
|