baidu_ca.h

00001 // Copyright 2017 Baidu Inc. All Rights Reserved.
00002 // Author: Su Hao (suhao@baidu.com)
00003 //
00004 // Desc: Provide the API for external applications.
00005 
00006 #ifndef BAIDU_IOT_TINYDU_IOT_OS_SRC_IOT_BAIDU_CA_INCLUDE_BAIDU_CA_H
00007 #define BAIDU_IOT_TINYDU_IOT_OS_SRC_IOT_BAIDU_CA_INCLUDE_BAIDU_CA_H
00008 
00009 #include "baidu_ca_types.h"
00010 
00011 #ifdef __cplusplus
00012 extern "C" {
00013 #endif
00014 
00015 /*
00016  * The message codes.
00017  */
00018 typedef enum {
00019 
00020     // Request message code
00021     BCA_MSG_REQ_GET                             = 1,
00022     BCA_MSG_REQ_POST                            = 2,
00023     BCA_MSG_REQ_PUT                             = 3,
00024     BCA_MSG_REQ_DELETE                          = 4,
00025 
00026     // Response message code
00027     BCA_MSG_RSP_CREATED                         = 65,   // 2.01
00028     BCA_MSG_RSP_DELETED                         = 66,   // 2.02
00029     BCA_MSG_RSP_VALID                           = 67,   // 2.03
00030     BCA_MSG_RSP_CHANGED                         = 68,   // 2.04
00031     BCA_MSG_RSP_CONTENT                         = 69,   // 2.05
00032     BCA_MSG_RSP_CONTINUE                        = 95,   // 2.31
00033     BCA_MSG_RSP_BAD_REQUEST                     = 128,  // 4.00
00034     BCA_MSG_RSP_UNAUTHORIZED                    = 129,  // 4.01
00035     BCA_MSG_RSP_BAD_OPTION                      = 130,  // 4.02
00036     BCA_MSG_RSP_FORBIDDEN                       = 131,  // 4.03
00037     BCA_MSG_RSP_NOT_FOUND                       = 132,  // 4.04
00038     BCA_MSG_RSP_METHOD_NOT_ALLOWED              = 133,  // 4.05
00039     BCA_MSG_RSP_NOT_ACCEPTABLE                  = 134,  // 4.06
00040     BCA_MSG_RSP_REQUEST_ENTITY_INCOMPLETE       = 136,  // 4.08
00041     BCA_MSG_RSP_PRECONDITION_FAILED             = 140,  // 4.12
00042     BCA_MSG_RSP_REQUEST_ENTITY_TOO_LARGE        = 141,  // 4.13
00043     BCA_MSG_RSP_UNSUPPORTED_CONTENT_FORMAT      = 143,  // 4.15
00044     BCA_MSG_RSP_INTERNAL_SERVER_ERROR           = 160,  // 5.00
00045     BCA_MSG_RSP_NOT_IMPLEMENTED                 = 161,  // 5.01
00046     BCA_MSG_RSP_BAD_GATEWAY                     = 162,  // 5.02
00047     BCA_MSG_RSP_SERVICE_UNAVAILABLE             = 163,  // 5.03
00048     BCA_MSG_RSP_GATEWAY_TIMEOUT                 = 164,  // 5.04
00049     BCA_MSG_RSP_PROXYING_NOT_SUPPORTED          = 165,  // 5.05
00050 
00051 } bca_msg_code_e;
00052 
00053 /**
00054  * CoAP Message type, used in CoAP Header
00055  */
00056 typedef enum {
00057     BCA_MSG_TYPE_CONFIRMABLE       = 0x00, // Reliable Request messages
00058     BCA_MSG_TYPE_NON_CONFIRMABLE   = 0x10, // Non-reliable Request and Response messages
00059     BCA_MSG_TYPE_ACKNOWLEDGEMENT   = 0x20, // Response to a Confirmable Request
00060     BCA_MSG_TYPE_RESET             = 0x30  // Answer a Bad Request
00061 } bca_msg_type_e;
00062 
00063 /*
00064  * The resource operation permission
00065  */
00066 typedef enum {
00067     BCA_RES_OP_GET      = 0x01,     // Get operation allowed
00068     BCA_RES_OP_PUT      = 0x02,     // Put operation allowed
00069     BCA_RES_OP_POST     = 0x04,     // Post operation allowed
00070     BCA_RES_OP_DELETE   = 0x08      // Delete operation allowed
00071 } bca_resource_operation_e;
00072 
00073 /*
00074  * The resource mode
00075  */
00076 typedef enum {
00077     BCA_RES_MODE_STATIC,            // Static resources have some value that doesn't change
00078     BCA_RES_MODE_DYNAMIC,           // Dynamic resources are handled in application
00079 } bca_resource_mode_e;
00080 
00081 enum _baidu_ca_protocol_enum {
00082     BCA_PROTO_TCP,
00083     BCA_PROTO_UDP
00084 };
00085 
00086 /*
00087  * The message definition
00088  */
00089 typedef struct _bca_message_s {
00090     bca_u16_t token_len;
00091 
00092     bca_u8_t  msg_type;
00093     bca_u8_t  msg_code;
00094     bca_u16_t msg_id;
00095 
00096     bca_u16_t path_len;
00097     bca_u16_t query_len;
00098     bca_u16_t payload_len;
00099 
00100     bca_u8_t* token;
00101     bca_u8_t* path;
00102     bca_u8_t* query;
00103     bca_u8_t* payload;
00104 } bca_msg_t;
00105 
00106 /*
00107  * Adapt the memory management functions.
00108  */
00109 typedef void* (*bca_malloc_f)(bca_context context, bca_size_t size);
00110 
00111 typedef void* (*bca_realloc_f)(bca_context context, void*, bca_size_t size);
00112 
00113 typedef void (*bca_free_f)(bca_context context, void* p);
00114 
00115 /*
00116  * The network address structure
00117  */
00118 typedef struct _bca_address_s {
00119     bca_u8_t    type;       // the socket type
00120     bca_u16_t   port;       // the host port
00121     void*       host;       // the host address
00122     bca_size_t  host_size;  // the host address length
00123 } bca_addr_t;
00124 
00125 /*
00126  * The network transfer data callbacks.
00127  * See the detail in @{link baidu_ca_transport_init}
00128  */
00129 typedef void* bca_socket_t;
00130 
00131 typedef bca_socket_t (*bca_soc_create_f)(bca_context ctx);
00132 
00133 typedef bca_status_t (*bca_soc_connect_f)(bca_socket_t sock,
00134                                           const bca_addr_t* addr);
00135 
00136 typedef bca_status_t (*bca_soc_send_f)(bca_socket_t sock,
00137                                        const void* data,
00138                                        bca_size_t size,
00139                                        const bca_addr_t* addr);
00140 
00141 typedef bca_status_t (*bca_soc_recv_f)(bca_socket_t sock,
00142                                        void* data,
00143                                        bca_size_t size,
00144                                        bca_addr_t* addr);
00145 
00146 typedef bca_status_t (*bca_soc_recv_timeout_f)(bca_socket_t sock,
00147                                                void* data,
00148                                                bca_size_t size,
00149                                                bca_u32_t timeout,
00150                                                bca_addr_t* addr);
00151 
00152 typedef bca_status_t (*bca_soc_close_f)(bca_socket_t sock);
00153 
00154 typedef bca_status_t (*bca_soc_destroy_f)(bca_socket_t sock);
00155 
00156 /*
00157  * The mutex callbacks
00158  */
00159 
00160 typedef void* bca_mutex_t;
00161 typedef bca_mutex_t (*bca_mutex_create_f)();
00162 typedef bca_status_t (*bca_mutex_lock_f)(bca_mutex_t mtx);
00163 typedef bca_status_t (*bca_mutex_unlock_f)(bca_mutex_t mtx);
00164 typedef bca_status_t (*bca_mutex_destroy_f)(bca_mutex_t mtx);
00165 
00166 /*
00167  * The timestamp callbacks
00168  */
00169 
00170 // Return the timestamp by milliseconds
00171 typedef bca_u32_t (*bca_timestamp_f)();
00172 
00173 /*
00174  * The random callbacks
00175  */
00176 
00177 // Return the random number
00178 typedef bca_s32_t (*bca_random_f)();
00179 
00180 /*
00181  * The handler
00182  */
00183 typedef void* bca_handler;
00184 
00185 /*
00186  * The status notification to user.
00187  */
00188 
00189 typedef bca_status_t (*bca_notify_f)(bca_context ctx,
00190                                      bca_msg_t* msg,
00191                                      bca_addr_t* addr);
00192 
00193 /*
00194  * The debug output
00195  */
00196 typedef void (*bca_debug_f)(bca_context ctx,
00197                             bca_u32_t level,
00198                             const char* file,
00199                             bca_u32_t line,
00200                             const char* fmt);
00201 
00202 /*
00203  * The resource for user
00204  */
00205 typedef struct _bca_resource_s {
00206     bca_u8_t    mode: 2;    // the resource mode, SEE in ${link bca_resource_mode_e}
00207     bca_u8_t    allowed: 6; // operation permission, SEE in ${link bca_resource_operation_e}
00208     char*       path;       // the resource path identify
00209 
00210     union {
00211         bca_notify_f   f_res;   // dynamic resource handle function, NULL if static
00212         struct {
00213             void*       data;   // static resource value data, NULL if dynamic
00214             bca_size_t  size;   // static resource size
00215         } s_res;
00216     } res;
00217 } bca_res_t;
00218 
00219 /*
00220  * Set the debug output
00221  *
00222  * @Param ctx, bca_context, the debug context for user
00223  * @Param f_debug, bca_debug_f, the debug output function
00224  */
00225 BCA_EXT void baidu_ca_debug_init(bca_context ctx, bca_debug_f f_debug);
00226 
00227 /*
00228  * Set the memory management functions.
00229  *
00230  * @Param ctx, bca_context, in, the memory context for user
00231  * @Param f_malloc, bca_malloc_f, the memory alloc function for user
00232  * @Param f_realloc, bca_realloc_f, the memory realloc function for user,
00233  * @Param f_free, bca_free_f, the memory free function for user
00234  *
00235  * If f_malloc or f_free set to NULL, we will use default libc instead all of it;
00236  * If only f_realloc set to NULL, we will realized it by f_malloc and f_free.
00237  */
00238 BCA_EXT void baidu_ca_memory_init(bca_context context,
00239                                   bca_malloc_f f_malloc,
00240                                   bca_realloc_f f_realloc,
00241                                   bca_free_f f_free);
00242 
00243 /*
00244  * Set network input/ouput function
00245  *
00246  * @Param f_create, in, the function create socket context
00247  * @Param f_conn, in, the function connect socket to host
00248  * @Param f_send, in, the function send message
00249  * @Param f_recv, in, the function receive message
00250  * @Param f_recv_timeout, in, the function receive message with timeout
00251  * @Param f_close, in, the function close the socket
00252  * @Param f_destroy, in, the function destroy the socket context
00253  */
00254 BCA_EXT void baidu_ca_transport_init(bca_soc_create_f f_create,
00255                                      bca_soc_connect_f f_conn,
00256                                      bca_soc_send_f f_send,
00257                                      bca_soc_recv_f f_recv,
00258                                      bca_soc_recv_timeout_f f_recv_timeout,
00259                                      bca_soc_close_f f_close,
00260                                      bca_soc_destroy_f f_destroy);
00261 
00262 /*
00263  * Initial the mutex callbacks for Baidu CA
00264  *
00265  * @Param f_create, in, the function create mutex context
00266  * @Param f_lock, in, the function mutex lock
00267  * @Param f_unlock, in, the function mutex unlock
00268  * @Param f_destroy, in, the function destroy mutex context
00269  */
00270 BCA_EXT void baidu_ca_mutex_init(bca_mutex_create_f f_create,
00271                                  bca_mutex_lock_f f_lock,
00272                                  bca_mutex_unlock_f f_unlock,
00273                                  bca_mutex_destroy_f f_destroy);
00274 
00275 /*
00276  * Initial the timestamp callbacks for Baidu CA
00277  *
00278  * @Param f_timestamp, in, the function obtain the timestamp
00279  */
00280 BCA_EXT void baidu_ca_timestamp_init(bca_timestamp_f f_timestamp);
00281 
00282 /*
00283  * Initial the random callbacks for Baidu CA
00284  *
00285  * @Param bca_random_f, in, the function random generator function
00286  */
00287 BCA_EXT void baidu_ca_random_init(bca_random_f f_random);
00288 
00289 /*
00290  * Acquire the handler
00291  *
00292  * @Param data, in, the configuration data
00293  * @Param size, in, the data size
00294  * @Param soc_ctx, in socket context
00295  * @Return bca_handler, the global context handler
00296  */
00297 BCA_EXT bca_handler baidu_ca_acquire(const void* data,
00298                                      bca_size_t size,
00299                                      bca_context soc_ctx);
00300 
00301 /*
00302  * Acquire the resources for response
00303  *
00304  * @Param hdlr, in, the handler will be operated
00305  * @Param list_res, in, resource list
00306  * @Param list_res_size, in resource list length
00307  * @Return bca_status_t, in, the operation result
00308  */
00309 BCA_EXT bca_status_t baidu_ca_add_resources(bca_handler hdlr,
00310                                             const bca_res_t list_res[],
00311                                             bca_size_t list_res_size);
00312 
00313 /*
00314  * Start run the Baidu CA, prepare the environment.
00315  *
00316  * @Param hdlr, in, the handler will be operated
00317  * @Return bca_status_t, in, the operation result
00318  */
00319 BCA_EXT bca_status_t baidu_ca_start(bca_handler hdlr);
00320 
00321 /*
00322  * Set the Reporter report response callback.
00323  *
00324  * @Param hdlr, in, the handler will be operated
00325  * @Param f_response, in, the callback for notify user the report data response
00326  * @Return bca_status_t, in, the operation result
00327  */
00328 BCA_EXT bca_status_t baidu_ca_report_set_response_callback(bca_handler hdlr,
00329                                                            bca_notify_f f_response,
00330                                                            bca_context context);
00331 
00332 /*
00333  * Build the message body that will be reported.
00334  *
00335  * @Param hdlr, in, the handler will be operated
00336  * @Param data, in, the message report data
00337  * @Param size, in, the data size
00338  * @Param confirmable, in, the report data QoS
00339  * @Return bca_msg_t *, in, the generated message body,
00340  *         it SHOULD be released by ${link baidu_ca_release_message}
00341  */
00342 BCA_EXT bca_msg_t* baidu_ca_build_report_message(bca_handler hdlr,
00343                                                  bca_bool confirmable);
00344 
00345 /*
00346  * Build the message body that will be responsed to remote.
00347  *
00348  * @Param hdlr, in, the handler will be operated
00349  * @Param msg, in, the message that remote requested
00350  * @Param msg_code, out, the response message code
00351  * @Return bca_msg_t *, in, the generated message body,
00352  *         it SHOULD be released by ${link baidu_ca_release_message}
00353  */
00354 BCA_EXT bca_msg_t* baidu_ca_build_response_message(bca_handler hdlr,
00355                                                    const bca_msg_t* msg,
00356                                                    bca_u8_t msg_code);
00357 
00358 /*
00359  * Release the message that generated by baidu_ca_build_XXXX_message.
00360  *
00361  * @Param hdlr, in, the handler will be operated
00362  * @Param msg, in, the message that remote requested
00363  */
00364 BCA_EXT void baidu_ca_release_message(bca_handler hdlr, bca_msg_t* msg);
00365 
00366 /*
00367  * Send the message
00368  *
00369  * @Param hdlr, in, the handler will be operated
00370  * @Param msg, in, the msg will be sent
00371  * @Param addr, in, the remote addr
00372  * @Return bca_status_t, in, the operation result
00373  */
00374 BCA_EXT bca_status_t baidu_ca_send_data(bca_handler hdlr,
00375                                         const bca_msg_t* msg,
00376                                         const bca_addr_t* addr);
00377 
00378 /*
00379  * When the message data has ready to be received
00380  *
00381  * @Param hdlr, in, the handler will be operated
00382  * @Param addr, in, the remote addr
00383  * @Return bca_status_t, in, the operation result
00384  */
00385 BCA_EXT bca_status_t baidu_ca_data_available(bca_handler hdlr,
00386                                              const bca_addr_t* addr);
00387 
00388 /*
00389  * Execute the cached CoAP data, such as blockwise, resending...
00390  *
00391  * @Param hdlr, in, the handler will be operated
00392  * @Return bca_status_t, in, the operation result
00393  */
00394 BCA_EXT bca_status_t baidu_ca_exec(bca_handler hdlr);
00395 
00396 /*
00397  * Stop the Baidu CA.
00398  *
00399  * @Param hdlr, in, the handler will be operated
00400  * @Return bca_status_t, in, the operation result
00401  */
00402 BCA_EXT bca_status_t baidu_ca_stop(bca_handler hdlr);
00403 
00404 /*
00405  * Release the handler
00406  *
00407  * @Param hdlr, in, the handler will be operated
00408  * @Return bca_status_t, in, the operation result
00409  */
00410 BCA_EXT bca_status_t baidu_ca_release(bca_handler hdlr);
00411 
00412 #ifdef __cplusplus
00413 }
00414 #endif
00415 
00416 #endif // BAIDU_IOT_TINYDU_IOT_OS_SRC_IOT_BAIDU_CA_INCLUDE_BAIDU_CA_H