COAP protocol libcoap API

Coap（Constrained Application Protocol） It's a class in the Internet of things world web agreement , Its detailed specification is defined in RFC 7252.Coap The full English name is Constrained Application Protocol, Means restricted application protocol , seeing the name of a thing one thinks of its function , Use on resource constrained IOT devices . Internet of things devices ram,rom They are usually very small , function TCP and HTTP It's not acceptable .coap The application in the Internet of things is mainly used for device discovery .

libcoap Yes, it is C A set of language implementation CoAP agreement , In this paper, libcoap Relevant interfaces and important structures of .

Important definitions and data structures

coap Address information

Used to identify local and remote address information , Its definition is as follows ：

typedef struct coap_address_t 
{
    uint16_t     port;
    ip_addr_t    addr;
} coap_address_t;

Key members	explain
port	Connection address and port number
addr	Connection address ip Information

API list

Interface	explain
coap_startup	coap Function module initialization , Include clock 、 Random number, etc
coap_cleanup	coap sign out
coap_new_context	establish coap Context
coap_free_context	Delete context
coap_context_set_keepalive	Set the keep alive time
coap_new_optlist	establish opt Structure
coap_insert_optlist	take opt Insert the list
coap_delete_optlist	Delete opt Linked list
coap_new_client_session	establish session
coap_session_release	Delete session
coap_register_option	register opt type
coap_register_response_handler	Register message callback function
coap_response_handler_t	Message callback function
coap_register_event_handler	Register event callback function
coap_event_handler_t	Event callback function
coap_register_nack_handler	Registration did not receive expectations ACK Callback function for
coap_nack_handler_t	nack Callback function
coap_new_message_id	Get new messages ID
coap_new_pdu	establish PDU Structure
coap_add_optlist_pdu	take opt Add linked list to PDU
coap_add_data	add to data Data to PDU
coap_add_block	add to block Data to PDU
coap_send	send out PDU news
coap_run_once	Main message processing loop , Handle message retransmission 、 Message receiving and distribution, etc
coap_can_exit	Judge coap Is there a message waiting to be sent or distributed
coap_split_uri	Extract from string URI Information , Include host 、 port 、 route 、 Request parameters, etc
coap_split_query	Extract from string query Information

coap_startup

The function of coap Initialization interface of function module , For initialization coap The clock that the protocol needs to use 、 Random number, etc , The function prototype is as follows ：

void coap_startup(void);

Parameters	explain
nothing	nothing
return	explain
nothing	nothing

coap_cleanup

The function of coap Deinitialization interface of function module , The function prototype is as follows ：

void coap_cleanup(void);

Parameters	explain
nothing	nothing
return	explain
nothing	nothing

coap_new_context

This function creates coap Function module context , Used to save the protocol stack status information , The function prototype is as follows ：

coap_context_t *coap_new_context(const coap_address_t *listen_addr);

Parameters	explain
listen_addr	Monitor address , Used as a client When you enter here NULL
return	explain
NULL	Create failure
Not NULL	Create success , Returns the context structure pointer

coap_free_context

This function releases coap Context resources , The function prototype is as follows ：

void coap_free_context(coap_context_t *context);

Parameters	explain
context	Need to be released coap Context pointer
return	explain
nothing	nothing

coap_context_set_keepalive

This function is used to set the context keep alive period , The function prototype is as follows ：

void coap_context_set_keepalive(coap_context_t *context, unsigned int seconds);

Parameters	explain
context	Need to be released coap Context pointer
seconds	Keep alive period
return	explain
nothing	nothing

coap_new_optlist

This function is used to create opt Structure , The function prototype is as follows ：

coap_optlist_t *coap_new_optlist(uint16_t      number,
                                 size_t        length,
                                 const uint8_t *data);

Parameters	explain
number	opt type , from COAP_OPTION_XXX Definition
length	opt Data length
data	opt data
return	explain
NULL	Create failure
Not NULL	Create success , return opt Structure pointer

coap_insert_optlist

This function is used to opt Structure insert linked list , The function prototype is as follows ：

int coap_insert_optlist(coap_optlist_t  **optlist_chain,
                        coap_optlist_t   *optlist);

Parameters	explain
optlist_chain	Linked list for inserting data
optlist	opt Structure pointer
return	explain
0	Insert the failure
1	Insert the success

coap_delete_optlist

This function is used to delete opt Linked list , Release the memory resources of the linked list , The function prototype is as follows ：

void coap_delete_optlist(coap_optlist_t *optlist_chain);

Parameters	explain
optlist_chain	opt Linked list
return	explain
nothing	nothing

coap_new_client_session

This function is used to create a client connected to the specified server address session, The function prototype is as follows ：

coap_session_t *coap_new_client_session(struct coap_context_t  *ctx,
                                        const coap_address_t   *local_if,
                                        const coap_address_t   *server,
                                        coap_proto_t            proto);

Parameters	explain
ctx	coap Context
local_if	Specify the local network interface used for network connection
server	Server address and port information
proto	Specify connection protocol , from COAP_PROTO_XXX Macro definition
return	explain
NULL	Create failure
Not NULL	Create success , return session Structure pointer

coap_session_release

This function is used to release session resources , The function prototype is as follows ：

void coap_session_release(coap_session_t *session);

Parameters	explain
session	Need to be released session
return	explain
nothing	nothing

coap_register_option

This function is used to send a message to ctx register opt, The function prototype is as follows ：

void coap_register_option(coap_context_t *ctx, uint16_t type);

Parameters	explain
ctx	coap Context
type	opt type
return	explain
nothing	nothing

coap_register_response_handler

This function is used to register the callback function of the reply message , The function prototype is as follows ：

