Skip to content

Commit

Permalink
Merge pull request #2840 from particle-iot/new-event-api/sc-131168
Browse files Browse the repository at this point in the history 
New cloud event API
  • Loading branch information
@sergeuz
sergeuz authored Jan 10, 2025
2 parents 872bf0a + 3115676 commit 6b1f904
Show file tree
Hide file tree
Showing 65 changed files with 6,041 additions and 667 deletions.
202 changes: 151 additions & 51 deletions communication/inc/coap_api.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,16 @@

#include <stdint.h>

/**
* Maximum supported length of an URI path.
*/
#define COAP_MAX_URI_PATH_LENGTH 127

/**
* Maximum supported size of payload data.
*/
#define COAP_MAX_PAYLOAD_SIZE 16384

/**
* Maximum size of payload data that can be sent or received without splitting the request or
* response message into multiple CoAP messages.
Expand All @@ -44,6 +54,11 @@
*/
typedef struct coap_message coap_message;

/**
* Payload data.
*/
typedef struct coap_payload coap_payload;

/**
* Message option.
*/
Expand All @@ -67,13 +82,13 @@ typedef int (*coap_connection_callback)(int error, int status, void* arg);
* needed.
*
* @param msg Request message.
* @param uri Request URI.
* @param path URI path.
* @param method Method code as defined by the `coap_method` enum.
* @param req_id Request ID.
* @param arg User argument.
* @return 0 on success, otherwise an error code defined by the `system_error_t` enum.
*/
typedef int (*coap_request_callback)(coap_message* msg, const char* uri, int method, int req_id, void* arg);
typedef int (*coap_request_callback)(coap_message* msg, const char* path, int method, int req_id, void* arg);

/**
* Callback invoked when a response message is received.
Expand Down Expand Up @@ -175,7 +190,8 @@ typedef enum coap_option_number {
COAP_OPTION_LOCATION_QUERY = 20, ///< Location-Query.
COAP_OPTION_PROXY_URI = 35, ///< Proxy-Uri.
COAP_OPTION_PROXY_SCHEME = 39, ///< Proxy-Scheme.
COAP_OPTION_SIZE1 = 60 ///< Size1.
COAP_OPTION_SIZE1 = 60, ///< Size1.
COAP_OPTION_NO_RESPONSE = 258 ///< No-Response (RFC 7967).
} coap_option_number;

/**
Expand All @@ -198,11 +214,23 @@ typedef enum coap_connection_status {
COAP_CONNECTION_OPEN = 1 ///< Connection is open.
} coap_connection_status;

/**
* Message option flags.
*/
typedef enum coap_message_flag {
/**
* Store the entire payload data of the message prior to notifying the user that an incoming
* message has been received.
*/
COAP_MESSAGE_FULL = 0x01
} coap_message_flag;

/**
* Result code.
*/
typedef enum coap_result {
COAP_RESULT_WAIT_BLOCK = 1 ///< Waiting for the next block of the message to be sent or received.
COAP_RESULT_WAIT_BLOCK = 1, ///< Waiting for the next block of the message to be sent or received.
COAP_RESULT_CANCELLED = 2 ///< Request was cancelled.
} coap_result;

#ifdef __cplusplus
Expand Down Expand Up @@ -230,40 +258,43 @@ void coap_remove_connection_handler(coap_connection_callback cb, void* reserved)
/**
* Register a handler for incoming requests.
*
* If a handler is already registered for the given combination of URI prefix and method code, it
* If a handler is already registered for the given combination of base URI path and method code, it
* will be replaced.
*
* @param uri URI prefix.
* @param path Base URI path. If `NULL` or empty, the handler will be invoked for any request that
* does not match any of the handlers with a non-empty URI path.
* @param method Method code as defined by the `coap_method` enum.
* @param flags Reserved argument. Must be set to 0.
* @param flags Flags defined by the `coap_message_flag` enum. Supported flags:
* - `COAP_MESSAGE_FULL`.
* @param cb Handler callback.
* @param arg User argument to pass to the callback.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return 0 on success, otherwise an error code defined by the `system_error_t` enum.
*/
int coap_add_request_handler(const char* uri, int method, int flags, coap_request_callback cb, void* arg, void* reserved);
int coap_add_request_handler(const char* path, int method, int flags, coap_request_callback cb, void* arg, void* reserved);

