2 * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
4 * Contact: Mateusz Malicki <m.malicki2@samsung.com>
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License
22 * @author Mateusz Malicki (m.malicki2@samsung.com)
23 * @brief This file contains the public API for Vasum Client
28 #include "client/vasum-client.h"
30 int main(int argc, char** argv)
34 VsmArrayString values = NULL;
37 status = vsm_start_glib_loop(); // start glib loop (if not started any yet)
38 if (VSMCLIENT_SUCCESS != status) {
43 client = vsm_client_create(); // create client handle
50 status = vsm_connect(client); // connect to dbus
51 if (VSMCLIENT_SUCCESS != status) {
57 status = vsm_get_zone_ids(client, &values);
58 if (VSMCLIENT_SUCCESS != status) {
65 for (VsmArrayString iValues = values; *iValues; iValues++) {
66 printf("%s\n", *iValues);
70 vsm_array_string_free(values); // free memory
71 vsm_client_free(client); // destroy client handle
72 vsm_stop_glib_loop(); // stop the glib loop (use only with vsm_start_glib_loop)
78 #ifndef VASUM_CLIENT_H
79 #define VASUM_CLIENT_H
90 * vasum-server's client pointer.
92 typedef void* VsmClient;
95 * NULL-terminated string type.
97 * @sa vsm_array_string_free
99 typedef char* VsmString;
102 * NULL-terminated array of strings type.
104 * @sa vsm_string_free
106 typedef VsmString* VsmArrayString;
109 * Completion status of communication function.
112 VSMCLIENT_CUSTOM_ERROR, ///< User specified error
113 VSMCLIENT_IO_ERROR, ///< Input/Output error
114 VSMCLIENT_OPERATION_FAILED, ///< Operation failed
115 VSMCLIENT_INVALID_ARGUMENT, ///< Invalid argument
116 VSMCLIENT_OTHER_ERROR, ///< Other error
117 VSMCLIENT_SUCCESS ///< Success
123 typedef unsigned int VsmSubscriptionId;
143 * Zone information structure
155 typedef VsmZoneStructure* VsmZone;
158 * Netowrk device type
167 * Network device information structure
172 } VsmNetdevStructure;
175 * Network device information
177 typedef VsmNetdevStructure* VsmNetdev;
191 * Do not call this function if an application creates a glib loop itself.
192 * Otherwise, call it before any other function from this library.
194 * @return status of this function call
196 VsmStatus vsm_start_glib_loop();
201 * Call only if vsm_start_glib_loop() was called.
203 * @return status of this function call
205 VsmStatus vsm_stop_glib_loop();
208 * Create a new vasum-server's client.
210 * @return Created client pointer or NULL on failure.
212 VsmClient vsm_client_create();
215 * Release client resources.
217 * @param[in] client vasum-server's client
219 void vsm_client_free(VsmClient client);
222 * Get status code of last vasum-server communication.
224 * @param[in] client vasum-server's client
225 * @return status of this function call
227 VsmStatus vsm_get_status(VsmClient client);
230 * Get status message of the last vasum-server communication.
232 * @param[in] client vasum-server's client
233 * @return last status message from vasum-server communication
235 const char* vsm_get_status_message(VsmClient client);
238 * Connect client to the vasum-server.
240 * @param[in] client vasum-server's client
241 * @return status of this function call
243 VsmStatus vsm_connect(VsmClient client);
246 * Connect client to the vasum-server via custom address.
248 * @param[in] client vasum-server's client
249 * @param[in] address dbus address
250 * @return status of this function call
252 VsmStatus vsm_connect_custom(VsmClient client, const char* address);
255 * Release VsmArrayString.
257 * @param[in] astring VsmArrayString
259 void vsm_array_string_free(VsmArrayString astring);
264 * @param string VsmString
266 void vsm_string_free(VsmString string);
271 * @param zone VsmZone
273 void vsm_zone_free(VsmZone zone);
278 * @param netdev VsmNetdev
280 void vsm_netdev_free(VsmNetdev netdev);
285 * Functions using org.tizen.vasum.host.manager D-Bus interface.
291 * Zone's D-Bus state change callback function signature.
293 * @param[in] zoneId affected zone id
294 * @param[in] dbusAddress new D-Bus address
295 * @param data custom user's data pointer passed to vsm_add_state_callback() function
297 typedef void (*VsmZoneDbusStateCallback)(const char* zoneId,
298 const char* dbusAddress,
302 * Get dbus address of each zone.
304 * @param[in] client vasum-server's client
305 * @param[out] keys array of zones name
306 * @param[out] values array of zones dbus address
307 * @return status of this function call
308 * @post keys[i] corresponds to values[i]
309 * @remark Use vsm_array_string_free() to free memory occupied by @p keys and @p values.
311 VsmStatus vsm_get_zone_dbuses(VsmClient client, VsmArrayString* keys, VsmArrayString* values);
316 * @param[in] client vasum-server's client
317 * @param[out] array array of zones name
318 * @return status of this function call
319 * @remark Use vsm_array_string_free() to free memory occupied by @p array.
321 VsmStatus vsm_get_zone_ids(VsmClient client, VsmArrayString* array);
324 * Get active (foreground) zone name.
326 * @param[in] client vasum-server's client
327 * @param[out] id active zone name
328 * @return status of this function call
329 * @remark Use @p vsm_string_free() to free memory occupied by @p id.
331 VsmStatus vsm_get_active_zone_id(VsmClient client, VsmString* id);
334 * Get zone name of process with given pid.
336 * @param[in] client vasum-server's client
337 * @param[in] pid process id
338 * @param[out] id active zone name
339 * @return status of this function call
340 * @remark Use @p vsm_string_free() to free memory occupied by @p id.
342 VsmStatus vsm_lookup_zone_by_pid(VsmClient client, int pid, VsmString* id);
345 * Get zone informations of zone with given id.
347 * @param[in] client vasum-server's client
348 * @param[in] id zone name
349 * @param[out] zone zone informations
350 * @return status of this function call
351 * @remark Use @p vsm_zone_free() to free memory occupied by @p zone
353 VsmStatus vsm_lookup_zone_by_id(VsmClient client, const char* id, VsmZone* zone);
356 * Get zone name with given terminal.
358 * @param[in] client vasum-server's client
359 * @param[in] terminal terminal id
360 * @param[out] id zone name with given terminal
361 * @return status of this function call
362 * @remark Use @p vsm_string_free() to free memory occupied by @p id.
364 VsmStatus vsm_lookup_zone_by_terminal_id(VsmClient client, int terminal, VsmString* id);
367 * Set active (foreground) zone.
369 * @param[in] client vasum-server's client
370 * @param[in] id zone name
371 * @return status of this function call
373 VsmStatus vsm_set_active_zone(VsmClient client, const char* id);
376 * Create and add zone
378 * @param[in] client vasum-server's client
379 * @param[in] id zone id
380 * @param[in] tname template name, NULL for default
381 * @return status of this function call
383 VsmStatus vsm_create_zone(VsmClient client, const char* id, const char* tname);
388 * @param[in] client vasum-server's client
389 * @param[in] id zone id
390 * @param[in] force if 0 data will be kept, otherwise data will be lost
391 * @return status of this function call
393 VsmStatus vsm_destroy_zone(VsmClient client, const char* id, int force);
398 * @param[in] client vasum-server's client
399 * @param[in] id zone name
400 * @return status of this function call
402 VsmStatus vsm_shutdown_zone(VsmClient client, const char* id);
407 * @param[in] client vasum-server's client
408 * @param[in] id zone name
409 * @return status of this function call
411 VsmStatus vsm_start_zone(VsmClient client, const char* id);
416 * @param[in] client vasum-server's client
417 * @param[in] id zone name
418 * @return status of this function call
420 VsmStatus vsm_lock_zone(VsmClient client, const char* id);
425 * @param[in] client vasum-server's client
426 * @param[in] id zone name
427 * @return status of this function call
429 VsmStatus vsm_unlock_zone(VsmClient client, const char* id);
432 * Register dbus state change callback function.
434 * @note The callback function will be invoked on a different thread.
436 * @param[in] client vasum-server's client
437 * @param[in] zoneDbusStateCallback callback function
438 * @param[in] data some extra data that will be passed to callback function
439 * @param[out] subscriptionId subscription identifier that can be used to unsubscribe signal,
440 * pointer can be NULL.
441 * @return status of this function call
443 VsmStatus vsm_add_state_callback(VsmClient client,
444 VsmZoneDbusStateCallback zoneDbusStateCallback,
446 VsmSubscriptionId* subscriptionId);
449 * Unregister dbus state change callback function.
451 * @param[in] client vasum-server's client
452 * @param[in] subscriptionId subscription identifier returned by vsm_add_state_callback
453 * @return status of this function call
455 VsmStatus vsm_del_state_callback(VsmClient client, VsmSubscriptionId subscriptionId);
458 * Grant access to device
460 * @param[in] client vasum-server's client
461 * @param[in] zone zone name
462 * @param[in] device device path
463 * @param[in] flags access flags
464 * @return status of this function call
466 VsmStatus vsm_zone_grant_device(VsmClient client,
472 * Revoke access to device
474 * @param[in] client vasum-server's client
475 * @param[in] zone zone name
476 * @param[in] device device path
477 * @return status of this function call
479 VsmStatus vsm_revoke_device(VsmClient client, const char* zone, const char* device);
482 * Get array of netdev from given zone
484 * @param[in] client vasum-server's client
485 * @param[in] zone zone name
486 * @param[out] netdevIds array of netdev id
487 * @return status of this function call
488 * @remark Use vsm_array_string_free() to free memory occupied by @p netdevIds.
490 VsmStatus vsm_zone_get_netdevs(VsmClient client, const char* zone, VsmArrayString* netdevIds);
493 * Get ipv4 address for given netdevId
495 * @param[in] client vasum-server's client
496 * @param[in] zone zone name
497 * @param[in] netdevId netdev id
498 * @param[out] addr ipv4 address
499 * @return status of this function call
501 VsmStatus vsm_netdev_get_ipv4_addr(VsmClient client,
503 const char* netdevId,
504 struct in_addr *addr);
507 * Get ipv6 address for given netdevId
509 * @param[in] client vasum-server's client
510 * @param[in] zone zone name
511 * @param[in] netdevId netdev id
512 * @param[out] addr ipv6 address
513 * @return status of this function call
515 VsmStatus vsm_netdev_get_ipv6_addr(VsmClient client,
517 const char* netdevId,
518 struct in6_addr *addr);
521 * Set ipv4 address for given netdevId
523 * @param[in] client vasum-server's client
524 * @param[in] zone zone name
525 * @param[in] netdevId netdev id
526 * @param[in] addr ipv4 address
527 * @param[in] prefix bit-length of the network prefix
528 * @return status of this function call
530 VsmStatus vsm_netdev_set_ipv4_addr(VsmClient client,
532 const char* netdevId,
533 struct in_addr *addr,
537 * Set ipv6 address for given netdevId
539 * @param[in] client vasum-server's client
540 * @param[in] zone zone name
541 * @param[in] netdevId netdev id
542 * @param[in] addr ipv6 address
543 * @param[in] prefix bit-length of the network prefix
544 * @return status of this function call
546 VsmStatus vsm_netdev_set_ipv6_addr(VsmClient client,
548 const char* netdevId,
549 struct in6_addr *addr,
553 * Create netdev in zone
555 * @param[in] client vasum-server's client
556 * @param[in] zone zone name
557 * @param[in] netdevType netdev type
558 * @param[in] target TODO: this is taken form zone-control
559 * @param[in] netdevId network device id
560 * @return status of this function call
562 VsmStatus vsm_create_netdev(VsmClient client,
564 VsmNetdevType netdevType,
566 const char* netdevId);
569 * Remove netdev from zone
571 * @param[in] client vasum-server's client
572 * @param[in] zone zone name
573 * @param[in] netdevId network device id
574 * @return status of this function call
576 VsmStatus vsm_destroy_netdev(VsmClient client, const char* zone, const char* netdevId);
579 * Get netdev informations
581 * @param[in] client vasum-server's client
582 * @param[in] zone zone name
583 * @param[in] netdevId network device id
584 * @param[out] netdev netdev informations
585 * @return status of this function call
586 * @remark Use vsm_netdev_free() to free memory occupied by @p netdev.
588 VsmStatus vsm_lookup_netdev_by_name(VsmClient client,
590 const char* netdevId,
594 * Create file, directory or pipe in zone
596 * Declare file, directory or pipe that will be created while zone startup
598 * @param[in] client vasum-server's client
599 * @param[in] type file type
600 * @param[in] zone zone id
601 * @param[in] path path to file
602 * @param[in] flags if O_CREAT bit is set then file will be created in zone,
603 * otherwise file will by copied from host;
604 * it is meaningful only when O_CREAT is set
605 * @param[in] mode mode of file
606 * @return status of this function call
608 VsmStatus vsm_declare_file(VsmClient client,
616 * Create mount point in zone
618 * Declare mount that will be created while zone startup
619 * Parameters are passed to mount system function
621 * @param[in] client vasum-server's client
622 * @param[in] source device path (path in host)
623 * @param[in] zone zone id
624 * @param[in] target mount point (path in zone)
625 * @param[in] type filesystem type
626 * @param[in] flags mount flags as in mount function
627 * @param[in] data additional data as in mount function
628 * @return status of this function call
630 VsmStatus vsm_declare_mount(VsmClient client,
639 * Create link in zone
641 * Declare link that will be created while zone startup
642 * Parameters are passed to link system function
644 * @param[in] client vasum-server's client
645 * @param[in] source path to link source (in host)
646 * @param[in] zone zone id
647 * @param[in] target path to link name (in zone)
648 * @return status of this function call
650 VsmStatus vsm_declare_link(VsmClient client,
656 /** @} */ // Host API
662 * Functions using org.tizen.vasum.zone.manager D-Bus interface.
668 * Notification callback function signature.
670 * @param[in] zone source zone
671 * @param[in] application sending application name
672 * @param[in] message notification message
673 * @param data custom user's data pointer passed to vsm_add_notification_callback()
675 typedef void (*VsmNotificationCallback)(const char* zone,
676 const char* application,
680 * Send message to active zone.
682 * @param[in] client vasum-server's client
683 * @param[in] application application name
684 * @param[in] message message
685 * @return status of this function call
687 VsmStatus vsm_notify_active_zone(VsmClient client, const char* application, const char* message);
690 * Move file between zones.
692 * @param[in] client vasum-server's client
693 * @param[in] destZone destination zone id
694 * @param[in] path path to moved file
695 * @return status of this function call
697 VsmStatus vsm_file_move_request(VsmClient client, const char* destZone, const char* path);
700 * Register notification callback function.
702 * @note The callback function will be invoked on a different thread.
704 * @param[in] client vasum-server's client
705 * @param[in] notificationCallback callback function
706 * @param[in] data some extra data that will be passed to callback function
707 * @param[out] subscriptionId subscription identifier that can be used to unsubscribe signal,
708 * pointer can be NULL.
709 * @return status of this function call
711 VsmStatus vsm_add_notification_callback(VsmClient client,
712 VsmNotificationCallback notificationCallback,
714 VsmSubscriptionId* subscriptionId);
717 * Unregister notification callback function.
719 * @param[in] client vasum-server's client
720 * @param[in] subscriptionId subscription identifier returned by vsm_add_notification_callback
721 * @return status of this function call
723 VsmStatus vsm_del_notification_callback(VsmClient client, VsmSubscriptionId subscriptionId);
725 /** @} */ // Zone API
731 #endif /* VASUM_CLIENT_H */