void coap_register_response_handler(coap_context_t           *context,
                                    coap_response_handler_t   handler);

Parameters	explain
context	coap Context
handler	Callback function
return	explain
nothing	nothing

coap_response_handler_t

coap Callback function of reply message , The function prototype is as follows ：

typedef void (*coap_response_handler_t)(struct coap_context_t *context,
                                        coap_session_t        *session,
                                        coap_pdu_t            *sent,
                                        coap_pdu_t            *received,
                                        const coap_tid_t       id);

Parameters	explain
context	coap Context
session	Identify connected session
sent	The transmission of data pdu
received	The received pdu
id	news id
return	explain
nothing	nothing

coap_register_event_handler

This function is used to register the callback function of the event , The function prototype is as follows ：

void coap_register_event_handler(struct coap_context_t  *context,
                                 coap_event_handler_t    hnd);

Parameters	explain
context	coap Context
hnd	Callback function , Event macro definitions ：COAP_EVENT_XXX
return	explain
nothing	nothing

coap_event_handler_t

typedef int (*coap_event_handler_t)(struct coap_context_t  *context,
                                    coap_event_t            event,
                                    struct coap_session_t  *session);

Event callback function , The function prototype is as follows ：

Parameters	explain
context	coap Context
event	Event type , Reference resources COAP_EVENT_XXX Macro definition
session	Identify connected session
return	explain
Not 0	Processing failed
0	Handle a successful

coap_register_nack_handler

This function is used to register that a timeout has not been received ack Callback function for , The function prototype is as follows ：

void coap_register_nack_handler(coap_context_t       *context,
                                coap_nack_handler_t   handler);

Parameters	explain
context	coap Context
handler	Callback function
return	explain
nothing	nothing

coap_nack_handler_t

nack Callback function , The function prototype is as follows ：

typedef void (*coap_nack_handler_t)(struct coap_context_t *context,
                                    coap_session_t        *session,
                                    coap_pdu_t            *sent,
                                    coap_nack_reason_t     reason,
                                    const coap_tid_t       id);

Parameters	explain
context	coap Context
session	Identify connected session
sent	The transmission of data pdu
reason	nack Detailed reasons , See coap_nack_reason_t Definition
id	news id
return	explain
nothing	nothing

coap_new_message_id

This function is used to create a new message ID, The function prototype is as follows ：

uint16_t coap_new_message_id(coap_session_t *session);

Parameters	explain
session	Identify the connection information session
return	explain
Not NULL	news ID

coap_new_pdu

This function is used to create a new communication pdu, The function prototype is as follows ：

coap_pdu_t *coap_new_pdu(const struct coap_session_t *session);

Parameters	explain
session	Identify the connection information session
return	explain
NULL	Create failure
Not NULL	Create success , return pdu Structure pointer

coap_add_optlist_pdu

This function is used to add opt Linked list to pdu, The function prototype is as follows ：

int coap_add_optlist_pdu(coap_pdu_t *pdu, coap_optlist_t **optlist_chain);

Parameters	explain
pdu	Identify the communication pdu
optlist_chain	opt Linked list
return	explain
0	Add failure
1	Add success

coap_add_data

This function is used to send a message to pdu add to data data , The function prototype is as follows ：

int coap_add_data(coap_pdu_t *pdu, size_t len, const uint8_t *data);

Parameters	explain
pdu	Identify the communication pdu
len	data length
data	data data
return	explain
0	Add failure
1	Add success

coap_add_block

This function is used to send a message to pdu add to block data , The function prototype is as follows ：

int coap_add_block(coap_pdu_t       *pdu, 
                   unsigned int      len,  
                   const uint8_t    *data,
                   unsigned int      block_num, 
                   unsigned char     block_szx);

Parameters	explain
pdu	Identify the communication pdu
len	data length
data	fill block Of data data
block_num	block Number
block_szx	block size
return	explain
0	Add failure
1	Add success

coap_send

This function is used to send coap data , The function prototype is as follows ：

coap_tid_t coap_send(coap_session_t *session, coap_pdu_t *pdu);

Parameters	explain
session	Identify the connection information session
pdu	Identify the communication pdu
return	explain
-1	fail in send
Not -1	Send successfully , Return message ID

coap_run_once

This function is used for the main message processing loop , Handle message retransmission 、 Message receiving and distribution, etc , The function prototype is as follows ：

int coap_run_once(coap_context_t *ctx, unsigned int timeout_ms);

Parameters	explain
ctx	coap Context
timeout_ms	Timeout time , Company ：ms
return	explain
-1	Processing failed
Not -1	Send successfully , Return message ID

coap_can_exit

This function is used to determine whether there is a message waiting to be sent or distributed , The function prototype is as follows ：

int coap_can_exit(coap_context_t *context);

Parameters	explain
context	coap Context
return	explain
1	No waiting messages
0	There are waiting messages

coap_split_uri

This function is used to parse... From a string URI Information , The function prototype is as follows ：

int coap_split_uri(const uint8_t *str_var, size_t len, coap_uri_t *uri);

Parameters	explain
str_var	contain URI String of information
len	String length
uri	Used to hold URI Structure pointer of information
return	explain
<0	Parse failure
0	Parsing succeeded

coap_split_query

This function is used to parse... From a string query Information , Generate criteria query structure , The function prototype is as follows ：

int coap_split_query(const uint8_t   *s, 
                     size_t           length,
                     unsigned char   *buf, 
                     size_t          *buflen);

Parameters	explain
s	contain query String of information
length	String length
buf	Preservation criteria query Structural buf
buflen	buf Maximum length , When the execution is successful, it is modified to the actual write buf Data length
return	explain
<0	Parse failure
0	query Number

Examples of use