1 // Copyright (c) 2018 Samsung Electronics Co., Ltd All Rights Reserved
2 // Use of this source code is governed by a apache 2.0 license that can be
3 // found in the LICENSE file.
5 #ifndef __TIZEN_APPFW_CAPABILITY_MANAGER_H__
6 #define __TIZEN_APPFW_CAPABILITY_MANAGER_H__
15 * @file capability-manager.h
19 * @addtogroup CAPI_CAPABILITY_MANAGER_MODULE
24 * @brief Enumerations for Capability Manager Errors.
28 CAPMGR_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
29 CAPMGR_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
30 CAPMGR_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
31 CAPMGR_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR, /**< Internal I/O error */
35 * @brief Enumerations for Capability Manager app control result type.
39 CAPMGR_APP_CONTROL_RESULT_OK, /**< Successful */
40 } capmgr_app_control_result_e;
43 * @brief Capability Manager device handle.
46 typedef struct capmgr_device_s* capmgr_device_h;
49 * @brief Capability Manager app control handle.
52 typedef struct capmgr_app_control_s* capmgr_app_control_h;
55 * @brief Capability Manager package info handle.
58 typedef struct capmgr_package_info_s* capmgr_package_info_h;
61 * @brief Called to retrieve information of devices currently discovered.
64 * @remarks The @a device can be used only in the callback. To use outside, make a copy.
65 * @param[in] device Device handle
66 * @param[in] user_data The user data to be passed to the callback function
67 * @see capmgr_device_foreach_devices()
69 typedef int (*capmgr_device_foreach_cb)(const capmgr_device_h device,
73 * @brief Called when send app control request has finished.
76 * @remarks The @a request, @reply can be used only in the callback. To use outside, make a copy.
77 * @param[in] request Capability Manager app control handle contains data to be sent
78 * @param[in] reply Capability Manager app control handle which contains
80 * @param[in] result App control send result
81 * @param[in] user_data The user data to be passed to the callback function
82 * @see capmgr_app_control_send()
84 typedef int (*capmgr_app_control_reply_cb)(const capmgr_app_control_h request,
85 const capmgr_app_control_h reply, capmgr_app_control_result_e result,
89 * @brief Called for each remote package info.
92 * @remarks The @a remote_package_info can be used only in the callback. To use outside, make a copy.
93 * @param[in] remote_package_info Capability Manager package info handle
94 * @param[in] user_data The user data to be passed to the callback function
95 * @see capmgr_package_info_foreach_packages()
97 typedef int (*capmgr_package_info_foreach_package_cb)(
98 const capmgr_package_info_h remote_package_info, void* user_data);
101 * @brief Called for each application of remote package.
104 * @remarks The @a appid can be used only in the callback. To use outside, make a copy.
105 * @param[in] appid Application ID of remote application
106 * @param[in] user_data The user data to be passed to the callback function
107 * @see capmgr_package_info_foreach_applications()
109 typedef int (*capmgr_package_info_foreach_app_cb)(
110 const char* appid, void* user_data);
113 * @brief Retrieves all remote device info stored on local device.
116 * @param[in] cb The callback function to invoke
117 * @param[in] user_data The user data to be passed to the callback function
118 * @return @c 0 on success,
119 * otherwise a negative error value
120 * @retval #CAPMGR_ERROR_NONE Successful
121 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
122 * @retval #CAPMGR_ERROR_IO_ERROR Internal I/O error
123 * @post This function invokes capmgr_device_foreach_cb() for each remote device information.
124 * @see capmgr_device_foreach_cb()
127 int capmgr_device_foreach_devices(capmgr_device_foreach_cb cb,
131 * @brief Clones the remote device information handle.
133 * @param[in] device The remote device handle
134 * @param[out] device_clone A newly created remote device information handle, if successfully cloned
135 * @return @c 0 on success,
136 * otherwise a negative error value
137 * @retval #CAPMGR_ERROR_NONE Successful
138 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
139 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
141 int capmgr_device_clone(const capmgr_device_h device,
142 capmgr_device_h* device_clone);
145 * @brief Destroys the remote device information handle and releases all its resources.
147 * @param[in] device The remote device information handle
148 * @return @c 0 on success,
149 * otherwise a negative error value
150 * @retval #CAPMGR_ERROR_NONE Successful
151 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
152 * @see capmgr_device_clone()
153 * @see capmgr_device_foreach_devices()
155 int capmgr_device_destroy(capmgr_device_h device);
158 * @brief Gets the device ID with the given remote device context.
160 * @remarks You must release @a device_id using free().
161 * @param[in] device The remote device information handle
162 * @param[out] device_id The remote device ID of the given remote device context
163 * @return @c 0 on success,
164 * otherwise a negative error value
165 * @retval #CAPMGR_ERROR_NONE Successful
166 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
167 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
168 * @see capmgr_device_clone()
169 * @see capmgr_device_foreach_devices()
171 int capmgr_device_get_device_id(capmgr_device_h device, char** device_id);
174 * @brief Gets the model name with the given remote device context.
176 * @remarks You must release @a model_name using free().
177 * @param[in] device The remote device information handle
178 * @param[out] model_name The model name of the given remote device context
179 * @return @c 0 on success,
180 * otherwise a negative error value
181 * @retval #CAPMGR_ERROR_NONE Successful
182 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
183 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
184 * @see capmgr_device_clone()
185 * @see capmgr_device_foreach_devices()
187 int capmgr_device_get_model_name(capmgr_device_h device, char** model_name);
190 * @brief Gets the device name with the given remote device context.
192 * @remarks You must release @a device_name using free().
193 * @param[in] device The remote device information handle
194 * @param[out] device_name The device name of the given remote device context
195 * @return @c 0 on success,
196 * otherwise a negative error value
197 * @retval #CAPMGR_ERROR_NONE Successful
198 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
199 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
200 * @see capmgr_device_clone()
201 * @see capmgr_device_foreach_devices()
203 int capmgr_device_get_device_name(capmgr_device_h device, char** device_name);
206 * @brief Gets the platform verion with the given remote device context.
208 * @remarks You must release @a platform_ver using free().
209 * @param[in] device The remote device information handle
210 * @param[out] platform_ver The platform version of the given remote device context
211 * @return @c 0 on success,
212 * otherwise a negative error value
213 * @retval #CAPMGR_ERROR_NONE Successful
214 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
215 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
216 * @see capmgr_device_clone()
217 * @see capmgr_device_foreach_devices()
219 int capmgr_device_get_platform_ver(capmgr_device_h device, char** platform_ver);
222 * @brief Gets the profile with the given remote device context.
224 * @remarks You must release @a profile using free().
225 * @param[in] device The remote device information handle
226 * @param[out] profile The profile value of the given remote device context
227 * @return @c 0 on success,
228 * otherwise a negative error value
229 * @retval #CAPMGR_ERROR_NONE Successful
230 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
231 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
232 * @see capmgr_device_clone()
233 * @see capmgr_device_foreach_devices()
235 int capmgr_device_get_profile(capmgr_device_h device, char** profile);
238 * @brief Gets the software verion with the given remote device context.
240 * @remarks You must release @a sw_ver using free().
241 * @param[in] device The remote device information handle
242 * @param[out] sw_ver The software version of the given remote device context
243 * @return @c 0 on success,
244 * otherwise a negative error value
245 * @retval #CAPMGR_ERROR_NONE Successful
246 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
247 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
248 * @see capmgr_device_clone()
249 * @see capmgr_device_foreach_devices()
251 int capmgr_device_get_sw_ver(capmgr_device_h device, char** sw_ver);
254 * @brief Creates a remote app control handle.
256 * @remarks You must release @a app_control using capmgr_app_control_destroy().
258 * @param[out] app_control The remote app control handle that is newly created on success
260 * @return @c 0 on success,
261 * otherwise a negative error value
263 * @retval #CAPMGR_ERROR_NONE Successful
264 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
265 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
266 * @see capmgr_app_control_destroy()
268 int capmgr_app_control_create(capmgr_app_control_h* app_control);
271 * @brief Clones the remote app control handle.
273 * @param[in] app_control The remote app control handle
274 * @param[out] app_control_clone A newly created remote app control handle, if successfully cloned
275 * @return @c 0 on success,
276 * otherwise a negative error value
277 * @retval #CAPMGR_ERROR_NONE Successful
278 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
279 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
281 int capmgr_app_control_clone(const capmgr_app_control_h app_control,
282 capmgr_app_control_h* app_control_clone);
285 * @brief Destroys the remote app control handle and releases all its resources.
287 * @param[in] app_control The remote app control handle
288 * @return @c 0 on success,
289 * otherwise a negative error value
290 * @retval #CAPMGR_ERROR_NONE Successful
291 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
292 * @see capmgr_app_control_create()
294 int capmgr_app_control_destroy(capmgr_app_control_h app_control);
297 * @brief Gets the remote device handle from the given app control context.
299 * @remarks You must release @a device using capmgr_device_destroy().
300 * @param[in] app_control The remote app control handle
301 * @param[out] device The remote device handle
302 * @return @c 0 on success,
303 * otherwise a negative error value
304 * @retval #CAPMGR_ERROR_NONE Successful
305 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
306 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
307 * @see capmgr_app_control_destroy()
309 int capmgr_app_control_get_device(capmgr_app_control_h app_control,
310 capmgr_device_h* device);
313 * @brief Gets the operation value from the given remote app control context.
315 * @remarks You must release @a operation using free().
316 * @param[in] app_control The remote app control handle
317 * @param[out] operation The operation value
318 * @return @c 0 on success,
319 * otherwise a negative error value
320 * @retval #CAPMGR_ERROR_NONE Successful
321 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
322 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
323 * @see capmgr_app_control_destroy()
325 int capmgr_app_control_get_operation(capmgr_app_control_h app_control,
329 * @brief Gets the URI value from the given remote app control context.
331 * @remarks You must release @a uri using free().
332 * @param[in] app_control The remote app control handle
333 * @param[out] uri The URI value
334 * @return @c 0 on success,
335 * otherwise a negative error value
336 * @retval #CAPMGR_ERROR_NONE Successful
337 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
338 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
339 * @see capmgr_app_control_destroy()
341 int capmgr_app_control_get_uri(capmgr_app_control_h app_control,
345 * @brief Gets the MIME value from the given remote app control context.
347 * @remarks You must release @a mime using free().
348 * @param[in] app_control The remote app control handle
349 * @param[out] mime The MIME value
350 * @return @c 0 on success,
351 * otherwise a negative error value
352 * @retval #CAPMGR_ERROR_NONE Successful
353 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
354 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
355 * @see capmgr_app_control_destroy()
357 int capmgr_app_control_get_mime(capmgr_app_control_h app_control,
361 * @brief Gets the application ID from the given remote app control context.
363 * @remarks You must release @a appid using free().
364 * @param[in] app_control The remote app control handle
365 * @param[out] appid The application ID
366 * @return @c 0 on success,
367 * otherwise a negative error value
368 * @retval #CAPMGR_ERROR_NONE Successful
369 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
370 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
371 * @see capmgr_app_control_destroy()
373 int capmgr_app_control_get_appid(capmgr_app_control_h app_control,
377 * @brief Gets the extra data corresponding to given key from remote app control context.
379 * @remarks You must release @a value using free().
380 * @param[in] app_control The remote app control handle
381 * @param[in] key The key value
382 * @param[out] value The value related with given key
383 * @return @c 0 on success,
384 * otherwise a negative error value
385 * @retval #CAPMGR_ERROR_NONE Successful
386 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
387 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
388 * @see capmgr_app_control_destroy()
390 int capmgr_app_control_get_extra_data(capmgr_app_control_h app_control,
391 const char* key, char** value);
394 * @brief Sets the target remote device to given remote app control context.
396 * @param[in] app_control The remote app control handle
397 * @param[in] device The remote device handle to set
398 * @return @c 0 on success,
399 * otherwise a negative error value
400 * @retval #CAPMGR_ERROR_NONE Successful
401 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
402 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
404 int capmgr_app_control_set_device(capmgr_app_control_h app_control,
405 const capmgr_device_h device);
408 * @brief Sets the operation value to given remote app control context.
410 * @param[in] app_control The remote app control handle
411 * @param[in] operation The operation value to set
412 * @return @c 0 on success,
413 * otherwise a negative error value
414 * @retval #CAPMGR_ERROR_NONE Successful
415 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
416 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
418 int capmgr_app_control_set_operation(capmgr_app_control_h app_control,
419 const char* operation);
422 * @brief Sets the URI value to given remote app control context.
424 * @param[in] app_control The remote app control handle
425 * @param[in] uri The URI value to set
426 * @return @c 0 on success,
427 * otherwise a negative error value
428 * @retval #CAPMGR_ERROR_NONE Successful
429 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
430 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
432 int capmgr_app_control_set_uri(capmgr_app_control_h app_control,
436 * @brief Sets the MIME value to given remote app control context.
438 * @param[in] app_control The remote app control handle
439 * @param[in] mime The MIME value to set
440 * @return @c 0 on success,
441 * otherwise a negative error value
442 * @retval #CAPMGR_ERROR_NONE Successful
443 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
444 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
446 int capmgr_app_control_set_mime(capmgr_app_control_h app_control,
450 * @brief Sets the application ID to given remote app control context.
452 * @param[in] app_control The remote app control handle
453 * @param[in] appid The application ID to set
454 * @return @c 0 on success,
455 * otherwise a negative error value
456 * @retval #CAPMGR_ERROR_NONE Successful
457 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
458 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
460 int capmgr_app_control_set_appid(capmgr_app_control_h app_control,
464 * @brief Sets the extra data to given remote app control context.
466 * @param[in] app_control The remote app control handle
467 * @param[in] key The key of extra data to set
468 * @param[in] value The value corresponding to key.
469 * @return @c 0 on success,
470 * otherwise a negative error value
471 * @retval #CAPMGR_ERROR_NONE Successful
472 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
473 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
475 int capmgr_app_control_add_extra_data(capmgr_app_control_h app_control,
476 const char* key, const char* value);
479 * @brief Removes the extra data corresponding to given key at remote app control context.
481 * @param[in] app_control The remote app control handle
482 * @param[in] key The key of extra data to remove
483 * @return @c 0 on success,
484 * otherwise a negative error value
485 * @retval #CAPMGR_ERROR_NONE Successful
486 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
487 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
489 int capmgr_app_control_remove_extra_data(capmgr_app_control_h app_control,
493 * @brief Sends the app control to remote device specified at handle.
495 * @param[in] app_control The remote app control handle
496 * @param[in] cb Callback to be invoked when send has done
497 * @param[in] user_data The user data to be passed to the callback function
498 * @return @c 0 on success,
499 * otherwise a negative error value
500 * @retval #CAPMGR_ERROR_NONE Successful
501 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
502 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
504 int capmgr_app_control_send(capmgr_app_control_h app_control,
505 capmgr_app_control_reply_cb cb, void* user_data);
508 * @brief Retrieves all packages installed at specified remote device and invoke callback each of it.
510 * @param[in] device The remote device handle
511 * @param[in] cb Callback to be invoked for each package
512 * @param[in] user_data The user data to be passed to the callback function
513 * @return @c 0 on success,
514 * otherwise a negative error value
515 * @retval #CAPMGR_ERROR_NONE Successful
516 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
517 * @retval #CAPMGR_ERROR_IO_ERROR I/O error
518 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
520 int capmgr_package_info_foreach_packages(const capmgr_device_h device,
521 capmgr_package_info_foreach_package_cb cb, void* user_data);
524 * @brief Retrieves all applications belongs to given package and invoke callback each of it.
526 * @param[in] remote_package_info The package information installed at specific remote device
527 * @param[in] cb Callback to be invoked for each application
528 * @param[in] user_data The user data to be passed to the callback function
529 * @return @c 0 on success,
530 * otherwise a negative error value
531 * @retval #CAPMGR_ERROR_NONE Successful
532 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
533 * @retval #CAPMGR_ERROR_IO_ERROR I/O error
534 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
536 int capmgr_package_info_foreach_applications(
537 const capmgr_package_info_h remote_package_info,
538 capmgr_package_info_foreach_app_cb cb, void* user_data);
541 * @brief Gets the package ID from given remote package information.
543 * @remarks You must release @a pkgid using free().
544 * @param[in] remote_package_info The package information installed at specific remote device
545 * @param[in] pkgid The package ID
546 * @return @c 0 on success,
547 * otherwise a negative error value
548 * @retval #CAPMGR_ERROR_NONE Successful
549 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
550 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
552 int capmgr_package_info_get_pkgid(capmgr_package_info_h remote_package_info,
556 * @brief Gets the label from given remote package information.
558 * @remarks You must release @a label using free().
559 * @param[in] remote_package_info The package information installed at specific remote device
560 * @param[in] label The label of package
561 * @return @c 0 on success,
562 * otherwise a negative error value
563 * @retval #CAPMGR_ERROR_NONE Successful
564 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
565 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
567 int capmgr_package_info_get_label(capmgr_package_info_h remote_package_info,
571 * @brief Gets the version from given remote package information.
573 * @remarks You must release @a version using free().
574 * @param[in] remote_package_info The package information installed at specific remote device
575 * @param[in] version The version of package
576 * @return @c 0 on success,
577 * otherwise a negative error value
578 * @retval #CAPMGR_ERROR_NONE Successful
579 * @retval #CAPMGR_ERROR_INVALID_PARAMETER Invalid parameter
580 * @retval #CAPMGR_ERROR_OUT_OF_MEMORY Out of memory
582 int capmgr_package_info_get_version(capmgr_package_info_h remote_package_info,
589 #endif // __TIZEN_APPFW_CAPABILITY_MANAGER_H__