1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
/*
* Copyright (c) 2014-2017 Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License
*/
/**
* @file src/include/cynara-agent.h
* @author Adam Malinowski <a.malinowsk2@partner.samsung.com>
* @author Oskar Switalski <o.switalski@samsung.com>
* @version 1.0
* @brief This file contains agent APIs available with libcynara-agent.
*/
#ifndef CYNARA_AGENT_H
#define CYNARA_AGENT_H
#include <stdint.h>
#include <cynara/cynara-error.h>
#ifdef __cplusplus
extern "C" {
#endif
typedef uint16_t cynara_agent_req_id;
typedef struct cynara_agent cynara_agent;
/**
* \enum cynara_agent_msg_type
* Values specifying type of message.
*
* \var cynara_agent_msg_type::CYNARA_MSG_TYPE_ACTION
* Message of this type indicates its content is a request for performing an action or response to
* such request.
*
* \var cynara_agent_msg_type::CYNARA_MSG_TYPE_CANCEL
* Message of this type indicates its content is a request for canceling action or response to such
* request.
*/
typedef enum {
CYNARA_MSG_TYPE_ACTION,
CYNARA_MSG_TYPE_CANCEL
} cynara_agent_msg_type;
/**
* \par Description:
* Initialize cynara-agent structure.
* Create structure used in following API calls.
*
* \par Purpose:
* This API must be used prior to calling other agent API functions.
*
* \par Typical use case:
* Once before other agent API functions are called.
*
* \par Method of function operation:
* This API initializes inner library structures and in case of success returns cynara_agent
* structure.
*
* \par Sync (or) Async:
* This is a synchronous API.
*
* \par Thread safety:
* This function is NOT thread safe. If functions from described API are called by multithreaded
* application from different threads, they must be put into protected critical section.
*
* \par Important notes:
* Structure cynara_agent created by this function should be released with cynara_agent_finish().
*
* \param[out] pp_cynara_agent Place holder for created cynara_agent structure.
* \param[in] p_agent_type Type (name) of agent used by cynara for communication agent<->plugin.
*
* \return CYNARA_API_SUCCESS on success, or error code on error.
*/
int cynara_agent_initialize(cynara_agent **pp_cynara_agent, const char *p_agent_type);
/**
* \par Description:
* Destroy structure created with cynara_agent_initialize().
*
* \par Purpose:
* This API should be used to clean up after usage of cynara-agent library.
*
* \par Typical use case:
* Once after connection to cynara is not needed.
*
* \par Method of function operation:
* This API releases inner library structure and destroys cynara_agent structure. Connection to
* cynara service is closed.
*
* \par Sync (or) Async:
* This is a synchronous API.
*
* \par Thread safety:
* This function is NOT thread-safe. If functions from described API are called by multithreaded
* application from different threads, they must be put into protected critical section.
*
* \par Important notes:
* No other call to cynara-agent library should be made after call to cynara_agent_finish() except
* cynara_agent_initialize().
*
* \param[in] p_cynara_agent cynara_agent structure. If NULL, then the call has no effect.
*/
int cynara_agent_finish(cynara_agent *p_cynara_agent);
/**
* \par Description:
* Get request from cynara service.
*
* \par Purpose:
* This API should be used to get request from cynara service. Request is generated by corresponding
* plugin loaded into cynara service.
*
* \par Typical use case:
* Agent waits for request from cynara service. Request may be either ask for performing agent
* specific action or ask for canceling such action. Agent calls this function when is ready to
* perform or cancel an action.
*
* \par Method of function operation:
* \parblock
* Function reads data incoming from cynara service and if at least one complete request is ready
* then returns with CYNARA_API_SUCCESS code. Request type, request id and specific
* plugin data are stored in given arguments. Function returns exactly one request. If there are
* more then one requests ready to get then one must call this function multiple times.
*
* This function is blocking which means that if there is no request from cynara service it will not
* return. On success, buffer for plugin specific data is allocated and size is set. Developer is
* responsible for freeing this memory using free() function.
* \endparblock
*
* \par Sync (or) Async:
* This is a synchronous API.
*
* \par Thread safety:
* This function is NOT thread safe. If functions from described API are called by multithreaded
* application from different threads, they must be put into protected critical section.
*
* \par Important notes:
* \parblock
* Call to cynara_agent_get_request() needs cynara_agent structure to be created first.
* Use cynara_agent_initialize() before calling this function.
*
* After CYNARA_API_ACCESS_DENIED error is returned agent should be terminated or at least should
* not invoke neither cynara_agent_get_request() nor cynara_agent_put_response() functions.
* \endparblock
*
* \param[in] p_cynara_agent cynara_agent structure.
* \param[out] req_type Request type, demand an action or cancel this action.
* \param[out] req_id Request identifier used to pair with answer #cynara_agent_put_response() and
* cancel request.
* \param[out] data Plugin specific data. Buffer is allocated in this function and developer is
* responsible for freeing it using free() function. Buffer is filled with data
* from corresponding plugin. If there is no enough memory for data
* CYNARA_API_OUT_OF_MEMORY is returned and all arguments remain untouched.
* \param[out] data_size Size of plugin data (bytes count). In case of out of memory this value
* stays untouched.
*
* \return CYNARA_API_SUCCESS on successfully read request,
* CYNARA_API_INTERRUPTED when cynara_agent_cancel_waiting() is called during waiting,
* or negative error code otherwise.
*/
int cynara_agent_get_request(cynara_agent *p_cynara_agent, cynara_agent_msg_type *req_type,
cynara_agent_req_id *req_id, void **data, size_t *data_size);
/**
* \par Description:
* Send response to cynara service.
*
* \par Purpose:
* This API should be used to send response to cynara service.
*
* \par Typical use case:
* Agent calls this function when is ready to answer request for action or cancel request.
*
* \par Method of function operation:
* Function sends data to cynara service. Data contains answer for previously got question.
* Answer may be of type CYNARA_MSG_TYPE_ACTION or CYNARA_MSG_TYPE_CANCEL. Type is
* CYNARA_MSG_TYPE_ACTION when request for an action was processed and answer is ready, or
* CYNARA_MSG_TYPE_CANCEL when processing request for an action was interrupted by cancel request.
* Agent must send exactly one response per one request and cancel. If request is processed before
* cancel message arrives the agent sends action response. If cancel arrives before action request
* is processed then agent sends cancel response and drops processing related action.
* Request id in response must be the same as request id in corresponding request.
*
* \par Sync (or) Async:
* This is a synchronous API.
*
* \par Thread safety:
* This function is NOT thread safe. If functions from described API are called by multithreaded
* application from different threads, they must be put into protected critical section.
*
* \par Important notes:
* Call to cynara_agent_get_request() needs cynara_agent structure to be created first.
* Use cynara_agent_initialize() before calling this function. Also successful call to
* cynara_agent_get_request() is needed before calling this function.
*
* \param[in] p_cynara_agent cynara_agent structure.
* \param[in] resp_type Response type - see Method of operation for details.
* \param[in] req_id Request identifier obtained from request.
* \param[in] data Plugin specific data. If necessary agent should fill this buffer with data
* directed to plugin.
* \param[in] data_size Size of plugin data (bytes count).
*
* \return CYNARA_API_SUCCESS on successfully read request, or negative error code otherwise.
*/
int cynara_agent_put_response(cynara_agent *p_cynara_agent, const cynara_agent_msg_type resp_type,
const cynara_agent_req_id req_id, const void *data,
const size_t data_size);
/**
* \par Description:
* Break from waiting for cynara service request using cynara_agent_get_request().
*
* \par Purpose:
* This API should be used when cynara_agent_get_request() is blocked and before calling
* cynara_agent_finish().
*
* \par Typical use case:
* Agent calls this API, when it wants to gracefully quit.
*
* \par Method of function operation:
* Function notifies cynara_agent_get_request() to stop waiting for request from cynara.
* Then cynara_agent_get_request() returns CYNARA_API_INTERRUPTED and no request is fetched.
*
* \par Sync (or) Async:
* This is a synchronous API.
*
* \par Thread safety:
* This function can be used only together with cynara_agent_get_request(), otherwise should
* be treaded as NOT thread safe.
*
* \par Important notes:
* Call to cynara_agent_cancel_waiting() needs cynara_agent structure to be created first and
* cynara_agent_get_request() running.
* Use cynara_agent_initialize() before calling this function.
*
* \param[in] p_cynara_agent cynara_agent structure.
* \return CYNARA_API_SUCCESS on successful waiting cancel, or negative error code otherwise.
*/
int cynara_agent_cancel_waiting(cynara_agent *p_cynara_agent);
#ifdef __cplusplus
}
#endif
#endif /* CYNARA_AGENT_H */
|
