Classes | |
struct | CoapOption |
Sequence of these is returned by CoapPDU::getOptions() More... |
Public Types | |
enum | Type { COAP_CONFIRMABLE = 0x00, COAP_NON_CONFIRMABLE = 0x10, COAP_ACKNOWLEDGEMENT = 0x20, COAP_RESET = 0x30 } |
CoAP message types. Note, values only work as enum. | |
enum | Code { COAP_EMPTY = 0x00, COAP_GET, COAP_POST, COAP_PUT, COAP_DELETE, COAP_CREATED = 0x41, COAP_DELETED, COAP_VALID, COAP_CHANGED, COAP_CONTENT, COAP_BAD_REQUEST = 0x80, COAP_UNAUTHORIZED, COAP_BAD_OPTION, COAP_FORBIDDEN, COAP_NOT_FOUND, COAP_METHOD_NOT_ALLOWED, COAP_NOT_ACCEPTABLE, COAP_PRECONDITION_FAILED = 0x8C, COAP_REQUEST_ENTITY_TOO_LARGE = 0x8D, COAP_UNSUPPORTED_CONTENT_FORMAT = 0x8F, COAP_INTERNAL_SERVER_ERROR = 0xA0, COAP_NOT_IMPLEMENTED, COAP_BAD_GATEWAY, COAP_SERVICE_UNAVAILABLE, COAP_GATEWAY_TIMEOUT, COAP_PROXYING_NOT_SUPPORTED } |
enum | Option { COAP_OPTION_IF_MATCH = 1, COAP_OPTION_URI_HOST = 3, COAP_OPTION_ETAG, COAP_OPTION_IF_NONE_MATCH, COAP_OPTION_OBSERVE, COAP_OPTION_URI_PORT, COAP_OPTION_LOCATION_PATH, COAP_OPTION_URI_PATH = 11, COAP_OPTION_CONTENT_FORMAT, COAP_OPTION_MAX_AGE = 14, COAP_OPTION_URI_QUERY, COAP_OPTION_ACCEPT = 17, COAP_OPTION_LOCATION_QUERY = 20, COAP_OPTION_BLOCK2 = 23, COAP_OPTION_BLOCK1 = 27, COAP_OPTION_SIZE2, COAP_OPTION_PROXY_URI = 35, COAP_OPTION_PROXY_SCHEME = 39, COAP_OPTION_SIZE1 = 60 } |
CoAP option numbers. | |
enum | ContentFormat { COAP_CONTENT_FORMAT_TEXT_PLAIN = 0, COAP_CONTENT_FORMAT_APP_LINK = 40, COAP_CONTENT_FORMAT_APP_XML, COAP_CONTENT_FORMAT_APP_OCTET, COAP_CONTENT_FORMAT_APP_EXI = 47, COAP_CONTENT_FORMAT_APP_JSON = 50 } |
CoAP content-formats. |
Public Member Functions | |
CoapPDU () | |
Memory-managed constructor. Buffer for PDU is dynamically sized and allocated by the object. | |
CoapPDU (uint8_t *pdu, int pduLength) | |
Construct a PDU using an external buffer. No copy of the buffer is made. | |
CoapPDU (uint8_t *buffer, int bufferLength, int pduLength) | |
Construct object from external buffer that may be larger than actual PDU. | |
~CoapPDU () | |
Destructor. Does not free buffer if constructor passed an external buffer. | |
int | reset () |
Reset CoapPDU container so it can be reused to build a new PDU. | |
int | validate () |
Validates a PDU constructed using an external buffer. | |
int | setVersion (uint8_t version) |
Sets the CoAP version. | |
uint8_t | getVersion () |
void | setType (CoapPDU::Type type) |
CoapPDU::Type | getType () |
Returns the type of the PDU. | |
int | setTokenLength (uint8_t tokenLength) |
Set the token length. | |
int | getTokenLength () |
Returns the token length. | |
uint8_t * | getTokenPointer () |
Returns a pointer to the PDU token. | |
int | setToken (uint8_t *token, uint8_t tokenLength) |
Set the PDU token to the supplied byte sequence. | |
void | setCode (CoapPDU::Code code) |
Sets the CoAP response code. | |
CoapPDU::Code | getCode () |
Gets the CoAP response code. | |
int | setMessageID (uint16_t messageID) |
Set messageID to the supplied value. | |
uint16_t | getMessageID () |
Returns the 16 bit message ID of the PDU. | |
int | addOption (uint16_t optionNumber, uint16_t optionLength, uint8_t *optionValue) |
Add an option to the PDU. | |
CoapOption * | getOptions () |
int | getNumOptions () |
Return the number of options that the PDU has. | |
int | setURI (char *uri, int urilen) |
Shorthand function for setting a resource URI. | |
int | getURI (char *dst, int dstlen, int *outLen) |
Concatenates any URI_PATH elements into a single string. | |
int | setContentFormat (CoapPDU::ContentFormat format) |
Shorthand for setting the content-format option. | |
uint8_t * | mallocPayload (int bytes) |
Allocate space for a payload. | |
int | setPayload (uint8_t *value, int len) |
Set the payload to the byte sequence specified. Allocates memory in dynamic PDU if necessary. | |
uint8_t * | getPayloadPointer () |
Returns a pointer to the payload buffer. | |
int | getPayloadLength () |
Gets the length of the payload buffer. | |
uint8_t * | getPayloadCopy () |
Returns a pointer to a buffer which is a copy of the payload buffer (dynamically allocated). | |
int | getPDULength () |
Returns the length of the PDU. | |
uint8_t * | getPDUPointer () |
Returns a pointer to the internal buffer. | |
void | setPDULength (int len) |
Set the PDU length to the length specified. | |
void | print () |
Dumps the PDU as a byte sequence to stdout. | |
void | printBin () |
Dumps the entire PDU in binary. | |
void | printHex () |
Dumps the PDU header in hex. | |
void | printOptionHuman (uint8_t *option) |
A routine for printing an option in human-readable format. | |
void | printHuman () |
Prints the PDU in human-readable format. | |
void | printPDUAsCArray () |
Prints the PDU as a c array (useful for debugging or hardcoding PDUs) |
Static Public Member Functions | |
static void | printBinary (uint8_t b) |
Prints a single byte in binary. |
CoapPDU::CoapPDU | ( | ) |
Memory-managed constructor. Buffer for PDU is dynamically sized and allocated by the object.
When using this constructor, the CoapPDU class will allocate space for the PDU. Contrast this with the parameterized constructors, which allow the use of an external buffer.
Note, the PDU container and space can be reused by issuing a CoapPDU::reset(). If the new PDU exceeds the space of the previously allocated memory, then further memory will be dynamically allocated.
Deleting the object will free the Object container and all dynamically allocated memory.
CoAP version defaults to 1.
CoapPDU::CoapPDU | ( | uint8_t * | pdu, |
int | pduLength | ||
) |
Construct a PDU using an external buffer. No copy of the buffer is made.
This constructor is normally used where a PDU has been received over the network, and it's length is known. In this case the CoapPDU object is probably going to be used as a temporary container to access member values.
It is assumed that pduLength is the length of the actual CoAP PDU, and consequently the buffer will also be this size, contrast this with CoapPDU::CoapPDU(uint8_t *buffer, int bufferLength, int pduLength) which allows the buffer to be larger than the PDU.
A PDU constructed in this manner must be validated with CoapPDU::validate() before the member variables will be accessible.
The buffer can be reused by issuing a CoapPDU::reset() but the class will not change the size of the buffer. If the newly constructed PDU exceeds the size of the buffer, the function called (for example CoapPDU::addOption) will fail.
Deleting this object will only delete the Object container and will not delete the PDU buffer.
pdu | A pointer to an array of bytes which comprise the CoAP PDU |
pduLength | The length of the CoAP PDU pointed to by pdu |
CoapPDU::CoapPDU | ( | uint8_t * | buffer, |
int | bufferLength, | ||
int | pduLength | ||
) |
Construct object from external buffer that may be larger than actual PDU.
This differs from CoapPDU::CoapPDU(uint8_t *pdu, int pduLength) in that the buffer may be larger than the actual CoAP PDU contained int the buffer. This is typically used when a large buffer is reused multiple times. Note that pduLength can be 0.
If an actual CoAP PDU is passed in the buffer, pduLength should match its length. CoapPDU::validate() must be called to initiate the object before member functions can be used.
A PDU constructed in this manner must be validated with CoapPDU::validate() before the member variables will be accessible.
The buffer can be reused by issuing a CoapPDU::reset() but the class will not change the size of the buffer. If the newly constructed PDU exceeds the size of the buffer, the function called (for example CoapPDU::addOption) will fail.
Deleting this object will only delete the Object container and will not delete the PDU buffer.
buffer | A buffer which either contains a CoAP PDU or is intended to be used to construct one. |
bufferLength | The length of the buffer |
pduLength | If the buffer contains a CoAP PDU, this specifies the length of the PDU within the buffer. |
CoapPDU::~CoapPDU | ( | ) |
Destructor. Does not free buffer if constructor passed an external buffer.
The destructor acts differently, depending on how the object was initially constructed (from buffer or not):
Complete object is destroyed.
Only object container is destroyed. \b pdu is left intact.
Only object container is destroyed. \b pdu is left intact.
int CoapPDU::addOption | ( | uint16_t | insertedOptionNumber, |
uint16_t | optionValueLength, | ||
uint8_t * | optionValue | ||
) |
Add an option to the PDU.
Unlike other implementations, options can be added in any order, and in-memory manipulation will be performed to ensure the correct ordering of options (they use a delta encoding of option numbers). Re-ordering memory like this incurs a small performance cost, so if you care about this, then you might want to add options in ascending order of option number.
optionNumber | The number of the option, see the enum CoapPDU::Option for shorthand notations. |
optionLength | The length of the option payload in bytes. |
optionValue | A pointer to the byte sequence that is the option payload (bytes will be copied). |
CoapPDU::CoapOption * CoapPDU::getOptions | ( | ) |
This returns the options as a sequence of structs.
int CoapPDU::getURI | ( | char * | dst, |
int | dstlen, | ||
int * | outLen | ||
) |
Concatenates any URI_PATH elements into a single string.
Parses the PDU options and extracts all URI_PATH elements, concatenating them into a single string with slash separators.
dst | Buffer into which to copy the concatenated path elements. |
dstlen | Length of buffer. |
outLen | Pointer to integer, into which URI length will be placed. |
uint8_t CoapPDU::getVersion | ( | ) |
Gets the CoAP Version.
uint8_t * CoapPDU::mallocPayload | ( | int | len | ) |
Allocate space for a payload.
For dynamically constructed PDUs, this will allocate space for a payload in the object and return a pointer to it. If the PDU was constructed from a buffer, this doesn't malloc anything, it just changes the _pduLength and returns the payload pointer.
len | The length of the payload buffer to allocate. |
void CoapPDU::printOptionHuman | ( | uint8_t * | option | ) |
A routine for printing an option in human-readable format.
option | This is a pointer to where the option begins in the PDU. |
int CoapPDU::reset | ( | ) |
Reset CoapPDU container so it can be reused to build a new PDU.
This resets the CoapPDU container, setting the pdu length, option count, etc back to zero. The PDU can then be populated as if it were newly constructed.
Note that the space available will depend on how the CoapPDU was originally constructed:
Available space initially be \b _pduLength. But further space will be allocated as needed on demand,limited only by the OS/environment.
Space is limited by the variable \b pduLength. The PDU cannot exceed \b pduLength bytes.
Space is limited by the variable \b bufferLength. The PDU cannot exceed \b bufferLength bytes.
int CoapPDU::setContentFormat | ( | CoapPDU::ContentFormat | format | ) |
Shorthand for setting the content-format option.
Sets the content-format to the specified value (adds an option).
format | The content format, one of: |
int CoapPDU::setMessageID | ( | uint16_t | messageID | ) |
Set messageID to the supplied value.
messageID | A 16bit message id. |
int CoapPDU::setPayload | ( | uint8_t * | payload, |
int | len | ||
) |
Set the payload to the byte sequence specified. Allocates memory in dynamic PDU if necessary.
This will set the payload to payload. It will allocate memory in the case where the PDU was constructed without an external buffer.
This will fail either if the fixed buffer isn't big enough, or if memory could not be allocated in the non-external-buffer case.
payload | Pointer to payload byte sequence. |
len | Length of payload byte sequence. |
void CoapPDU::setPDULength | ( | int | len | ) |
Set the PDU length to the length specified.
This is used when re-using a PDU container before calling CoapPDU::validate() as it is not possible to deduce the length of a PDU since the payload has no length marker.
len | The length of the PDU |
int CoapPDU::setToken | ( | uint8_t * | token, |
uint8_t | tokenLength | ||
) |
Set the PDU token to the supplied byte sequence.
This sets the PDU token to token and sets the token length to tokenLength.
token | A sequence of bytes representing the token. |
tokenLength | The length of the byte sequence. |
int CoapPDU::setTokenLength | ( | uint8_t | tokenLength | ) |
Set the token length.
tokenLength | The length of the token in bytes, between 0 and 8. |
void CoapPDU::setType | ( | CoapPDU::Type | mt | ) |
Sets the type of this CoAP PDU.
mt | The type, one of:
|
int CoapPDU::setURI | ( | char * | uri, |
int | urilen | ||
) |
Shorthand function for setting a resource URI.
This will parse the supplied uri and construct enough URI_PATH CoAP options to encode it. The options are added to the PDU.
At present queries are not handled. TODO Implement queries.
uri | The uri to parse. |
urilen | The length of the uri to parse. |
int CoapPDU::setVersion | ( | uint8_t | version | ) |
Sets the CoAP version.
version | CoAP version between 0 and 3. |
int CoapPDU::validate | ( | ) |
Validates a PDU constructed using an external buffer.
When a CoapPDU is constructed using an external buffer, the programmer must call this function to check that the received PDU is a valid CoAP PDU.