Минимальная реализация основных функций поддержки протокола CoAP

Несмотря на то, что CoAP позиционируется как "облегченный" протокол для приложений с ограниченными ресурсами, он достаточно сложен, и его полноценная реализация была бы избыточна для задач простой телеметрии. Данный модуль предоставляет базовые функции для формирования и разбора сообщений CoAP. Подробнее...

Группы
	Определения констант для индентификаторов класса, версии и типа сообщений
	Определения методов для запросов CoAP
	Определения, относящеся к полям заголовков и опций CoAP

Структуры данных
struct	CoAP_header_info_t
struct	CoAP_option_info_t

Макросы
#define	MAX_PARSED_OPTIONS   10
	Максимальное количество опций, которое будет анализироваться при разборе сообщения
#define	MAX_URI_ENTRIES   10
	Максимально допустимое количество сегментов в URI.
#define	MAX_URI_LENGTH   128
	Предельная длина URI.
#define	CoAP_assemble_request(request_method, buffer, buffer_length, url_string, data, data_length)   CoAP_assemble_request_extended(request_method,0,buffer,buffer_length,url_string,data,data_length)
	Препроцессорная замена для обеспечения совместимости с кодом, использующим старую версию функции, а также для случаев, когда параметр OBSERVE не требуется и может быть установлен по-умолчанию.

Перечисления
enum	CoAP_parsing_error_t {   ERR_WRONG_PROTOCOL_VER, ERR_UNKNOWN_MSG_TYPE, ERR_WRONG_TKL, ERR_WRONG_OPTION,   ERR_TOO_MUCH_OPTIONS, ERR_NONE }

Функции
void	CoAP_parse_message_header (uint8_t *hdr, CoAP_header_info_t *out)
	Выполняет разбор заголовка CoAP-сообщения с извлечением информации в структуру типа CoAP_header_info_t. Подробнее...
CoAP_parsing_error_t	CoAP_parse_message (uint8_t *buf, uint16_t buf_length, uint8_t **data_start)
	Выполняет поиск данных в пакете CoAP. Подробнее...
uint16_t	CoAP_assemble_request_extended (uint8_t request_method, uint8_t is_observe_request, uint8_t *msg_buffer, uint16_t buffer_length, uint8_t *url_string, uint8_t *data, uint16_t data_length)
	Формирует CoAP-сообщение с запросом к серверу Подробнее...
#define	NULL   ((void *)0)
#define	COAP_MSG_VERSION   0x01
#define	COAP_TYPE_CONFIRMABLE   0x00
#define	COAP_TYPE_NON_CONFIRMABLE   0x01
#define	COAP_TYPE_ACK   0x02
#define	COAP_TYPE_RESET   0x03
#define	COAP_CLASS_REQUEST   0
#define	COAP_CLASS_RESP_SUCCESS   2
#define	COAP_CLASS_CLIENT_ERROR   4
#define	COAP_CLASS_SERVER_ERROR   5

Подробное описание

Несмотря на то, что CoAP позиционируется как "облегченный" протокол для приложений с ограниченными ресурсами, он достаточно сложен, и его полноценная реализация была бы избыточна для задач простой телеметрии. Данный модуль предоставляет базовые функции для формирования и разбора сообщений CoAP.

Перечисления

CoAP_parsing_error_t

enum CoAP_parsing_error_t

Элементы перечислений
ERR_WRONG_PROTOCOL_VER	Неверное значение версии протокола в заголовке; вероятно, сообщение повреждено
ERR_UNKNOWN_MSG_TYPE	Неверное значение типа сообщения в заголовке; вероятно, сообщение повреждено
ERR_WRONG_TKL	Недопустимая длина идентификатора запроса
ERR_WRONG_OPTION	Ошибка в формате опциии
ERR_TOO_MUCH_OPTIONS	Количество опций в заголовке превышает предел
ERR_NONE	Ошибок не произошло

См. определение в файле coap_essentials.h строка 130

Функции

CoAP_assemble_request_extended()

uint16_t CoAP_assemble_request_extended	(	uint8_t	request_method,
		uint8_t	is_observe_request,
		uint8_t *	msg_buffer,
		uint16_t	buffer_length,
		uint8_t *	url_string,
		uint8_t *	data,
		uint16_t	data_length
	)

Формирует CoAP-сообщение с запросом к серверу

Аргументы

[in]	request_method	Метод запроса; см. Определения методов для запросов CoAP
[in]	is_observe_request	Если этот параметр имеет ненулевое значение, в сообщение будет добавлен заголовок OBSERVE

Заметки

В текущей ревизии стандарта CoAP OBSERVE имеет смысл только в сочетании с методом GET. Если request_method не равен COAP_METHOD_GET, значение is_observe_request игнорируется.

Аргументы

[in]	msg_buffer	Буфер, в который будет записано сформированное сообщение
[in]	buffer_length	Доступная длина буфера
[in]	url_string	Строка URL, по которому должен быть выполнен запрос

Предупреждения

- Строка URL должна начинаться с '/', например /test/telemetry

- Строка URL не должна включать IP

Аргументы

[in]	data	Полезная нагрузка запроса
[in]	data_length	Длина полезной нагрузки

Возвращает

Фактическая длина сформированного сообщения (<= buffer_length). В случае ошибки - ноль.

См. определение в файле coap_essentials.c строка 174

CoAP_parse_message()

CoAP_parsing_error_t CoAP_parse_message	(	uint8_t *	buf,
		uint16_t	buf_length,
		uint8_t **	data_start
	)

Выполняет поиск данных в пакете CoAP.

Заголовок CoAP имеет динамический размер за счет полей опций и динамической длины идентификатора запроса (token). CoAP_parse_message() пропускает все служебные поля и возвращает указатель на позицию в пакете, с которой начинаются полезные данные (если они есть).

Служебная информация CoAP не содержит поля с информацией о длине полезных данных; согласно стандарту, она должна вычисляться как разница между длиной заголовка и длиной пакета UDP.

Аргументы

[in]	buf	Массив, содержащий сообщение CoAP
[in]	buf_length	Длина входного массива
[out]	data_start	Указатель на переменную-указатель, в которую будет помещена позиция, с которой начинаются данные.

Предупреждения

data_start является указателем на указатель. Это необходимо потому, что функция модифицирует это значение для передачи его в вызывающий код. Типичный метод использования выглядит следующим образом:

uint8_t *payload_start;
 
...
 
CoAP_parse_message(buffer,buffer_length,&payload_start);

Возвращает

Результат разбора, определенный в CoAP_parsing_error_t

См. определение в файле coap_essentials.c строка 99

CoAP_parse_message_header()

void CoAP_parse_message_header	(	uint8_t *	hdr,
		CoAP_header_info_t *	out
	)

Выполняет разбор заголовка CoAP-сообщения с извлечением информации в структуру типа CoAP_header_info_t.

Аргументы

[in]	hdr	Массив, в котором содержится CoAP-сообщение
[out]	out	Указатель на структуру, в которую будет скопирована информация из заголовка

См. определение в файле coap_essentials.c строка 12