src/afb-wsj1.h

   1 /*
   2  * Copyright (C) 2016 "IoT.bzh"
   3  * Author: José Bollo <jose.bollo@iot.bzh>
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *   http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 #pragma once
  19
  20 struct afb_wsj1;
  21 struct afb_wsj1_msg;
  22
  23 struct json_object;
  24
  25 /*
  26  * Interface for callback functions.
  27  * The received closure is the closure passed when creating the afb_wsj1
  28  * socket using afb_wsj1_create.
  29  */
  30 struct afb_wsj1_itf {
  31         /*
  32          *  This function is called on hangup.
  33          *  Receives the 'closure' and the handle 'wsj1'
  34          */
  35         void (*on_hangup)(void *closure, struct afb_wsj1 *wsj1);
  36
  37         /*
  38          * This function is called on incoming call.
  39          * Receives the 'closure'
  40          */
  41         void (*on_call)(void *closure, const char *api, const char *verb, struct afb_wsj1_msg *msg);
  42
  43         /*
  44          * This function is called on incoming event
  45          */
  46         void (*on_event)(void *closure, const char *event, struct afb_wsj1_msg *msg);
  47 };
  48
  49 /*
  50  * Creates the afb_wsj1 socket connected to the file descriptor 'fd'
  51  * and having the callback interface defined by 'itf' for the 'closure'.
  52  * Returns the created wsj1 websocket or NULL in case of error.
  53  */
  54 extern struct afb_wsj1 *afb_wsj1_create(int fd, struct afb_wsj1_itf *itf, void *closure);
  55
  56 /*
  57  * Increases by one the count of reference to 'wsj1'
  58  */
  59 extern void afb_wsj1_addref(struct afb_wsj1 *wsj1);
  60
  61 /*
  62  * Decreases by one the count of reference to 'wsj1'
  63  * and if it falls to zero releases the used resources
  64  * and free the memory
  65  */
  66 extern void afb_wsj1_unref(struct afb_wsj1 *wsj1);
  67
  68 /*
  69  * Sends a close message to the websocket of 'wsj1'.
  70  * The close message is sent with the 'code' and 'text'.
  71  * 'text' can be NULL.
  72  * Return 0 in case of success. Otherwise, returns -1 and set errno.
  73  */
  74 extern int afb_wsj1_close(struct afb_wsj1 *wsj1, uint16_t code, const char *text);
  75
  76 /*
  77  * Sends on 'wsj1' the event of name 'event' with the
  78  * data 'object'. If not NULL, 'object' should be a valid
  79  * JSON string.
  80  * Return 0 in case of success. Otherwise, returns -1 and set errno.
  81  */
  82 extern int afb_wsj1_send_event_s(struct afb_wsj1 *wsj1, const char *event, const char *object);
  83
  84 /*
  85  * Sends on 'wsj1' the event of name 'event' with the
  86  * data 'object'. 'object' can be NULL.
  87  * 'object' is dereferenced using 'json_object_put'. Use 'json_object_get' to keep it.
  88  * Return 0 in case of success. Otherwise, returns -1 and set errno.
  89  */
  90 extern int afb_wsj1_send_event_j(struct afb_wsj1 *wsj1, const char *event, struct json_object *object);
  91
  92 /*
  93  * Sends on 'wsj1' a call to the method of 'api'/'verb' with arguments
  94  * given by 'object'. If not NULL, 'object' should be a valid JSON string.
  95  * On receiving the reply, the function 'on_reply' is called with 'closure'
  96  * as its first argument and the message of the reply.
  97  * Return 0 in case of success. Otherwise, returns -1 and set errno.
  98  */
  99 extern int afb_wsj1_call_s(struct afb_wsj1 *wsj1, const char *api, const char *verb, const char *object, void (*on_reply)(void *closure, struct afb_wsj1_msg *msg), void *closure);
 100
 101 /*
 102  * Sends on 'wsj1' a call to the method of 'api'/'verb' with arguments
 103  * given by 'object'. 'object' can be NULL.
 104  * 'object' is dereferenced using 'json_object_put'. Use 'json_object_get' to keep it.
 105  * On receiving the reply, the function 'on_reply' is called with 'closure'
 106  * as its first argument and the message of the reply.
 107  * Return 0 in case of success. Otherwise, returns -1 and set errno.
 108  */
 109 extern int afb_wsj1_call_j(struct afb_wsj1 *wsj1, const char *api, const char *verb, struct json_object *object, void (*on_reply)(void *closure, struct afb_wsj1_msg *msg), void *closure);
 110
 111 /*
 112  * Sends for message 'msg' the reply with the 'object' and, if not NULL, the token.
 113  * When 'iserror' is zero a OK reply is send, otherwise an ERROR reply is sent.
 114  * If not NULL, 'object' should be a valid JSON string.
 115  * Return 0 in case of success. Otherwise, returns -1 and set errno.
 116  */
 117 extern int afb_wsj1_reply_s(struct afb_wsj1_msg *msg, const char *object, const char *token, int iserror);
 118
 119 /*
 120  * Sends for message 'msg' the reply with the 'object' and, if not NULL, the token.
 121  * When 'iserror' is zero a OK reply is send, otherwise an ERROR reply is sent.
 122  * 'object' can be NULL.
 123  * 'object' is dereferenced using 'json_object_put'. Use 'json_object_get' to keep it.
 124  * Return 0 in case of success. Otherwise, returns -1 and set errno.
 125  */
 126 extern int afb_wsj1_reply_j(struct afb_wsj1_msg *msg, struct json_object *object, const char *token, int iserror);
 127
 128 /*
 129  * Sends for message 'msg' the OK reply with the 'object' and, if not NULL, the token.
 130  * If not NULL, 'object' should be a valid JSON string.
 131  * Return 0 in case of success. Otherwise, returns -1 and set errno.
 132  */
 133 static inline int afb_wsj1_reply_ok_s(struct afb_wsj1_msg *msg, const char *object, const char *token)
 134 {
 135         return afb_wsj1_reply_s(msg, object, token, 0);
 136 }
 137
 138 /*
 139  * Sends for message 'msg' the OK reply with the 'object' and, if not NULL, the token.
 140  * 'object' can be NULL.
 141  * 'object' is dereferenced using 'json_object_put'. Use 'json_object_get' to keep it.
 142  * Return 0 in case of success. Otherwise, returns -1 and set errno.
 143  */
 144 static inline int afb_wsj1_reply_ok_j(struct afb_wsj1_msg *msg, struct json_object *object, const char *token)
 145 {
 146         return afb_wsj1_reply_j(msg, object, token, 0);
 147 }
 148
 149 /*
 150  * Sends for message 'msg' the ERROR reply with the 'object' and, if not NULL, the token.
 151  * If not NULL, 'object' should be a valid JSON string.
 152  * Return 0 in case of success. Otherwise, returns -1 and set errno.
 153  */
 154 static inline int afb_wsj1_reply_error_s(struct afb_wsj1_msg *msg, const char *object, const char *token)
 155 {
 156         return afb_wsj1_reply_s(msg, object, token, 1);
 157 }
 158
 159 /*
 160  * Sends for message 'msg' the ERROR reply with the 'object' and, if not NULL, the token.
 161  * 'object' can be NULL.
 162  * 'object' is dereferenced using 'json_object_put'. Use 'json_object_get' to keep it.
 163  * Return 0 in case of success. Otherwise, returns -1 and set errno.
 164  */
 165 static inline int afb_wsj1_reply_error_j(struct afb_wsj1_msg *msg, struct json_object *object, const char *token)
 166 {
 167         return afb_wsj1_reply_j(msg, object, token, 1);
 168 }
 169
 170 /*
 171  * Increases by one the count of reference to 'msg'.
 172  * Should be called if callbacks stores the message.
 173  */
 174 extern void afb_wsj1_msg_addref(struct afb_wsj1_msg *msg);
 175
 176 /*
 177  * Decreases by one the count of reference to 'msg'.
 178  * and if it falls to zero releases the used resources
 179  * and free the memory.
 180  * Should be called if 'afb_wsj1_msg_addref' was called.
 181  */
 182 extern void afb_wsj1_msg_unref(struct afb_wsj1_msg *msg);
 183
 184 /*
 185  * Returns 1 if 'msg' is for a CALL
 186  * Otherwise returns 0.
 187  */
 188 extern int afb_wsj1_msg_is_call(struct afb_wsj1_msg *msg);
 189
 190 /*
 191  * Returns 1 if 'msg' is for a REPLY of any kind
 192  * Otherwise returns 0.
 193  */
 194 extern int afb_wsj1_msg_is_reply(struct afb_wsj1_msg *msg);
 195
 196 /*
 197  * Returns 1 if 'msg' is for a REPLY OK
 198  * Otherwise returns 0.
 199  */
 200 extern int afb_wsj1_msg_is_reply_ok(struct afb_wsj1_msg *msg);
 201
 202 /*
 203  * Returns 1 if 'msg' is for a REPLY ERROR
 204  * Otherwise returns 0.
 205  */
 206 extern int afb_wsj1_msg_is_reply_error(struct afb_wsj1_msg *msg);
 207
 208 /*
 209  * Returns 1 if 'msg' is for an EVENT
 210  * Otherwise returns 0.
 211  */
 212 extern int afb_wsj1_msg_is_event(struct afb_wsj1_msg *msg);
 213
 214 /*
 215  * Returns the api of the call for 'msg'
 216  * Returns NULL if 'msg' is not for a CALL
 217  */
 218 extern const char *afb_wsj1_msg_api(struct afb_wsj1_msg *msg);
 219
 220 /*
 221  * Returns the verb call for 'msg'
 222  * Returns NULL if 'msg' is not for a CALL
 223  */
 224 extern const char *afb_wsj1_msg_verb(struct afb_wsj1_msg *msg);
 225
 226 /*
 227  * Returns the event name for 'msg'
 228  * Returns NULL if 'msg' is not for an EVENT
 229  */
 230 extern const char *afb_wsj1_msg_event(struct afb_wsj1_msg *msg);
 231
 232 /*
 233  * Returns the token sent with 'msg' or NULL when no token was sent.
 234  */
 235 extern const char *afb_wsj1_msg_token(struct afb_wsj1_msg *msg);
 236
 237 /*
 238  * Returns the wsj1 of 'msg'
 239  */
 240 extern struct afb_wsj1 *afb_wsj1_msg_wsj1(struct afb_wsj1_msg *msg);
 241
 242 /*
 243  * Returns the string representation of the object received with 'msg'
 244  */
 245 extern const char *afb_wsj1_msg_object_s(struct afb_wsj1_msg *msg);
 246
 247 /*
 248  * Returns the object received with 'msg'
 249  */
 250 extern struct json_object *afb_wsj1_msg_object_j(struct afb_wsj1_msg *msg);
 251