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
83 #include <netinet/ip.h>
84 #include <linux/if_link.h>
92 * vasum-server's client pointer.
94 typedef void* VsmClient;
97 * NULL-terminated string type.
99 * @sa vsm_array_string_free
101 typedef char* VsmString;
104 * NULL-terminated array of strings type.
106 * @sa vsm_string_free
108 typedef VsmString* VsmArrayString;
111 * Completion status of communication function.
114 VSMCLIENT_CUSTOM_ERROR, /**< User specified error */
115 VSMCLIENT_IO_ERROR, /**< Input/Output error */
116 VSMCLIENT_OPERATION_FAILED, /**< Operation failed */
117 VSMCLIENT_INVALID_ARGUMENT, /**< Invalid argument */
118 VSMCLIENT_OTHER_ERROR, /**< Other error */
119 VSMCLIENT_SUCCESS /**< Success */
125 typedef unsigned int VsmSubscriptionId;
145 * Zone information structure
157 typedef VsmZoneStructure* VsmZone;
160 * Netowrk device type
169 * Network device information structure
174 } VsmNetdevStructure;
177 * Network device information
179 typedef VsmNetdevStructure* VsmNetdev;
190 #ifndef __VASUM_WRAPPER_SOURCE__
194 * Do not call this function if an application creates a glib loop itself.
195 * Otherwise, call it before any other function from this library.
197 * @return status of this function call
199 VsmStatus vsm_start_glib_loop();
204 * Call only if vsm_start_glib_loop() was called.
206 * @return status of this function call
208 VsmStatus vsm_stop_glib_loop();
211 * Create a new vasum-server's client.
213 * @return Created client pointer or NULL on failure.
215 VsmClient vsm_client_create();
218 * Release client resources.
220 * @param[in] client vasum-server's client
222 void vsm_client_free(VsmClient client);
225 * Get status code of last vasum-server communication.
227 * @param[in] client vasum-server's client
228 * @return status of this function call
230 VsmStatus vsm_get_status(VsmClient client);
233 * Get status message of the last vasum-server communication.
235 * @param[in] client vasum-server's client
236 * @return last status message from vasum-server communication
238 const char* vsm_get_status_message(VsmClient client);
241 * Connect client to the vasum-server.
243 * @param[in] client vasum-server's client
244 * @return status of this function call
246 VsmStatus vsm_connect(VsmClient client);
249 * Connect client to the vasum-server via custom address.
251 * @param[in] client vasum-server's client
252 * @param[in] address dbus address
253 * @return status of this function call
255 VsmStatus vsm_connect_custom(VsmClient client, const char* address);
258 * Release VsmArrayString.
260 * @param[in] astring VsmArrayString
262 void vsm_array_string_free(VsmArrayString astring);
267 * @param string VsmString
269 void vsm_string_free(VsmString string);
274 * @param zone VsmZone
276 void vsm_zone_free(VsmZone zone);
281 * @param netdev VsmNetdev
283 void vsm_netdev_free(VsmNetdev netdev);
288 * Functions using org.tizen.vasum.host.manager D-Bus interface.
294 * Zone's D-Bus state change callback function signature.
296 * @param[in] zoneId affected zone id
297 * @param[in] address new D-Bus address
298 * @param data custom user's data pointer passed to vsm_add_state_callback() function
300 typedef void (*VsmZoneDbusStateCallback)(const char* zoneId,
305 * Get dbus address of each zone.
307 * @param[in] client vasum-server's client
308 * @param[out] keys array of zones name
309 * @param[out] values array of zones dbus address
310 * @return status of this function call
311 * @post keys[i] corresponds to values[i]
312 * @remark Use vsm_array_string_free() to free memory occupied by @p keys and @p values.
314 VsmStatus vsm_get_zone_dbuses(VsmClient client, VsmArrayString* keys, VsmArrayString* values);
319 * @param[in] client vasum-server's client
320 * @param[out] array array of zones name
321 * @return status of this function call
322 * @remark Use vsm_array_string_free() to free memory occupied by @p array.
324 VsmStatus vsm_get_zone_ids(VsmClient client, VsmArrayString* array);
327 * Get active (foreground) zone name.
329 * @param[in] client vasum-server's client
330 * @param[out] id active zone name
331 * @return status of this function call
332 * @remark Use @p vsm_string_free() to free memory occupied by @p id.
334 VsmStatus vsm_get_active_zone_id(VsmClient client, VsmString* id);
337 * Get zone rootfs path.
339 * @param[in] client vasum-server's client
340 * @param[in] id zone name
341 * @param[out] rootpath zone rootfs path
342 * @return status of this function call
343 * @remark Use @p vsm_string_free() to free memory occupied by @p rootpath.
345 VsmStatus vsm_get_zone_rootpath(VsmClient client, const char* id, VsmString* rootpath);
348 * Get zone name of process with given pid.
350 * @param[in] client vasum-server's client
351 * @param[in] pid process id
352 * @param[out] id active zone name
353 * @return status of this function call
354 * @remark Use @p vsm_string_free() to free memory occupied by @p id.
356 VsmStatus vsm_lookup_zone_by_pid(VsmClient client, int pid, VsmString* id);
359 * Get zone informations of zone with given id.
361 * @param[in] client vasum-server's client
362 * @param[in] id zone name
363 * @param[out] zone zone informations
364 * @return status of this function call
365 * @remark Use @p vsm_zone_free() to free memory occupied by @p zone
367 VsmStatus vsm_lookup_zone_by_id(VsmClient client, const char* id, VsmZone* zone);
370 * Get zone name with given terminal.
372 * @param[in] client vasum-server's client
373 * @param[in] terminal terminal id
374 * @param[out] id zone name with given terminal
375 * @return status of this function call
376 * @remark Use @p vsm_string_free() to free memory occupied by @p id.
378 VsmStatus vsm_lookup_zone_by_terminal_id(VsmClient client, int terminal, VsmString* id);
381 * Set active (foreground) zone.
383 * @param[in] client vasum-server's client
384 * @param[in] id zone name
385 * @return status of this function call
387 VsmStatus vsm_set_active_zone(VsmClient client, const char* id);
390 * Create and add zone
392 * @param[in] client vasum-server's client
393 * @param[in] id zone id
394 * @param[in] tname template name, NULL is equivalent to "default"
395 * @return status of this function call
397 VsmStatus vsm_create_zone(VsmClient client, const char* id, const char* tname);
402 * @param[in] client vasum-server's client
403 * @param[in] id zone id
404 * @param[in] force if 0 data will be kept, otherwise data will be lost
405 * @return status of this function call
407 VsmStatus vsm_destroy_zone(VsmClient client, const char* id, int force);
412 * @param[in] client vasum-server's client
413 * @param[in] id zone name
414 * @return status of this function call
416 VsmStatus vsm_shutdown_zone(VsmClient client, const char* id);
421 * @param[in] client vasum-server's client
422 * @param[in] id zone name
423 * @return status of this function call
425 VsmStatus vsm_start_zone(VsmClient client, const char* id);
430 * @param[in] client vasum-server's client
431 * @param[in] id zone name
432 * @return status of this function call
434 VsmStatus vsm_lock_zone(VsmClient client, const char* id);
439 * @param[in] client vasum-server's client
440 * @param[in] id zone name
441 * @return status of this function call
443 VsmStatus vsm_unlock_zone(VsmClient client, const char* id);
446 * Register dbus state change callback function.
448 * @note The callback function will be invoked on a different thread.
450 * @param[in] client vasum-server's client
451 * @param[in] zoneDbusStateCallback callback function
452 * @param[in] data some extra data that will be passed to callback function
453 * @param[out] subscriptionId subscription identifier that can be used to unsubscribe signal,
454 * pointer can be NULL.
455 * @return status of this function call
457 VsmStatus vsm_add_state_callback(VsmClient client,
458 VsmZoneDbusStateCallback zoneDbusStateCallback,
460 VsmSubscriptionId* subscriptionId);
463 * Unregister dbus state change callback function.
465 * @param[in] client vasum-server's client
466 * @param[in] subscriptionId subscription identifier returned by vsm_add_state_callback
467 * @return status of this function call
469 VsmStatus vsm_del_state_callback(VsmClient client, VsmSubscriptionId subscriptionId);
472 * Grant access to device
474 * @param[in] client vasum-server's client
475 * @param[in] zone zone name
476 * @param[in] device device path
477 * @param[in] flags access flags
478 * @return status of this function call
480 VsmStatus vsm_grant_device(VsmClient client,
486 * Revoke access to device
488 * @param[in] client vasum-server's client
489 * @param[in] zone zone name
490 * @param[in] device device path
491 * @return status of this function call
493 VsmStatus vsm_revoke_device(VsmClient client, const char* zone, const char* device);
496 * Get array of netdev from given zone
498 * @param[in] client vasum-server's client
499 * @param[in] zone zone name
500 * @param[out] netdevIds array of netdev id
501 * @return status of this function call
502 * @remark Use vsm_array_string_free() to free memory occupied by @p netdevIds.
504 VsmStatus vsm_zone_get_netdevs(VsmClient client, const char* zone, VsmArrayString* netdevIds);
507 * Get ipv4 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 ipv4 address
513 * @return status of this function call
515 VsmStatus vsm_netdev_get_ipv4_addr(VsmClient client,
517 const char* netdevId,
518 struct in_addr *addr);
521 * Get ipv6 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[out] addr ipv6 address
527 * @return status of this function call
529 VsmStatus vsm_netdev_get_ipv6_addr(VsmClient client,
531 const char* netdevId,
532 struct in6_addr *addr);
535 * Set ipv4 address for given netdevId
537 * @param[in] client vasum-server's client
538 * @param[in] zone zone name
539 * @param[in] netdevId netdev id
540 * @param[in] addr ipv4 address
541 * @param[in] prefix bit-length of the network prefix
542 * @return status of this function call
544 VsmStatus vsm_netdev_set_ipv4_addr(VsmClient client,
546 const char* netdevId,
547 struct in_addr *addr,
551 * Set ipv6 address for given netdevId
553 * @param[in] client vasum-server's client
554 * @param[in] zone zone name
555 * @param[in] netdevId netdev id
556 * @param[in] addr ipv6 address
557 * @param[in] prefix bit-length of the network prefix
558 * @return status of this function call
560 VsmStatus vsm_netdev_set_ipv6_addr(VsmClient client,
562 const char* netdevId,
563 struct in6_addr *addr,
567 * Remove ipv4 address from netdev
569 * @param[in] client vasum-server's client
570 * @param[in] zone zone name
571 * @param[in] netdevId network device id
572 * @param[in] addr ipv4 address
573 * @param[in] prefix bit-length of the network prefix
574 * @return status of this function call
576 VsmStatus vsm_netdev_del_ipv4_addr(VsmClient client,
578 const char* netdevId,
579 struct in_addr* addr,
583 * Remove ipv6 address from netdev
585 * @param[in] client vasum-server's client
586 * @param[in] zone zone name
587 * @param[in] netdevId network device id
588 * @param[in] addr ipv6 address
589 * @param[in] prefix bit-length of the network prefix
590 * @return status of this function call
592 VsmStatus vsm_netdev_del_ipv6_addr(VsmClient client,
594 const char* netdevId,
595 struct in6_addr* addr,
599 * Turn up a network device in the zone
601 * @param[in] client vasum-server's client
602 * @param[in] zone zone name
603 * @param[in] netdevId netdev id
604 * @return status of this function call
606 VsmStatus vsm_netdev_up(VsmClient client,
608 const char* netdevId);
611 * Turn down a network device in the zone
613 * @param[in] client vasum-server's client
614 * @param[in] zone zone name
615 * @param[in] netdevId netdev id
616 * @return status of this function call
618 VsmStatus vsm_netdev_down(VsmClient client,
620 const char* netdevId);
624 * Create veth netdev in zone
626 * @param[in] client vasum-server's client
627 * @param[in] zone zone name
628 * @param[in] zoneDev in host network device id
629 * @param[in] hostDev in zone network device id
630 * @return status of this function call
632 VsmStatus vsm_create_netdev_veth(VsmClient client,
635 const char* hostDev);
637 * Create macvlab in zone
639 * @param[in] client vasum-server's client
640 * @param[in] zone zone name
641 * @param[in] zoneDev in host network device id
642 * @param[in] hostDev in zone network device id
643 * @return status of this function call
645 VsmStatus vsm_create_netdev_macvlan(VsmClient client,
649 enum macvlan_mode mode);
651 * Create/move phys netdev in/to zone
653 * @param[in] client vasum-server's client
654 * @param[in] zone zone name
655 * @param[in] devId network device id
656 * @return status of this function call
658 VsmStatus vsm_create_netdev_phys(VsmClient client, const char* zone, const char* devId);
661 * Get netdev informations
663 * @param[in] client vasum-server's client
664 * @param[in] zone zone name
665 * @param[in] netdevId network device id
666 * @param[out] netdev netdev informations
667 * @return status of this function call
668 * @remark Use vsm_netdev_free() to free memory occupied by @p netdev.
670 VsmStatus vsm_lookup_netdev_by_name(VsmClient client,
672 const char* netdevId,
676 * Remove netdev from zone
678 * @param[in] client vasum-server's client
679 * @param[in] zone zone name
680 * @param[in] devId network device id
681 * @return status of this function call
683 VsmStatus vsm_destroy_netdev(VsmClient client, const char* zone, const char* devId);
686 * Create file, directory or pipe in zone
688 * Declare file, directory or pipe that will be created while zone startup
690 * @param[in] client vasum-server's client
691 * @param[in] type file type
692 * @param[in] zone zone id
693 * @param[in] path path to file
694 * @param[in] flags if O_CREAT bit is set then file will be created in zone,
695 * otherwise file will by copied from host;
696 * it is meaningful only when O_CREAT is set
697 * @param[in] mode mode of file
698 * @return status of this function call
700 VsmStatus vsm_declare_file(VsmClient client,
708 * Create mount point in zone
710 * Declare mount that will be created while zone startup
711 * Parameters are passed to mount system function
713 * @param[in] client vasum-server's client
714 * @param[in] source device path (path in host)
715 * @param[in] zone zone id
716 * @param[in] target mount point (path in zone)
717 * @param[in] type filesystem type
718 * @param[in] flags mount flags as in mount function
719 * @param[in] data additional data as in mount function
720 * @return status of this function call
722 VsmStatus vsm_declare_mount(VsmClient client,
731 * Create link in zone
733 * Declare link that will be created while zone startup
734 * Parameters are passed to link system function
736 * @param[in] client vasum-server's client
737 * @param[in] source path to link source (in host)
738 * @param[in] zone zone id
739 * @param[in] target path to link name (in zone)
740 * @return status of this function call
742 VsmStatus vsm_declare_link(VsmClient client,
748 * Get all declarations
750 * Gets all declarations of resourcies
751 * (@see ::vsm_declare_link, @see ::vsm_declare_mount, @see ::vsm_declare_linki)
753 * @param[in] client vasum-server's client
754 * @param[in] zone zone id
755 * @param[out] declarations array of declarations id
756 * @return status of this function call
758 VsmStatus vsm_list_declarations(VsmClient client,
760 VsmArrayString* declarations);
765 * Removes given declaration by its id (@see ::vsm_list_declarations)
767 * @param[in] client vasum-server's client
768 * @param[in] zone zone id
769 * @param[in] declaration declaration id
770 * @return status of this function call
772 VsmStatus vsm_remove_declaration(VsmClient client,
774 VsmString declaration);
783 * Functions using org.tizen.vasum.zone.manager D-Bus interface.
789 * Notification callback function signature.
791 * @param[in] zone source zone
792 * @param[in] application sending application name
793 * @param[in] message notification message
794 * @param data custom user's data pointer passed to vsm_add_notification_callback()
796 typedef void (*VsmNotificationCallback)(const char* zone,
797 const char* application,
801 * Send message to active zone.
803 * @param[in] client vasum-server's client
804 * @param[in] application application name
805 * @param[in] message message
806 * @return status of this function call
808 VsmStatus vsm_notify_active_zone(VsmClient client, const char* application, const char* message);
811 * Move file between zones.
813 * @param[in] client vasum-server's client
814 * @param[in] destZone destination zone id
815 * @param[in] path path to moved file
816 * @return status of this function call
818 VsmStatus vsm_file_move_request(VsmClient client, const char* destZone, const char* path);
821 * Register notification callback function.
823 * @note The callback function will be invoked on a different thread.
825 * @param[in] client vasum-server's client
826 * @param[in] notificationCallback callback function
827 * @param[in] data some extra data that will be passed to callback function
828 * @param[out] subscriptionId subscription identifier that can be used to unsubscribe signal,
829 * pointer can be NULL.
830 * @return status of this function call
832 VsmStatus vsm_add_notification_callback(VsmClient client,
833 VsmNotificationCallback notificationCallback,
835 VsmSubscriptionId* subscriptionId);
838 * Unregister notification callback function.
840 * @param[in] client vasum-server's client
841 * @param[in] subscriptionId subscription identifier returned by vsm_add_notification_callback
842 * @return status of this function call
844 VsmStatus vsm_del_notification_callback(VsmClient client, VsmSubscriptionId subscriptionId);
846 #endif /* __VASUM_WRAPPER_SOURCE__ */
854 #endif /* VASUM_CLIENT_H */