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
24 * @defgroup libvasum-client libvasum-client
25 * @brief C library for interfacing Vasum
27 * All functionalities that are possible using the Vasum's Command Line Interface can also be done with libvasum-client's calls.
31 * - Create VsmClient with vsm_client_create(). It'll be needed for all communication with Vasum.
32 * - Establish the connection with the daemon using vsm_connect()
33 * - Do what you need to do with the zones
34 * - Free the client with vsm_client_free()
38 #include <vasum-client.h>
40 int main(int argc, char** argv)
44 VsmArrayString values = NULL;
47 // Create client handle
48 client = vsm_client_create();
56 status = vsm_connect(client);
57 if (VSMCLIENT_SUCCESS != status) {
63 status = vsm_get_zone_ids(client, &values);
64 if (VSMCLIENT_SUCCESS != status) {
71 for (VsmArrayString iValues = values; *iValues; iValues++) {
72 printf("%s\n", *iValues);
76 vsm_array_string_free(values); // free memory
77 vsm_client_free(client); // destroy client handle
84 * By default libVasum will create a separate thread for his communication with Vasum. Most of the time it'll sleep so it shouldn't be a concern.
85 * It's also possible to connect to an existing polling loop. To do this you'll need to:
86 * - Get the poll file descriptor with vsm_get_poll_fd()
87 * - Use epoll/poll/select to wait for events on the file descriptor
88 * - Call vsm_enter_eventloop() every time there's an event
96 #include <sys/epoll.h>
97 #include <vasum-client.h>
99 volatile static sig_atomic_t running;
100 static int LOOP_INTERVAL = 1000; // ms
102 void* main_loop(void* client)
105 VsmStatus status = vsm_get_poll_fd(client, &fd);
106 assert(VSMCLIENT_SUCCESS == status);
109 struct epoll_event event;
110 int num = epoll_wait(fd, &event, 1, LOOP_INTERVAL);
112 status = vsm_enter_eventloop(client, 0 , 0);
113 assert(VSMCLIENT_SUCCESS == status);
119 int main(int argc, char** argv)
126 client = vsm_client_create();
129 status = vsm_set_dispatcher_type(client, VSMDISPATCHER_EXTERNAL);
130 assert(VSMCLIENT_SUCCESS == status);
132 status = vsm_connect(client);
133 assert(VSMCLIENT_SUCCESS == status);
137 ret = pthread_create(&loop, NULL, main_loop, client);
140 // make vsm_* calls on client
143 status = vsm_disconnect(client);
144 assert(VSMCLIENT_SUCCESS == status);
148 ret = pthread_join(loop, NULL);
151 vsm_client_free(client); // destroy client handle
157 #ifndef VASUM_CLIENT_H
158 #define VASUM_CLIENT_H
161 #include <sys/stat.h>
162 #include <netinet/ip.h>
163 #include <linux/if_link.h>
171 * vasum-server's opaque client pointer.
173 typedef void* VsmClient;
176 * NULL-terminated string type.
178 * @sa vsm_string_free
180 typedef char* VsmString;
183 * NULL-terminated array of strings type.
185 * @sa vsm_array_string_free
187 typedef VsmString* VsmArrayString;
190 * Completion status of libvasum-client's functions
193 VSMCLIENT_CUSTOM_ERROR, ///< User specified error
194 VSMCLIENT_IO_ERROR, ///< Input/Output error
195 VSMCLIENT_OPERATION_FAILED, ///< Operation failed
196 VSMCLIENT_INVALID_ARGUMENT, ///< Invalid argument
197 VSMCLIENT_OTHER_ERROR, ///< Other error
198 VSMCLIENT_SUCCESS ///< Success
204 typedef unsigned int VsmSubscriptionId;
224 * Zone information structure
236 typedef VsmZoneStructure* VsmZone;
239 * Netowrk device type
248 * Network device information structure
253 } VsmNetdevStructure;
256 * Network device information
258 typedef VsmNetdevStructure* VsmNetdev;
270 * Event dispacher types.
273 VSMDISPATCHER_EXTERNAL, /**< User must handle dispatching messages */
274 VSMDISPATCHER_INTERNAL /**< Library will take care of dispatching messages */
277 #ifndef __VASUM_WRAPPER_SOURCE__
280 * Get file descriptor associated with event dispatcher of zone client
282 * The function vsm_get_poll_fd() returns the file descriptor associated with the event dispatcher of vsm client.
283 * The file descriptor can be bound to another I/O multiplexing facilities like epoll, select, and poll.
285 * @param[in] client vsm client
286 * @param[out] fd epoll file descriptor
287 * @return status of this function call
289 VsmStatus vsm_get_poll_fd(VsmClient client, int* fd);
292 * Wait for an I/O event on a vsm client
294 * vsm_enter_eventloop() waits for event on the vsm client
296 * The call waits for a maximum time of timout milliseconds. Specifying a timeout of -1 makes vsm_enter_eventloop() wait indefinitely,
297 * while specifying a timeout equal to zero makes vsm_enter_eventloop() to return immediately even if no events are available.
299 * @param[in] client vasum-server's client
300 * @param[in] flags Reserved
301 * @param[in] timeout Timeout time (milisecond), -1 is infinite
302 * @return status of this function call
304 VsmStatus vsm_enter_eventloop(VsmClient client, int flags, int timeout);
307 * Set dispatching method
309 * @param[in] client vasum-server's client
310 * @param[in] dispacher dispatching method
311 * @return status of this function call
313 VsmStatus vsm_set_dispatcher_type(VsmClient client, VsmDispacherType dispacher);
316 * Get dispatching method
318 * @param[in] client vasum-server's client
319 * @param[out] dispacher dispatching method
320 * @return status of this function call
322 VsmStatus vsm_get_dispatcher_type(VsmClient client, VsmDispacherType* dispacher);
325 * Create a new vasum-server's client.
327 * @return Created client pointer or NULL on failure.
329 VsmClient vsm_client_create();
332 * Release client resources.
334 * @param[in] client vasum-server's client
336 void vsm_client_free(VsmClient client);
339 * Get status code of last vasum-server communication.
341 * @param[in] client vasum-server's client
342 * @return status of this function call
344 VsmStatus vsm_get_status(VsmClient client);
347 * Get status message of the last vasum-server communication.
349 * @param[in] client vasum-server's client
350 * @return last status message from vasum-server communication
352 const char* vsm_get_status_message(VsmClient client);
355 * Connect client to the vasum-server.
357 * @param[in] client vasum-server's client
358 * @return status of this function call
360 VsmStatus vsm_connect(VsmClient client);
363 * Connect client to the vasum-server via custom address.
365 * @param[in] client vasum-server's client
366 * @param[in] address dbus address
367 * @return status of this function call
369 VsmStatus vsm_connect_custom(VsmClient client, const char* address);
372 * Disconnect client from vasum-server.
374 * @param[in] client vasum-server's client
375 * @return status of this function call
377 VsmStatus vsm_disconnect(VsmClient client);
380 * Release VsmArrayString.
382 * @param[in] astring VsmArrayString
384 void vsm_array_string_free(VsmArrayString astring);
389 * @param string VsmString
391 void vsm_string_free(VsmString string);
396 * @param zone VsmZone
398 void vsm_zone_free(VsmZone zone);
403 * @param netdev VsmNetdev
405 void vsm_netdev_free(VsmNetdev netdev);
408 * Zone's D-Bus state change callback function signature.
410 * @param[in] zoneId affected zone id
411 * @param[in] address new D-Bus address
412 * @param data custom user's data pointer passed to vsm_add_state_callback() function
414 typedef void (*VsmZoneDbusStateCallback)(const char* zoneId,
419 * Lock the command queue exclusively.
421 * @param[in] client vasum-server's client
422 * @return status of this function call
424 VsmStatus vsm_lock_queue(VsmClient client);
427 * Unlock the command queue.
429 * @param[in] client vasum-server's client
430 * @return status of this function call
432 VsmStatus vsm_unlock_queue(VsmClient client);
435 * Get dbus address of each zone.
437 * @param[in] client vasum-server's client
438 * @param[out] keys array of zones name
439 * @param[out] values array of zones dbus address
440 * @return status of this function call
441 * @post keys[i] corresponds to values[i]
442 * @remark Use vsm_array_string_free() to free memory occupied by @p keys and @p values.
444 VsmStatus vsm_get_zone_dbuses(VsmClient client, VsmArrayString* keys, VsmArrayString* values);
449 * @param[in] client vasum-server's client
450 * @param[out] array array of zones name
451 * @return status of this function call
452 * @remark Use vsm_array_string_free() to free memory occupied by @p array.
454 VsmStatus vsm_get_zone_ids(VsmClient client, VsmArrayString* array);
457 * Get active (foreground) zone name.
459 * @param[in] client vasum-server's client
460 * @param[out] id active zone name
461 * @return status of this function call
462 * @remark Use @p vsm_string_free() to free memory occupied by @p id.
464 VsmStatus vsm_get_active_zone_id(VsmClient client, VsmString* id);
467 * Get zone rootfs path.
469 * @param[in] client vasum-server's client
470 * @param[in] id zone name
471 * @param[out] rootpath zone rootfs path
472 * @return status of this function call
473 * @remark Use @p vsm_string_free() to free memory occupied by @p rootpath.
475 VsmStatus vsm_get_zone_rootpath(VsmClient client, const char* id, VsmString* rootpath);
478 * Get zone name of process with given pid.
480 * @param[in] client vasum-server's client
481 * @param[in] pid process id
482 * @param[out] id active zone name
483 * @return status of this function call
484 * @remark Use @p vsm_string_free() to free memory occupied by @p id.
486 VsmStatus vsm_lookup_zone_by_pid(VsmClient client, int pid, VsmString* id);
489 * Get zone informations of zone with given id.
491 * @param[in] client vasum-server's client
492 * @param[in] id zone name
493 * @param[out] zone zone informations
494 * @return status of this function call
495 * @remark Use @p vsm_zone_free() to free memory occupied by @p zone
497 VsmStatus vsm_lookup_zone_by_id(VsmClient client, const char* id, VsmZone* zone);
500 * Get zone name with given terminal.
502 * @param[in] client vasum-server's client
503 * @param[in] terminal terminal id
504 * @param[out] id zone name with given terminal
505 * @return status of this function call
506 * @remark Use @p vsm_string_free() to free memory occupied by @p id.
508 VsmStatus vsm_lookup_zone_by_terminal_id(VsmClient client, int terminal, VsmString* id);
511 * Set active (foreground) zone.
513 * @param[in] client vasum-server's client
514 * @param[in] id zone name
515 * @return status of this function call
517 VsmStatus vsm_set_active_zone(VsmClient client, const char* id);
520 * Create and add zone
522 * @param[in] client vasum-server's client
523 * @param[in] id zone id
524 * @param[in] tname template name, NULL is equivalent to "default"
525 * @return status of this function call
527 VsmStatus vsm_create_zone(VsmClient client, const char* id, const char* tname);
532 * @param[in] client vasum-server's client
533 * @param[in] id zone id
534 * @param[in] force if 0 data will be kept, otherwise data will be lost
535 * @return status of this function call
537 VsmStatus vsm_destroy_zone(VsmClient client, const char* id, int force);
542 * @param[in] client vasum-server's client
543 * @param[in] id zone name
544 * @return status of this function call
546 VsmStatus vsm_shutdown_zone(VsmClient client, const char* id);
551 * @param[in] client vasum-server's client
552 * @param[in] id zone name
553 * @return status of this function call
555 VsmStatus vsm_start_zone(VsmClient client, const char* id);
560 * @param[in] client vasum-server's client
561 * @param[in] id zone name
562 * @return status of this function call
564 VsmStatus vsm_lock_zone(VsmClient client, const char* id);
569 * @param[in] client vasum-server's client
570 * @param[in] id zone name
571 * @return status of this function call
573 VsmStatus vsm_unlock_zone(VsmClient client, const char* id);
576 * Register dbus state change callback function.
578 * @note The callback function will be invoked on a different thread.
580 * @param[in] client vasum-server's client
581 * @param[in] zoneDbusStateCallback callback function
582 * @param[in] data some extra data that will be passed to callback function
583 * @param[out] subscriptionId subscription identifier that can be used to unsubscribe signal,
584 * pointer can be NULL.
585 * @return status of this function call
587 VsmStatus vsm_add_state_callback(VsmClient client,
588 VsmZoneDbusStateCallback zoneDbusStateCallback,
590 VsmSubscriptionId* subscriptionId);
593 * Unregister dbus state change callback function.
595 * @param[in] client vasum-server's client
596 * @param[in] subscriptionId subscription identifier returned by vsm_add_state_callback
597 * @return status of this function call
599 VsmStatus vsm_del_state_callback(VsmClient client, VsmSubscriptionId subscriptionId);
602 * Grant access to device
604 * @param[in] client vasum-server's client
605 * @param[in] zone zone name
606 * @param[in] device device path
607 * @param[in] flags access flags
608 * @return status of this function call
610 VsmStatus vsm_grant_device(VsmClient client,
616 * Revoke access to device
618 * @param[in] client vasum-server's client
619 * @param[in] zone zone name
620 * @param[in] device device path
621 * @return status of this function call
623 VsmStatus vsm_revoke_device(VsmClient client, const char* zone, const char* device);
626 * Get array of netdev from given zone
628 * @param[in] client vasum-server's client
629 * @param[in] zone zone name
630 * @param[out] netdevIds array of netdev id
631 * @return status of this function call
632 * @remark Use vsm_array_string_free() to free memory occupied by @p netdevIds.
634 VsmStatus vsm_zone_get_netdevs(VsmClient client, const char* zone, VsmArrayString* netdevIds);
637 * Get ipv4 address for given netdevId
639 * @param[in] client vasum-server's client
640 * @param[in] zone zone name
641 * @param[in] netdevId netdev id
642 * @param[out] addr ipv4 address
643 * @return status of this function call
645 VsmStatus vsm_netdev_get_ipv4_addr(VsmClient client,
647 const char* netdevId,
648 struct in_addr *addr);
651 * Get ipv6 address for given netdevId
653 * @param[in] client vasum-server's client
654 * @param[in] zone zone name
655 * @param[in] netdevId netdev id
656 * @param[out] addr ipv6 address
657 * @return status of this function call
659 VsmStatus vsm_netdev_get_ipv6_addr(VsmClient client,
661 const char* netdevId,
662 struct in6_addr *addr);
665 * Set ipv4 address for given netdevId
667 * @param[in] client vasum-server's client
668 * @param[in] zone zone name
669 * @param[in] netdevId netdev id
670 * @param[in] addr ipv4 address
671 * @param[in] prefix bit-length of the network prefix
672 * @return status of this function call
674 VsmStatus vsm_netdev_set_ipv4_addr(VsmClient client,
676 const char* netdevId,
677 struct in_addr *addr,
681 * Set ipv6 address for given netdevId
683 * @param[in] client vasum-server's client
684 * @param[in] zone zone name
685 * @param[in] netdevId netdev id
686 * @param[in] addr ipv6 address
687 * @param[in] prefix bit-length of the network prefix
688 * @return status of this function call
690 VsmStatus vsm_netdev_set_ipv6_addr(VsmClient client,
692 const char* netdevId,
693 struct in6_addr *addr,
697 * Remove ipv4 address from netdev
699 * @param[in] client vasum-server's client
700 * @param[in] zone zone name
701 * @param[in] netdevId network device id
702 * @param[in] addr ipv4 address
703 * @param[in] prefix bit-length of the network prefix
704 * @return status of this function call
706 VsmStatus vsm_netdev_del_ipv4_addr(VsmClient client,
708 const char* netdevId,
709 struct in_addr* addr,
713 * Remove ipv6 address from netdev
715 * @param[in] client vasum-server's client
716 * @param[in] zone zone name
717 * @param[in] netdevId network device id
718 * @param[in] addr ipv6 address
719 * @param[in] prefix bit-length of the network prefix
720 * @return status of this function call
722 VsmStatus vsm_netdev_del_ipv6_addr(VsmClient client,
724 const char* netdevId,
725 struct in6_addr* addr,
729 * Turn up a network device in the zone
731 * @param[in] client vasum-server's client
732 * @param[in] zone zone name
733 * @param[in] netdevId netdev id
734 * @return status of this function call
736 VsmStatus vsm_netdev_up(VsmClient client,
738 const char* netdevId);
741 * Turn down a network device in the zone
743 * @param[in] client vasum-server's client
744 * @param[in] zone zone name
745 * @param[in] netdevId netdev id
746 * @return status of this function call
748 VsmStatus vsm_netdev_down(VsmClient client,
750 const char* netdevId);
754 * Create veth netdev in zone
756 * @param[in] client vasum-server's client
757 * @param[in] zone zone name
758 * @param[in] zoneDev Device ID in Zone network
759 * @param[in] hostDev Device ID in Host network
760 * @return status of this function call
762 VsmStatus vsm_create_netdev_veth(VsmClient client,
765 const char* hostDev);
767 * Create macvlan in zone
769 * @param[in] client vasum-server's client
770 * @param[in] zone Zone name
771 * @param[in] zoneDev Device ID in Zone network
772 * @param[in] hostDev Device ID in Host network
773 * @param[in] mode Mode with which macvlan will be created.
774 * @return status of this function call
778 VsmStatus vsm_create_netdev_macvlan(VsmClient client,
782 enum macvlan_mode mode);
784 * Create/move phys netdev in/to zone
786 * @param[in] client vasum-server's client
787 * @param[in] zone zone name
788 * @param[in] devId network device id
789 * @return status of this function call
791 VsmStatus vsm_create_netdev_phys(VsmClient client, const char* zone, const char* devId);
794 * Get netdev informations
796 * @param[in] client vasum-server's client
797 * @param[in] zone zone name
798 * @param[in] netdevId network device id
799 * @param[out] netdev netdev informations
800 * @return status of this function call
801 * @remark Use vsm_netdev_free() to free memory occupied by @p netdev.
803 VsmStatus vsm_lookup_netdev_by_name(VsmClient client,
805 const char* netdevId,
809 * Remove netdev from zone
811 * @param[in] client vasum-server's client
812 * @param[in] zone zone name
813 * @param[in] devId network device id
814 * @return status of this function call
816 VsmStatus vsm_destroy_netdev(VsmClient client, const char* zone, const char* devId);
819 * Create file, directory or pipe in zone
821 * Declare file, directory or pipe that will be created while zone startup
823 * @param[in] client vasum-server's client
824 * @param[in] type file type
825 * @param[in] zone zone id
826 * @param[in] path path to file
827 * @param[in] flags if O_CREAT bit is set then file will be created in zone,
828 * otherwise file will by copied from host;
829 * it is meaningful only when O_CREAT is set
830 * @param[in] mode mode of file
831 * @return status of this function call
833 VsmStatus vsm_declare_file(VsmClient client,
841 * Create mount point in zone
843 * Declare mount that will be created while zone startup
844 * Parameters are passed to mount system function
846 * @param[in] client vasum-server's client
847 * @param[in] source device path (path in host)
848 * @param[in] zone zone id
849 * @param[in] target mount point (path in zone)
850 * @param[in] type filesystem type
851 * @param[in] flags mount flags as in mount function
852 * @param[in] data additional data as in mount function
853 * @return status of this function call
855 VsmStatus vsm_declare_mount(VsmClient client,
864 * Create link in zone
866 * Declare link that will be created while zone startup
867 * Parameters are passed to link system function
869 * @param[in] client vasum-server's client
870 * @param[in] source path to link source (in host)
871 * @param[in] zone zone id
872 * @param[in] target path to link name (in zone)
873 * @return status of this function call
875 VsmStatus vsm_declare_link(VsmClient client,
881 * Get all declarations
883 * Gets all declarations of resourcies
884 * (@see ::vsm_declare_link, @see ::vsm_declare_mount, @see ::vsm_declare_file)
886 * @param[in] client vasum-server's client
887 * @param[in] zone zone id
888 * @param[out] declarations array of declarations id
889 * @return status of this function call
891 VsmStatus vsm_list_declarations(VsmClient client,
893 VsmArrayString* declarations);
898 * Removes given declaration by its id (@see ::vsm_list_declarations)
900 * @param[in] client vasum-server's client
901 * @param[in] zone zone id
902 * @param[in] declaration declaration id
903 * @return status of this function call
905 VsmStatus vsm_remove_declaration(VsmClient client,
907 VsmString declaration);
910 * Clean up zones root directory
912 * Removes all unknown zones root directory entry
913 * @return status of this function call
915 VsmStatus vsm_clean_up_zones_root(VsmClient client);
917 #endif /* __VASUM_WRAPPER_SOURCE__ */
923 #endif /* VASUM_CLIENT_H */