/**
* Unregister a handler for incoming requests.
*
* @param uri URI prefix.
* @param path Base URI path.
* @param method Method code as defined by the `coap_method` enum.
* @param reserved Reserved argument. Must be set to `NULL`.
*/
void coap_remove_request_handler(const char* uri, int method, void* reserved);
void coap_remove_request_handler(const char* path, int method, void* reserved);

/**
* Begin sending a request message.
*
* @param[out] msg Request message.
* @param uri Request URI.
* @param path URI path.
* @param method Method code as defined by the `coap_method` enum.
* @param timeout Request timeout in milliseconds. If 0, the default timeout is used.
* @param flags Reserved argument. Must be set to 0.
* @param flags Flags defined by the `coap_message_flag` enum. Supported flags:
* - `COAP_MESSAGE_FULL`.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return ID of the request on success, otherwise an error code defined by the `system_error_t` enum.
*/
int coap_begin_request(coap_message** msg, const char* uri, int method, int timeout, int flags, void* reserved);
int coap_begin_request(coap_message** msg, const char* path, int method, int timeout, int flags, void* reserved);

/**
* Finish sending a request message.
Expand All @@ -288,7 +319,8 @@ int coap_end_request(coap_message* msg, coap_response_callback resp_cb, coap_ack
* @param[out] msg Response message.
* @param status Response code as defined by the `coap_status` enum.
* @param req_id ID of the request which this response is meant for.
* @param flags Reserved argument. Must be set to 0.
* @param flags Flags defined by the `coap_message_flag` enum. Supported flags:
* - `COAP_MESSAGE_FULL`.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return 0 on success, otherwise an error code defined by the `system_error_t` enum.
*/
Expand Down Expand Up @@ -332,11 +364,12 @@ void coap_destroy_message(coap_message* msg, void* reserved);
*
* @param req_id ID of the request that started the message exchange.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return `COAP_RESULT_CANCELLED` if the request was found and cancelled, otherwise 0.
*/
void coap_cancel_request(int req_id, void* reserved);
int coap_cancel_request(int req_id, void* reserved);

