coap_service_api.h

00001 /*
00002  * Copyright (c) 2015-2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef COAP_SERVICE_API_H_
00019 #define COAP_SERVICE_API_H_
00020 
00021 #ifdef __cplusplus
00022 extern "C" {
00023 #endif
00024 
00025 #include <string.h>
00026 
00027 #include "ns_types.h"
00028 #include "mbed-coap/sn_coap_header.h"
00029 #include "ns_address.h"
00030 
00031 /**
00032  * This interface is used in sending and receiving of CoAP messages to multicast address and receive multiple responses.
00033  */
00034 
00035 // Allowed_methods
00036 #define COAP_SERVICE_ACCESS_ALL_ALLOWED         0x0F
00037 #define COAP_SERVICE_ACCESS_GET_ALLOWED         0x01
00038 #define COAP_SERVICE_ACCESS_PUT_ALLOWED         0x02
00039 #define COAP_SERVICE_ACCESS_POST_ALLOWED        0x04
00040 #define COAP_SERVICE_ACCESS_DELETE_ALLOWED      0x08
00041 
00042 // Bits for service options
00043 #define COAP_SERVICE_OPTIONS_NONE               0x00
00044 #define COAP_SERVICE_OPTIONS_VIRTUAL_SOCKET     0x01
00045 #define COAP_SERVICE_OPTIONS_SECURE             0x02
00046 #define COAP_SERVICE_OPTIONS_EPHEMERAL_PORT     0x04
00047 /** Coap interface selected as socket interface */
00048 #define COAP_SERVICE_OPTIONS_SELECT_SOCKET_IF   0x08
00049 /** Register to COAP multicast groups */
00050 #define COAP_SERVICE_OPTIONS_MULTICAST_JOIN     0x10
00051 /** Link-layer security bypass option is set*/
00052 #define COAP_SERVICE_OPTIONS_SECURE_BYPASS      0x80
00053 
00054 // Bits for request options
00055 #define COAP_REQUEST_OPTIONS_NONE               0x00
00056 #define COAP_REQUEST_OPTIONS_ADDRESS_DEFAULT    0x00//!< default is not setting either short or long.
00057 #define COAP_REQUEST_OPTIONS_ADDRESS_LONG       0x01
00058 #define COAP_REQUEST_OPTIONS_ADDRESS_SHORT      0x02
00059 #define COAP_REQUEST_OPTIONS_MULTICAST          0x04 //!< indicates that CoAP library support multicasting
00060 #define COAP_REQUEST_OPTIONS_SECURE_BYPASS      0x08
00061 
00062 extern const uint8_t COAP_MULTICAST_ADDR_LINK_LOCAL[16]; //!< ff02::fd, COAP link local multicast address
00063 extern const uint8_t COAP_MULTICAST_ADDR_ADMIN_LOCAL[16]; //!< ff03::fd, COAP admin-local multicast address
00064 extern const uint8_t COAP_MULTICAST_ADDR_SITE_LOCAL[16]; //!> ff05::fd, COAP site-local multicast address
00065 
00066 /**
00067  * \brief Service message response receive callback.
00068  *
00069  * Function that handles CoAP service message receiving and parsing
00070  *
00071  * \param service_id       Service handle.
00072  * \param source_address   IPv6 source address.
00073  * \param source_port      Source port.
00074  * \param response_ptr     Pointer to CoAP header structure.
00075  *
00076  * \return 0 for success / -1 for failure
00077   */
00078 typedef int coap_service_response_recv(int8_t service_id, uint8_t source_address[static 16], uint16_t source_port, sn_coap_hdr_s *response_ptr);
00079 
00080 /**
00081  * \brief CoAP service request callback
00082  *
00083  * CoAP service request message receiving and parsing function
00084  *
00085  * \param service_id         Id number of the current service.
00086  * \param source_address     IPv6 source address.
00087  * \param source_port        Source port.
00088  * \param request_ptr        Pointer to CoAP header structure.
00089  *
00090  * \return -1 = Message ignored, no response will be sent. Transaction will be deleted.
00091  *          0 = Response is either already sent or will be send. Transaction is not deleted.
00092  */
00093 typedef int coap_service_request_recv_cb(int8_t service_id, uint8_t source_address[static 16], uint16_t source_port, sn_coap_hdr_s *request_ptr);
00094 
00095 /**
00096  * \brief Security service start callback
00097  *
00098  * Starts security service handling and fetches device password.
00099  *
00100  * \param service_id         Id number of the current service.
00101  * \param address            Address of sender.
00102  * \param port               Port of the device.
00103  * \param pw                 Pointer where to write the ecjpake password.
00104  * \param pw_len             Pointer where to write length of the ecjpake password.
00105  *
00106  * \return 0 for success / -1 for failure
00107  */
00108 typedef int coap_service_security_start_cb(int8_t service_id, uint8_t address[static 16], uint16_t port, uint8_t *pw, uint8_t *pw_len);
00109 
00110 /**
00111  * \brief CoAP service security done callback
00112  *
00113  * CoAP service security done callback function.
00114  *
00115  * \param service_id         Id number of the current service.
00116  * \param address            Address of sender.
00117  * \param keyblock           Security key (40 bits).
00118  *
00119  * \return 0 for success / -1 for failure
00120  */
00121 typedef int coap_service_security_done_cb(int8_t service_id, uint8_t address[static 16], uint8_t keyblock[static 40]);
00122 
00123 /**
00124  * \brief Message prevalidation callback
00125  *
00126  * Message prevalidation callback function type used in method coap_service_msg_prevalidate_callback_set.
00127  *
00128  * \param local_interface_id    Local interface ID, message arrived to this interface.
00129  * \param local_address         Local address, message arrived to this address.
00130  * \param local_port            Local port, message arrived to this port.
00131  * \param recv_interface_id     Interface ID where message was received.
00132  * \param source_address        Sender address.
00133  * \param source_port           Sender port.
00134  * \param coap_uri              CoAP URI, NUL terminated.
00135  *
00136  * \return <0 in case of errors,
00137  *         0 if message is valid to process further,
00138  *         >0 if message should be dropped.
00139  */
00140 
00141 typedef int coap_service_msg_prevalidate_cb(int8_t local_interface_id, uint8_t local_address[static 16], uint16_t local_port, int8_t recv_interface_id, uint8_t source_address[static 16], uint16_t source_port, char *coap_uri);
00142 
00143 /**
00144  * \brief Initialise server instance.
00145  *
00146  * Initialise Thread services for the registered application.
00147  *
00148  * \param interface_id       Informs registered application interface id. This parameter is passed to socket implementation.
00149  * \param listen_port        Port that Application wants to use for communicate with coap server.
00150  * \param service_options    Options of the current service.
00151  * \param *start_ptr         Callback to inform security handling is started and to fetch device password.
00152  * \param *coap_security_done_cb  Callback to inform security handling is done.
00153  *
00154  * \return service_id / -1 for failure
00155  */
00156 extern int8_t coap_service_initialize(int8_t interface_id, uint16_t listen_port, uint8_t service_options, coap_service_security_start_cb *start_ptr, coap_service_security_done_cb *coap_security_done_cb);
00157 
00158 /**
00159  * \brief Service delete
00160  *
00161  * Removes all data related to this instance
00162  *
00163  * \param service_id         Id number of the current service.
00164  */
00165 extern void coap_service_delete(int8_t service_id);
00166 
00167 /**
00168  * \brief Close secure connection
00169  *
00170  * Closes secure connection (if present), but leaves socket open.
00171  *
00172  * \param service_id            Id number of the current service.
00173  * \param destimation_addr_ptr  Connection destination address.
00174  * \param port                  Connection destination port.
00175  */
00176 extern void coap_service_close_secure_connection(int8_t service_id, uint8_t destination_addr_ptr[static 16], uint16_t port);
00177 
00178 /**
00179  * \brief Virtual socket sent callback.
00180  *
00181  * Sent data to virtual socket.
00182  *
00183  * \param service_id                       Id number of the current service.
00184  * \param destination_addr_ptr             Receiver IPv6 address.
00185  * \param port                             Receiver port number.
00186  * \param *data_ptr                        Pointer to the data.
00187  * \param data_len                         Lenght of the data.
00188  *
00189  * \return 0 for success / -1 for failure
00190   */
00191 typedef int coap_service_virtual_socket_send_cb(int8_t service_id, uint8_t destination_addr_ptr[static 16], uint16_t port, const uint8_t *data_ptr, uint16_t data_len);
00192 
00193 /**
00194  * \brief Virtual socket read.
00195  *
00196  * Receive data from virtual socket.
00197  *
00198  * \param service_id                       Id number of the current service.
00199  * \param source_addr_ptr                  Receiver IPv6 address.
00200  * \param port                             Receiver port number.
00201  * \param *data_ptr                        Pointer to the data
00202  * \param data_len                         Lenght of the data
00203  *
00204  * \return 0 for success / -1 for failure
00205   */
00206 extern int16_t coap_service_virtual_socket_recv(int8_t service_id, uint8_t source_addr_ptr[static 16], uint16_t port, uint8_t *data_ptr, uint16_t data_len);
00207 
00208 /**
00209  * \brief Set virtual socket
00210  *
00211  * Sets virtual socket for CoAP services.
00212  *
00213  * \param service_id         Id number of the current service.
00214  * \param *send_method_ptr   Callback to coap virtual socket.
00215  *
00216  * \return 0 for success / -1 for failure
00217  */
00218 extern int16_t coap_service_virtual_socket_set_cb(int8_t service_id, coap_service_virtual_socket_send_cb *send_method_ptr);
00219 
00220 /**
00221  * \brief Register unsecure callback methods to CoAP server
00222  *
00223  * Register application and informs CoAP services unsecure registery callback function.
00224  *
00225  * \param service_id       Id number of the current service.
00226  * \param *uri             Uri address.
00227  * \param allowed_method   Informs method that is allowed to use (used defines described above).
00228  * \param *request_recv_cb CoAP service request receive callback function pointer.
00229  *
00230  * \return 0 for success / -1 for failure
00231  */
00232 extern int8_t coap_service_register_uri(int8_t service_id, const char *uri, uint8_t allowed_method, coap_service_request_recv_cb *request_recv_cb);
00233 
00234 /**
00235  * \brief Unregister unsecure callback methods to CoAP server
00236  *
00237  * Register application and informs CoAP services unsecure registery callback function.
00238  *
00239  * \param service_id       Id number of the current service.
00240  * \param *uri             Uri address.
00241  *
00242  * \return 0 for success / -1 for failure
00243  */
00244 extern int8_t coap_service_unregister_uri(int8_t service_id, const char *uri);
00245 
00246 /**
00247  * \brief Sends CoAP service request
00248  *
00249  * Build and sends CoAP service request message.
00250  *
00251  * \param service_id            Id number of the current service.
00252  * \param options               Options defined above.
00253  * \param destination_addr      IPv6 address.
00254  * \param destination_port      Destination port
00255  * \param msg_type              Message type can be found from sn_coap_header.
00256  * \param msg_code              Message code can be found from sn_coap_header.
00257  * \param *uri                  Uri address.
00258  * \param cont_type             Content type can be found from sn_coap_header.
00259  * \param payload_ptr           Pointer to message content.
00260  * \param payload_len           Lenght of the message.
00261  * \param *request_response_cb  Callback to inform result of the request.
00262  *
00263  * \return msg_id               Id number of the current message.
00264  */
00265 extern uint16_t coap_service_request_send(int8_t service_id, uint8_t options, const uint8_t destination_addr[static 16], uint16_t destination_port, sn_coap_msg_type_e msg_type, sn_coap_msg_code_e msg_code, const char *uri,
00266                                           sn_coap_content_format_e cont_type, const uint8_t *payload_ptr, uint16_t payload_len, coap_service_response_recv *request_response_cb);
00267 
00268 /**
00269  * \brief Sends CoAP service response
00270  *
00271  * Build and sends CoAP service response message.
00272  *
00273  * \param service_id       Id number of the current service.
00274  * \param options          Options defined above.
00275  * \param request_ptr      Pointer to CoAP request message header structure.
00276  * \param message_code     Message code can be found from sn_coap_header.
00277  * \param content_type     Content type can be found from sn_coap_header.
00278  * \param payload_ptr      Pointer to message content.
00279  * \param payload_len      Lenght of the message.
00280  *
00281  * \return -1              For failure
00282  *-         0              For success
00283  */
00284 extern int8_t coap_service_response_send(int8_t service_id, uint8_t options, sn_coap_hdr_s *request_ptr, sn_coap_msg_code_e message_code, sn_coap_content_format_e content_type, const uint8_t *payload_ptr, uint16_t payload_len);
00285 
00286 /**
00287  * \brief Sends CoAP service response
00288  *
00289  * Build and sends CoAP service response message based on CoAP request message id.
00290  *
00291  * \param service_id       Id number of the current service.
00292  * \param options          Options defined above.
00293  * \param msg_id           Request messages ID.
00294  * \param msg_type         Message type can be found from sn_coap_header.
00295  * \param message_code     Message code can be found from sn_coap_header.
00296  * \param content_type     Content type can be found from sn_coap_header.
00297  * \param payload_ptr      Pointer to message content.
00298  * \param payload_len      Lenght of the message.
00299  *
00300  * \return -1              For failure
00301  *-         0              For success
00302  */
00303 extern int8_t coap_service_response_send_by_msg_id(int8_t service_id, uint8_t options, uint16_t msg_id, sn_coap_msg_code_e message_code, sn_coap_content_format_e content_type, const uint8_t *payload_ptr, uint16_t payload_len);
00304 
00305 /**
00306  * \brief Delete CoAP request transaction
00307  *
00308  * Removes pending CoAP transaction from service.
00309  *
00310  * \param service_id       Id number of the current service.
00311  * \param msg_id           Message ID number.
00312  *
00313  * \return -1              For failure
00314  *-         0              For success
00315  */
00316 extern int8_t coap_service_request_delete(int8_t service_id, uint16_t msg_id);
00317 
00318 /**
00319  * \brief Delete CoAP requests from service id
00320  *
00321  * Removes pending CoAP requests from service specified by service_id.
00322  *
00323  * \param service_id       Id number of the current service.
00324  */
00325 extern void coap_service_request_delete_by_service_id(int8_t service_id);
00326 
00327 /**
00328  * \brief Set DTLS handshake timeout values
00329  *
00330  * Configures the DTLS handshake timeout values.
00331  *
00332  * \param service_id       Id number of the current service.
00333  * \param min              Initial timeout value.
00334  * \param max              Maximum value of timeout.
00335  *
00336  * \return -1              For failure
00337  *-         0              For success
00338  */
00339 extern int8_t coap_service_set_handshake_timeout(int8_t service_id, uint32_t min, uint32_t max);
00340 
00341 /**
00342  * \brief Set DTLS handshake limit values
00343  *
00344  * Configures the limits for DTLS sessions. Values must be > 0.
00345  *
00346  * \param handshakes_max        Maximum amount of simultaneous handshakes.
00347  * \param connections_max       Maximum amount of sessions.
00348  *
00349  * \return -1              For failure
00350  *-         0              For success
00351  */
00352 extern int8_t coap_service_handshake_limits_set(uint8_t handshakes_max, uint8_t connections_max);
00353 
00354 /**
00355  * \brief Set CoAP duplication message buffer size
00356  *
00357  * Configures the CoAP duplication message buffer size.
00358  *
00359  * \param service_id       Id number of the current service.
00360  * \param size             Buffer size (messages).
00361  *
00362  * \return -1              For failure
00363  *-         0              For success
00364  */
00365 extern int8_t coap_service_set_duplicate_message_buffer(int8_t service_id, uint8_t size);
00366 
00367 /**
00368  * \brief Set DTLS certificates
00369  *
00370  * Set DTLS certificates.
00371  *
00372  * \param service_id       Id number of the current service.
00373  * \param cert             Pointer to certificate chain.
00374  * \param cert_len         Certificate length.
00375  * \param priv_key         pointer to private key.
00376  * \param priv_key_len     length of private key.
00377  *
00378  * \return -1              For failure
00379  *-         0              For success
00380  */
00381 
00382 extern int8_t coap_service_certificate_set(int8_t service_id, const unsigned char *cert, uint16_t cert_len, const unsigned char *priv_key, uint8_t priv_key_len);
00383 
00384 /**
00385  * \brief Set CoAP blockwise payload size
00386  *
00387  * Set CoAP blockwise payload limit. If payload is bigger than configured limit, CoAP message will use blockwise option when sending.
00388  *
00389  * \param service_id       Id number of the current service.
00390  * \param size             Blockwise size. Valid sizes are 16, 32, 64, 128, 256, 512 and 1024 bytes
00391  *
00392  * \return -1              For failure
00393  *-         0              For success
00394  */
00395 extern int8_t coap_service_blockwise_size_set(int8_t service_id, uint16_t size);
00396 
00397 /**
00398  * \brief Set message prevalidation callback function.
00399  *
00400  * Set message prevalidation callback function for the service. Callback will be called for all services using the same listen port.
00401  *
00402  * CoAP service will call this function to allow application prevalidate incoming CoAP message before passing it to application.
00403  *
00404  * \param listen_port           Socket port where to set callback.
00405  * \param msg_prevalidate_cb    Callback to be called to validate incoming message before processing it. Use NULL to clear callback usage.
00406  *
00407  * \return -1              For failure
00408  *          0              For success
00409  */
00410 extern int8_t coap_service_msg_prevalidate_callback_set(uint16_t listen_port, coap_service_msg_prevalidate_cb *msg_prevalidate_cb);
00411 
00412 #ifdef __cplusplus
00413 }
00414 #endif
00415 
00416 #endif /* COAP_SERVICE_API_H_ */