2 * Copyright (C) 2016, 2017 "IoT.bzh"
3 * Author: José Bollo <jose.bollo@iot.bzh>
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
9 * http://www.apache.org/licenses/LICENSE-2.0
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.
27 * Interface for callback functions.
28 * The received closure is the closure passed when creating the afb_wsj1
29 * socket using afb_wsj1_create.
33 * This function is called on hangup.
34 * Receives the 'closure' and the handle 'wsj1'
36 void (*on_hangup)(void *closure, struct afb_wsj1 *wsj1);
39 * This function is called on incoming call.
40 * Receives the 'closure'
42 void (*on_call)(void *closure, const char *api, const char *verb, struct afb_wsj1_msg *msg);
45 * This function is called on incoming event
47 void (*on_event)(void *closure, const char *event, struct afb_wsj1_msg *msg);
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.
57 extern struct afb_wsj1 *afb_wsj1_create(struct sd_event *eloop, int fd, struct afb_wsj1_itf *itf, void *closure);
60 * Increases by one the count of reference to 'wsj1'
62 extern void afb_wsj1_addref(struct afb_wsj1 *wsj1);
65 * Decreases by one the count of reference to 'wsj1'
66 * and if it falls to zero releases the used resources
69 extern void afb_wsj1_unref(struct afb_wsj1 *wsj1);
72 * Sends a close message to the websocket of 'wsj1'.
73 * The close message is sent with the 'code' and 'text'.
75 * Return 0 in case of success. Otherwise, returns -1 and set errno.
77 extern int afb_wsj1_close(struct afb_wsj1 *wsj1, uint16_t code, const char *text);
80 * Sends on 'wsj1' the event of name 'event' with the
81 * data 'object'. If not NULL, 'object' should be a valid
83 * Return 0 in case of success. Otherwise, returns -1 and set errno.
85 extern int afb_wsj1_send_event_s(struct afb_wsj1 *wsj1, const char *event, const char *object);
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.
93 extern int afb_wsj1_send_event_j(struct afb_wsj1 *wsj1, const char *event, struct json_object *object);
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.
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);
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.
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);
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.
120 extern int afb_wsj1_reply_s(struct afb_wsj1_msg *msg, const char *object, const char *token, int iserror);
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.
129 extern int afb_wsj1_reply_j(struct afb_wsj1_msg *msg, struct json_object *object, const char *token, int iserror);
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.
136 static inline int afb_wsj1_reply_ok_s(struct afb_wsj1_msg *msg, const char *object, const char *token)
138 return afb_wsj1_reply_s(msg, object, token, 0);
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.
147 static inline int afb_wsj1_reply_ok_j(struct afb_wsj1_msg *msg, struct json_object *object, const char *token)
149 return afb_wsj1_reply_j(msg, object, token, 0);
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.
157 static inline int afb_wsj1_reply_error_s(struct afb_wsj1_msg *msg, const char *object, const char *token)
159 return afb_wsj1_reply_s(msg, object, token, 1);
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.
168 static inline int afb_wsj1_reply_error_j(struct afb_wsj1_msg *msg, struct json_object *object, const char *token)
170 return afb_wsj1_reply_j(msg, object, token, 1);
174 * Increases by one the count of reference to 'msg'.
175 * Should be called if callbacks stores the message.
177 extern void afb_wsj1_msg_addref(struct afb_wsj1_msg *msg);
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.
185 extern void afb_wsj1_msg_unref(struct afb_wsj1_msg *msg);
188 * Returns 1 if 'msg' is for a CALL
189 * Otherwise returns 0.
191 extern int afb_wsj1_msg_is_call(struct afb_wsj1_msg *msg);
194 * Returns 1 if 'msg' is for a REPLY of any kind
195 * Otherwise returns 0.
197 extern int afb_wsj1_msg_is_reply(struct afb_wsj1_msg *msg);
200 * Returns 1 if 'msg' is for a REPLY OK
201 * Otherwise returns 0.
203 extern int afb_wsj1_msg_is_reply_ok(struct afb_wsj1_msg *msg);
206 * Returns 1 if 'msg' is for a REPLY ERROR
207 * Otherwise returns 0.
209 extern int afb_wsj1_msg_is_reply_error(struct afb_wsj1_msg *msg);
212 * Returns 1 if 'msg' is for an EVENT
213 * Otherwise returns 0.
215 extern int afb_wsj1_msg_is_event(struct afb_wsj1_msg *msg);
218 * Returns the api of the call for 'msg'
219 * Returns NULL if 'msg' is not for a CALL
221 extern const char *afb_wsj1_msg_api(struct afb_wsj1_msg *msg);
224 * Returns the verb call for 'msg'
225 * Returns NULL if 'msg' is not for a CALL
227 extern const char *afb_wsj1_msg_verb(struct afb_wsj1_msg *msg);
230 * Returns the event name for 'msg'
231 * Returns NULL if 'msg' is not for an EVENT
233 extern const char *afb_wsj1_msg_event(struct afb_wsj1_msg *msg);
236 * Returns the token sent with 'msg' or NULL when no token was sent.
238 extern const char *afb_wsj1_msg_token(struct afb_wsj1_msg *msg);
241 * Returns the wsj1 of 'msg'
243 extern struct afb_wsj1 *afb_wsj1_msg_wsj1(struct afb_wsj1_msg *msg);
246 * Returns the string representation of the object received with 'msg'
248 extern const char *afb_wsj1_msg_object_s(struct afb_wsj1_msg *msg);
251 * Returns the object received with 'msg'
253 extern struct json_object *afb_wsj1_msg_object_j(struct afb_wsj1_msg *msg);