src/afb-wsj1.h

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