coap_client.h
Go to the documentation of this file.
1 /**
2  * @file coap_client.h
3  * @brief CoAP client
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2019 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneTCP Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 1.9.6
29  **/
30 
31 #ifndef _COAP_CLIENT_H
32 #define _COAP_CLIENT_H
33 
34 //Dependencies
35 #include "core/net.h"
36 #include "coap/coap_common.h"
37 #include "coap/coap_message.h"
38 #include "coap/coap_option.h"
39 
40 //CoAP client support
41 #ifndef COAP_CLIENT_SUPPORT
42  #define COAP_CLIENT_SUPPORT ENABLED
43 #elif (COAP_CLIENT_SUPPORT != ENABLED && COAP_CLIENT_SUPPORT != DISABLED)
44  #error COAP_CLIENT_SUPPORT parameter is not valid
45 #endif
46 
47 //DTLS-secured CoAP support
48 #ifndef COAP_CLIENT_DTLS_SUPPORT
49  #define COAP_CLIENT_DTLS_SUPPORT DISABLED
50 #elif (COAP_CLIENT_DTLS_SUPPORT != ENABLED && COAP_CLIENT_DTLS_SUPPORT != DISABLED)
51  #error COAP_CLIENT_DTLS_SUPPORT parameter is not valid
52 #endif
53 
54 //CoAP observe support
55 #ifndef COAP_CLIENT_OBSERVE_SUPPORT
56  #define COAP_CLIENT_OBSERVE_SUPPORT ENABLED
57 #elif (COAP_CLIENT_OBSERVE_SUPPORT != ENABLED && COAP_CLIENT_OBSERVE_SUPPORT != DISABLED)
58  #error COAP_CLIENT_OBSERVE_SUPPORT parameter is not valid
59 #endif
60 
61 //CoAP block-wise transfer support
62 #ifndef COAP_CLIENT_BLOCK_SUPPORT
63  #define COAP_CLIENT_BLOCK_SUPPORT ENABLED
64 #elif (COAP_CLIENT_BLOCK_SUPPORT != ENABLED && COAP_CLIENT_BLOCK_SUPPORT != DISABLED)
65  #error COAP_CLIENT_BLOCK_SUPPORT parameter is not valid
66 #endif
67 
68 //CoAP client tick interval
69 #ifndef COAP_CLIENT_TICK_INTERVAL
70  #define COAP_CLIENT_TICK_INTERVAL 100
71 #elif (COAP_CLIENT_TICK_INTERVAL < 10)
72  #error COAP_CLIENT_TICK_INTERVAL parameter is not valid
73 #endif
74 
75 //Default timeout
76 #ifndef COAP_CLIENT_DEFAULT_TIMEOUT
77  #define COAP_CLIENT_DEFAULT_TIMEOUT 20000
78 #elif (COAP_CLIENT_DEFAULT_TIMEOUT < 0)
79  #error COAP_CLIENT_DEFAULT_TIMEOUT parameter is not valid
80 #endif
81 
82 //Maximum number of simultaneous outstanding requests
83 #ifndef COAP_CLIENT_NSTART
84  #define COAP_CLIENT_NSTART 1
85 #elif (COAP_CLIENT_NSTART < 1)
86  #error COAP_CLIENT_NSTART parameter is not valid
87 #endif
88 
89 //Maximum number of retransmissions
90 #ifndef COAP_CLIENT_MAX_RETRANSMIT
91  #define COAP_CLIENT_MAX_RETRANSMIT 4
92 #elif (COAP_CLIENT_MAX_RETRANSMIT < 1)
93  #error COAP_CLIENT_MAX_RETRANSMIT parameter is not valid
94 #endif
95 
96 //Initial retransmission timeout (minimum)
97 #ifndef COAP_CLIENT_ACK_TIMEOUT_MIN
98  #define COAP_CLIENT_ACK_TIMEOUT_MIN 2000
99 #elif (COAP_CLIENT_ACK_TIMEOUT_MIN < 1000)
100  #error COAP_CLIENT_ACK_TIMEOUT_MIN parameter is not valid
101 #endif
102 
103 //Initial retransmission timeout (maximum)
104 #ifndef COAP_CLIENT_ACK_TIMEOUT_MAX
105  #define COAP_CLIENT_ACK_TIMEOUT_MAX 3000
106 #elif (COAP_CLIENT_ACK_TIMEOUT_MAX < COAP_CLIENT_ACK_TIMEOUT_MIN)
107  #error COAP_CLIENT_ACK_TIMEOUT_MAX parameter is not valid
108 #endif
109 
110 //Random delay after Max-Age has expired (minimum)
111 #ifndef COAP_CLIENT_RAND_DELAY_MIN
112  #define COAP_CLIENT_RAND_DELAY_MIN 5000
113 #elif (COAP_CLIENT_RAND_DELAY_MIN < 1000)
114  #error COAP_CLIENT_RAND_DELAY_MIN parameter is not valid
115 #endif
116 
117 //Random delay after Max-Age has expired (maximum)
118 #ifndef COAP_CLIENT_RAND_DELAY_MAX
119  #define COAP_CLIENT_RAND_DELAY_MAX 15000
120 #elif (COAP_CLIENT_RAND_DELAY_MAX < COAP_CLIENT_RAND_DELAY_MIN)
121  #error COAP_CLIENT_RAND_DELAY_MAX parameter is not valid
122 #endif
123 
124 //Default token length
125 #ifndef COAP_CLIENT_DEFAULT_TOKEN_LEN
126  #define COAP_CLIENT_DEFAULT_TOKEN_LEN 4
127 #elif (COAP_CLIENT_DEFAULT_TOKEN_LEN < 0 || COAP_CLIENT_DEFAULT_TOKEN_LEN > 8)
128  #error COAP_CLIENT_DEFAULT_TOKEN_LEN parameter is not valid
129 #endif
130 
131 //DTLS supported?
132 #if (COAP_CLIENT_DTLS_SUPPORT == ENABLED)
133  #include "core/crypto.h"
134  #include "tls.h"
135 #endif
136 
137 //Forward declaration of CoapClientContext structure
138 struct _CoapClientContext;
139 #define CoapClientContext struct _CoapClientContext
140 
141 //Forward declaration of CoapClientRequest structure
142 struct _CoapClientRequest;
143 #define CoapClientRequest struct _CoapClientRequest
144 
145 //Dependencies
146 #include "coap_client_request.h"
147 
148 //C++ guard
149 #ifdef __cplusplus
150 extern "C" {
151 #endif
152 
153 
154 /**
155  * @brief CoAP client states
156  */
157 
158 typedef enum
159 {
164 
165 
166 //DTLS supported?
167 #if (COAP_CLIENT_DTLS_SUPPORT == ENABLED)
168 
169 /**
170  * @brief DTLS initialization callback
171  **/
172 
174  TlsContext *dtlsContext);
175 
176 #endif
177 
178 
179 /**
180  * @brief CoAP client context
181  **/
182 
184 {
185  OsMutex mutex; ///<Mutex preventing simultaneous access to the context
186  OsEvent event; ///<Event object used to receive notifications
187  CoapClientState state; ///<CoAP client state
188  CoapTransportProtocol transportProtocol; ///<Transport protocol (UDP or DTLS)
189  NetInterface *interface; ///<Underlying network interface
190  Socket *socket; ///<Underlying UDP socket
191 #if (COAP_CLIENT_DTLS_SUPPORT == ENABLED)
192  TlsContext *dtlsContext; ///<DTLS context
193  TlsSessionState dtlsSession; ///<DTLS session state
194  CoapClientDtlsInitCallback dtlsInitCallback; ///<DTLS initialization callback
195 #endif
196  systime_t startTime; ///<Start time
197  systime_t timeout; ///<Timeout value
198  uint16_t mid; ///<Message identifier
199  size_t tokenLen; ///<Token length
200  CoapClientRequest request[COAP_CLIENT_NSTART]; ///<Outstanding CoAP requests
201  CoapMessage response; ///<CoAP response message
202 };
203 
204 
205 //CoAP client related functions
207 
209  CoapTransportProtocol transportProtocol);
210 
211 #if (COAP_CLIENT_DTLS_SUPPORT == ENABLED)
212 
214  CoapClientDtlsInitCallback callback);
215 
216 #endif
217 
220 
222  NetInterface *interface);
223 
225  const IpAddr *serverIpAddr, uint16_t serverPort);
226 
228 
230 
231 void coapClientDeinit(CoapClientContext *context);
232 
233 //C++ guard
234 #ifdef __cplusplus
235 }
236 #endif
237 
238 #endif
error_t coapClientBindToInterface(CoapClientContext *context, NetInterface *interface)
Bind the CoAP client to a particular network interface.
Definition: coap_client.c:240
CoapClientState
CoAP client states.
Definition: coap_client.h:158
CoAP request handling.
uint8_t length
Definition: dtls_misc.h:149
IP network address.
Definition: ip.h:71
CoapClientState state
CoAP client state.
Definition: coap_client.h:187
CoapClientDtlsInitCallback dtlsInitCallback
DTLS initialization callback.
Definition: coap_client.h:194
Event object.
TlsContext * dtlsContext
DTLS context.
Definition: coap_client.h:192
error_t coapClientSetTokenLength(CoapClientContext *context, size_t length)
Set the length of the token.
Definition: coap_client.c:211
systime_t timeout
Timeout value.
Definition: coap_client.h:197
#define CoapClientContext
Definition: coap_client.h:139
CoapClientRequest request[COAP_CLIENT_NSTART]
Outstanding CoAP requests.
Definition: coap_client.h:200
#define COAP_CLIENT_NSTART
Definition: coap_client.h:84
#define CoapClientRequest
Definition: coap_client.h:143
CoAP message formatting and parsing.
CoapTransportProtocol
CoAP transport protocols.
Definition: coap_common.h:82
error_t coapClientRegisterDtlsInitCallback(CoapClientContext *context, CoapClientDtlsInitCallback callback)
Register DTLS initialization callback function.
Definition: coap_client.c:158
error_t coapClientTask(CoapClientContext *context, systime_t timeout)
Process CoAP client events.
Definition: coap_client.c:373
OsMutex mutex
Mutex preventing simultaneous access to the context.
Definition: coap_client.h:185
#define TlsContext
Definition: tls.h:36
error_t
Error codes.
Definition: error.h:42
error_t(* CoapClientDtlsInitCallback)(CoapClientContext *context, TlsContext *dtlsContext)
DTLS initialization callback.
Definition: coap_client.h:173
@ COAP_CLIENT_STATE_DISCONNECTED
Definition: coap_client.h:160
CoAP message.
Definition: coap_message.h:55
#define NetInterface
Definition: net.h:36
General definitions for cryptographic algorithms.
error_t coapClientDisconnect(CoapClientContext *context)
Disconnect from the CoAP server.
Definition: coap_client.c:399
void coapClientDeinit(CoapClientContext *context)
Release CoAP client context.
Definition: coap_client.c:438
CoAP client context.
Definition: coap_client.h:183
error_t coapClientSetTransportProtocol(CoapClientContext *context, CoapTransportProtocol transportProtocol)
Set the transport protocol to be used.
Definition: coap_client.c:130
NetInterface * interface
Underlying network interface.
Definition: coap_client.h:189
CoapClientContext * context
CoAP client context.
error_t coapClientSetTimeout(CoapClientContext *context, systime_t timeout)
Set default request timeout.
Definition: coap_client.c:186
Mutex object.
uint16_t mid
Message identifier.
Definition: coap_client.h:198
CoapTransportProtocol transportProtocol
Transport protocol (UDP or DTLS)
Definition: coap_client.h:188
OsEvent event
Event object used to receive notifications.
Definition: coap_client.h:186
TLS session state.
Definition: tls.h:1834
CoapMessage response
CoAP response message.
Definition: coap_client.h:201
#define Socket
Definition: socket.h:36
TlsSessionState dtlsSession
DTLS session state.
Definition: coap_client.h:193
TLS (Transport Layer Security)
@ COAP_CLIENT_STATE_CONNECTED
Definition: coap_client.h:162
error_t coapClientConnect(CoapClientContext *context, const IpAddr *serverIpAddr, uint16_t serverPort)
Establish connection with the CoAP server.
Definition: coap_client.c:267
@ COAP_CLIENT_STATE_CONNECTING
Definition: coap_client.h:161
Socket * socket
Underlying UDP socket.
Definition: coap_client.h:190
size_t tokenLen
Token length.
Definition: coap_client.h:199
TCP/IP stack core.
error_t coapClientInit(CoapClientContext *context)
Initialize CoAP client context.
Definition: coap_client.c:53
Definitions common to CoAP client and server.
uint32_t systime_t
Definition: compiler_port.h:46
CoAP option formatting and parsing.
systime_t startTime
Start time.
Definition: coap_client.h:196