src/afb-wsj1.h

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