/**
* Write the payload data of a message.
* Write payload data to the current block of a message.
*
* If the data can't be sent in one message block, the function will return `COAP_RESULT_WAIT_BLOCK`.
* When that happens, the caller must stop writing the payload data until the `block_cb` callback is
Expand All @@ -356,11 +389,11 @@ void coap_cancel_request(int req_id, void* reserved);
* @return 0 or `COAP_RESULT_WAIT_BLOCK` on success, otherwise an error code defined by the
* `system_error_t` enum.
*/
int coap_write_payload(coap_message* msg, const char* data, size_t* size, coap_block_callback block_cb,
int coap_write_block(coap_message* msg, const char* data, size_t* size, coap_block_callback block_cb,
coap_error_callback error_cb, void* arg, void* reserved);

/**
* Read the payload data of a message.
* Read payload data from the current block of a message.
*
* If the end of the current message block is reached and more blocks are expected to be received for
* this message, the function will return `COAP_RESULT_WAIT_BLOCK`. The `block_cb` callback will be
Expand All @@ -378,63 +411,141 @@ int coap_write_payload(coap_message* msg, const char* data, size_t* size, coap_b
* @return 0 or `COAP_RESULT_WAIT_BLOCK` on success, otherwise an error code defined by the
* `system_error_t` enum.
*/
int coap_read_payload(coap_message* msg, char* data, size_t *size, coap_block_callback block_cb,
int coap_read_block(coap_message* msg, char* data, size_t* size, coap_block_callback block_cb,
coap_error_callback error_cb, void* arg, void* reserved);

/**
* Read the payload data of the current message block without changing the reading position in it.
* Read payload data from the current block of a message without changing the reading position in it.
*
* @param msg Request or response message.
* @param[out] data Output buffer. Can be `NULL`.
* @param size Number of bytes to read.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return Number of bytes read or an error code defined by the `system_error_t` enum.
*/
int coap_peek_payload(coap_message* msg, char* data, size_t size, void* reserved);
int coap_peek_block(coap_message* msg, char* data, size_t size, void* reserved);

/**
* Get a message option.
* Create a payload instance.
*
* @param[out] opt Message option. If the option with the given number cannot be found, the argument
* is set to `NULL`.
* @param num Option number.
* @param msg Request or response message.
* @param[out] payload Payload instance.
* @param max_heap_size Maximum amount of payload data that can be stored on the heap. The data
* exceeding the specified size will be stored in a temporary file.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return 0 on success, otherwise an error code defined by the `system_error_t` enum.
*/
int coap_get_option(coap_option** opt, int num, coap_message* msg, void* reserved);
int coap_create_payload(coap_payload** payload, size_t max_heap_size, void* reserved);

/**
* Get the next message option.
* Destroy a payload instance.
*
* @param payload Payload instance.
* @param reserved Reserved argument. Must be set to `NULL`.
*/
void coap_destroy_payload(coap_payload* payload, void* reserved);

/**
* Write the payload data.
*
* @param payload Payload instance.
* @param data Input buffer.
* @param size Number of bytes to write.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return On success, the number of bytes written. Otherwise, an error code defined by the
* `system_error_t` enum.
*/
int coap_write_payload(coap_payload* payload, const char* data, size_t size, size_t pos, void* reserved);

/**
* Read the payload data.
*
* @param payload Payload instance.
* @param data Output buffer.
* @param size Number of bytes to read.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return On success, the number of bytes read. Otherwise, an error code defined by the
* `system_error_t` enum.
*/
int coap_read_payload(coap_payload* payload, char* data, size_t size, size_t pos, void* reserved);

/**
* Set the size of the payload data.
*
* @param payload Payload instance.
* @param size New data size.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return 0 on success, otherwise, an error code defined by the `system_error_t` enum.
*/
int coap_set_payload_size(coap_payload* payload, size_t size, void* reserved);

/**
* Get the size of the payload data.
*
* @param payload Payload instance.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return On success, the size of the payload data. Otherwise, an error code defined by the
* `system_error_t` enum.
*/
int coap_get_payload_size(coap_payload* payload, void* reserved);

/**
* Set the payload data of a message.
*
* The caller is still responsible for destroying its reference to the payload instance via
* `coap_destroy_payload()` after calling this function.
*
* @param msg Request or response message.
* @param payload Payload data instance.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return 0 on success, otherwise, an error code defined by the `system_error_t` enum.
*/
int coap_set_payload(coap_message* msg, coap_payload* payload, void* reserved);

/**
* Get the payload data of a message.
*
* The obtained reference to the payload instance needs to be destroyed via `coap_destroy_payload()`
* when it's no longer needed.
*
* @param msg Request or response message.
* @param[out] payload Payload data instance.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return 0 on success, otherwise, an error code defined by the `system_error_t` enum.
*/
int coap_get_payload(coap_message* msg, coap_payload** payload, void* reserved);

/**
* Get the first message option with a given number.
*
* @param[in,out] opt **in:** Current option. If `NULL`, the first option of the message is returned.
* **out:** Next option. If `NULL`, the option provided is the last option of the message.
* @param[out] num Option number.
* @param msg Request or response message.
* @param[out] opt Message option. If the option cannot be found, the argument is set to `NULL`.
* @param num Option number.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return 0 on success, otherwise an error code defined by the `system_error_t` enum.
*/
int coap_get_next_option(coap_option** opt, int* num, coap_message* msg, void* reserved);
int coap_get_option(coap_message* msg, coap_option** opt, int num, void* reserved);

/**
* Get the value of an `uint` option.
* Get the next message option.
*
* @param opt Message option.
* @param[out] val Option value.
* @param msg Request or response message.
* @param[in,out] opt **in:** Current option. If `NULL`, the first option of the message is returned.
* **out:** Next option. If `NULL`, the option provided is the last option of the message.
* @param[out] num Option number.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return 0 on success, otherwise an error code defined by the `system_error_t` enum.
*/
int coap_get_uint_option_value(const coap_option* opt, unsigned* val, void* reserved);
int coap_get_next_option(coap_message* msg, coap_option** opt, int* num, void* reserved);

/**
* Get the value of an `uint` option as a 64-bit integer.
* Get the value of a `uint` option.
*
* @param opt Message option.
* @param[out] val Option value.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return 0 on success, otherwise an error code defined by the `system_error_t` enum.
*/
int coap_get_uint64_option_value(const coap_option* opt, uint64_t* val, void* reserved);
int coap_get_uint_option_value(coap_option* opt, unsigned* val, void* reserved);

/**
* Get the value of a string option.
Expand All @@ -448,7 +559,7 @@ int coap_get_uint64_option_value(const coap_option* opt, uint64_t* val, void* re
* @return On success, the actual size of the option value not including the terminating null (can
* be greater than `size`). Otherwise, an error code defined by the `system_error_t` enum.
*/
int coap_get_string_option_value(const coap_option* opt, char* data, size_t size, void* reserved);
int coap_get_string_option_value(coap_option* opt, char* data, size_t size, void* reserved);

/**
* Get the value of an opaque option.
Expand All @@ -460,7 +571,7 @@ int coap_get_string_option_value(const coap_option* opt, char* data, size_t size
* @return On success, the actual size of the option value (can be greater than `size`). Otherwise,
* an error code defined by the `system_error_t` enum.
*/
int coap_get_opaque_option_value(const coap_option* opt, char* data, size_t size, void* reserved);
int coap_get_opaque_option_value(coap_option* opt, char* data, size_t size, void* reserved);

/**
* Add an empty option to a message.
Expand All @@ -483,17 +594,6 @@ int coap_add_empty_option(coap_message* msg, int num, void* reserved);
*/
int coap_add_uint_option(coap_message* msg, int num, unsigned val, void* reserved);

/**
* Add a `uint` option to a message as a 64-bit integer.
*
* @param msg Request of response message.
* @param num Option number.
* @param val Option value.
* @param reserved Reserved argument. Must be set to `NULL`.
* @return 0 on success, otherwise an error code defined by the `system_error_t` enum.
*/
int coap_add_uint64_option(coap_message* msg, int num, uint64_t val, void* reserved);

/**
* Add a string option to a message.
*
Expand Down
9 changes: 8 additions & 1 deletion communication/inc/coap_defs.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,11 @@ const size_t MIN_COAP_MESSAGE_SIZE = 4;

const size_t MAX_COAP_TOKEN_SIZE = 8;

const size_t MAX_COAP_ETAG_OPTION_SIZE = 8;
const size_t MAX_COAP_REQUEST_TAG_OPTION_SIZE = 8;

const unsigned MAX_COAP_OPTION_NUMBER = 65535;

constexpr unsigned coapCode(unsigned cls, unsigned detail) {
return ((cls & 0x07) << 5) | (detail & 0x1f);
}
Expand Down Expand Up @@ -101,6 +106,8 @@ enum class CoapOption {
BLOCK2 = 23,
BLOCK1 = 27,
SIZE2 = 28,
// RFC 7967
NO_RESPONSE = 258,
// RFC 9175, 3.2. The Request-Tag Option
REQUEST_TAG = 292
};
Expand All @@ -120,7 +127,7 @@ enum class CoapContentFormat {
IMAGE_PNG = 23,
APPLICATION_CBOR = 60,
// Vendor-specific formats
PARTICLE_JSON_AS_CBOR = 65001 // application/vnd.particle.json+cbor
PARTICLE_STRUCTURED = 65001 // application/vnd.particle.json+cbor
};

PARTICLE_DEFINE_ENUM_COMPARISON_OPERATORS(CoapContentFormat)
Expand Down
Loading

0 comments on commit 6b1f904

Please sign in to comment.