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