commotion.h
Go to the documentation of this file.
1 /* vim: set ts=2 expandtab: */
2 /**
3  * @file commotion.h
4  * @brief Client API for the Commotion Daemon
5  *
6  * @author Josh King (jheretic), jking@chambana.net
7  *
8  * @internal
9  * Created 12/16/2013 12:00:25 PM
10  * Compiler gcc/g++
11  * Organization The Open Technology Institute
12  * Copyright Copyright (c) 2013, Josh King
13  *
14  * This file is part of Commotion, Copyright (c) 2013, Josh King
15  *
16  * Commotion is free software: you can redistribute it and/or modify
17  * it under the terms of the GNU Affero General Public License as
18  * published by the Free Software Foundation, either version 3 of the
19  * License, or (at your option) any later version.
20  *
21  * Commotion is distributed in the hope that it will be useful,
22  * but WITHOUT ANY WARRANTY; without even the implied warranty of
23  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
24  * GNU Affero General Public License for more details.
25  *
26  * You should have received a copy of the GNU Affero General Public License
27  * along with Commotion. If not, see <http://www.gnu.org/licenses/>.
28  *
29  * =====================================================================================
30  */
31 
32 #include <stdbool.h>
33 
34 #ifndef _CONNECT_H
35 #define _CONNECT_H
36 
37 #ifndef CO_OBJ_INTERNAL
38 typedef void co_obj_t;
39 #endif
40 
41 /**
42  * @brief initializes API
43  */
44 int co_init(void);
45 
46 /**
47  * @brief shuts down the API
48  */
49 int co_shutdown(void);
50 
51 /**
52  * @brief creates a connection to Commotion daemon at the given URI
53  * @param uri URI string
54  * @param ulen length of URI string
55  */
56 co_obj_t *co_connect(const char *uri, const size_t ulen);
57 
58 /**
59  * @brief closes connection to Commotion daemon
60  * @param connection context object for active connection
61  */
62 int co_disconnect(co_obj_t *connection);
63 
64 /**
65  * @brief create an API request
66  */
68 
69 /**
70  * @brief appends object to request
71  * @param request request object to append to
72  * @param object object to append
73  */
74 int co_request_append(co_obj_t *request, co_obj_t *object);
75 
76 /**
77  * @brief appends string to request
78  * @param request request object to append to
79  * @param s string to append
80  * @param slen length of string to append
81  */
82 int co_request_append_str(co_obj_t *request, const char *s, const size_t slen);
83 
84 /**
85  * @brief appends byte array to request
86  * @param request request object to append to
87  * @param s array to append
88  * @param slen length of array to append
89  */
90 int co_request_append_bin(co_obj_t *request, const char *s, const size_t slen);
91 
92 /**
93  * @brief appends int to request
94  * @param request request object to append to
95  * @param i integer to append
96  */
97 int co_request_append_int(co_obj_t *request, const int i);
98 
99 /**
100  * @brief appends unsigned int to request
101  * @param request request object to append to
102  * @param i integer to append
103  */
104 int co_request_append_uint(co_obj_t *request, const unsigned int i);
105 
106 /**
107  * @brief sense procedure call to daemon
108  * @param connection context object for connection
109  * @param response pointer to response buffer
110  * @param method method name
111  * @param mlen length of method name
112  * @param request request object to send
113  */
114 int co_call(co_obj_t *connection, co_obj_t **response, const char *method, const size_t mlen, co_obj_t *request);
115 
116 /**
117  * @brief retrieve object from response
118  * @param response pointer to response object
119  * @param key identifier for response element to retrieve
120  * @param klen length of key name
121  */
122 co_obj_t *co_response_get(co_obj_t *response, const char *key, const size_t klen);
123 
124 /**
125  * @brief retrieve string from response
126  * @param response pointer to response object
127  * @param output pointer to output buffer
128  * @param key identifier for response element to retrieve
129  * @param klen length of key name
130  */
131 size_t co_response_get_str(co_obj_t *response, char **output, const char *key, const size_t klen);
132 
133 /**
134  * @brief retrieve byte array from response
135  * @param response pointer to response object
136  * @param output pointer to output buffer
137  * @param key identifier for response element to retrieve
138  * @param klen length of key name
139  */
140 size_t co_response_get_bin(co_obj_t *response, char **output, const char *key, const size_t klen);
141 
142 /**
143  * @brief retrieve unsigned int from response
144  * @param response pointer to response object
145  * @param output pointer to output buffer
146  * @param key identifier for response element to retrieve
147  * @param klen length of key name
148  */
149 int co_response_get_uint(co_obj_t *response, unsigned long *output, const char *key, const size_t klen);
150 
151 /**
152  * @brief retrieve signed int from response
153  * @param response pointer to response object
154  * @param output pointer to output buffer
155  * @param key identifier for response element to retrieve
156  * @param klen length of key name
157  */
158 int co_response_get_int(co_obj_t *response, signed long *output, const char *key, const size_t klen);
159 
160 /**
161  * @brief retrieve bool from response
162  * @param response pointer to response object
163  * @param output pointer to output buffer
164  * @param key identifier for response element to retrieve
165  * @param klen length of key name
166  */
167 int co_response_get_bool(co_obj_t *response, bool *output, const char *key, const size_t klen);
168 
169 /**
170  * @brief print response object
171  * @param response pointer to response object
172  */
173 int co_response_print(co_obj_t *response);
174 
175 /**
176  * @brief free API objects
177  * @param object object to free
178  */
179 void co_free(co_obj_t *object);
180 #endif
int co_request_append_bin(co_obj_t *request, const char *s, const size_t slen)
appends byte array to request
Definition: commotion.c:144
int co_response_get_bool(co_obj_t *response, bool *output, const char *key, const size_t klen)
retrieve bool from response
Definition: commotion.c:331
void co_free(co_obj_t *object)
free API objects
Definition: commotion.c:362
co_obj_t * co_request_create(void)
create an API request
Definition: commotion.c:113
int co_response_print(co_obj_t *response)
print response object
Definition: commotion.c:353
int co_request_append(co_obj_t *request, co_obj_t *object)
appends object to request
Definition: commotion.c:119
size_t co_response_get_bin(co_obj_t *response, char **output, const char *key, const size_t klen)
retrieve byte array from response
Definition: commotion.c:262
int co_call(co_obj_t *connection, co_obj_t **response, const char *method, const size_t mlen, co_obj_t *request)
sense procedure call to daemon
Definition: commotion.c:186
int co_request_append_int(co_obj_t *request, const int i)
appends int to request
Definition: commotion.c:158
size_t co_response_get_str(co_obj_t *response, char **output, const char *key, const size_t klen)
retrieve string from response
Definition: commotion.c:251
Definition: obj.h:131
int co_response_get_int(co_obj_t *response, signed long *output, const char *key, const size_t klen)
retrieve signed int from response
Definition: commotion.c:302
co_obj_t * co_connect(const char *uri, const size_t ulen)
creates a connection to Commotion daemon at the given URI
Definition: commotion.c:84
int co_init(void)
initializes API
Definition: commotion.c:52
int co_shutdown(void)
shuts down the API
Definition: commotion.c:72
int co_response_get_uint(co_obj_t *response, unsigned long *output, const char *key, const size_t klen)
retrieve unsigned int from response
Definition: commotion.c:273
int co_request_append_str(co_obj_t *request, const char *s, const size_t slen)
appends string to request
Definition: commotion.c:130
co_obj_t * co_response_get(co_obj_t *response, const char *key, const size_t klen)
retrieve object from response
Definition: commotion.c:241
int co_request_append_uint(co_obj_t *request, const unsigned int i)
appends unsigned int to request
Definition: commotion.c:172
int co_disconnect(co_obj_t *connection)
closes connection to Commotion daemon
Definition: commotion.c:99