/**
* @file
- * @author Mateusz Malicki (m.malicki2@samsung.com)
- * @brief This file contains the public API for Vasum Client
+ * @author Mateusz Malicki (m.malicki2@samsung.com)
+ * @brief This file contains the public API for Vasum Client
+ * @defgroup libvasum-client libvasum-client
+ * @brief C library for interfacing Vasum
+ *
+ * All functionalities that are possible using the Vasum's Command Line Interface can also be done with libvasum-client's calls.
+ *
+ * @par Simple usage:
+ * Basic usage:
+ * - Create VsmClient with vsm_client_create(). It'll be needed for all communication with Vasum.
+ * - Establish the connection with the daemon using vsm_connect()
+ * - Do what you need to do with the zones
+ * - Free the client with vsm_client_free()
*
- * @par Example usage:
* @code
#include <stdio.h>
-#include "client/vasum-client.h"
+#include <vasum-client.h>
int main(int argc, char** argv)
{
VsmArrayString values = NULL;
int ret = 0;
- status = vsm_start_glib_loop(); // start glib loop (if not started any yet)
- if (VSMCLIENT_SUCCESS != status) {
- // error!
- return 1;
- }
-
- client = vsm_client_create(); // create client handle
+ // Create client handle
+ client = vsm_client_create();
if (NULL == client) {
// error!
ret = 1;
goto finish;
}
- status = vsm_connect(client); // connect to dbus
+ // Connect to Vasum
+ status = vsm_connect(client);
if (VSMCLIENT_SUCCESS != status) {
// error!
ret = 1;
finish:
vsm_array_string_free(values); // free memory
vsm_client_free(client); // destroy client handle
- vsm_stop_glib_loop(); // stop the glib loop (use only with vsm_start_glib_loop)
return ret;
}
@endcode
- */
+ * @par Polling loop
+ *
+ * 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.
+ * It's also possible to connect to an existing polling loop. To do this you'll need to:
+ * - Get the poll file descriptor with vsm_get_poll_fd()
+ * - Use epoll/poll/select to wait for events on the file descriptor
+ * - Call vsm_enter_eventloop() every time there's an event
+ *
+ * For example:
+ * @code
+#include <pthread.h>
+#include <assert.h>
+#include <stdio.h>
+#include <signal.h>
+#include <sys/epoll.h>
+#include <vasum-client.h>
+
+volatile static sig_atomic_t running;
+static int LOOP_INTERVAL = 1000; // ms
+
+void* main_loop(void* client)
+{
+ int fd = -1;
+ VsmStatus status = vsm_get_poll_fd(client, &fd);
+ assert(VSMCLIENT_SUCCESS == status);
+
+ while (running) {
+ struct epoll_event event;
+ int num = epoll_wait(fd, &event, 1, LOOP_INTERVAL);
+ if (num > 0) {
+ status = vsm_enter_eventloop(client, 0 , 0);
+ assert(VSMCLIENT_SUCCESS == status);
+ }
+ }
+ return NULL;
+}
+
+int main(int argc, char** argv)
+{
+ pthread_t loop;
+ VsmStatus status;
+ VsmClient client;
+ int ret = 0;
+
+ client = vsm_client_create();
+ assert(client);
+
+ status = vsm_set_dispatcher_type(client, VSMDISPATCHER_EXTERNAL);
+ assert(VSMCLIENT_SUCCESS == status);
+
+ status = vsm_connect(client);
+ assert(VSMCLIENT_SUCCESS == status);
+
+ // start event loop
+ running = 1;
+ ret = pthread_create(&loop, NULL, main_loop, client);
+ assert(ret == 0);
+
+ // make vsm_* calls on client
+ // ...
+
+ status = vsm_disconnect(client);
+ assert(VSMCLIENT_SUCCESS == status);
+
+ //stop event loop
+ running = 0;
+ ret = pthread_join(loop, NULL);
+ assert(ret == 0);
+
+ vsm_client_free(client); // destroy client handle
+ return ret;
+}
+ @endcode
+ */
+/*@{*/
#ifndef VASUM_CLIENT_H
#define VASUM_CLIENT_H
#endif
/**
- * vasum-server's client pointer.
+ * vasum-server's opaque client pointer.
*/
typedef void* VsmClient;
/**
* NULL-terminated string type.
*
- * @sa vsm_array_string_free
+ * @sa vsm_string_free
*/
typedef char* VsmString;
/**
* NULL-terminated array of strings type.
*
- * @sa vsm_string_free
+ * @sa vsm_array_string_free
*/
typedef VsmString* VsmArrayString;
+typedef void *VsmAddrList;
/**
- * Completion status of communication function.
+ * Completion status of libvasum-client's functions
*/
typedef enum {
VSMCLIENT_CUSTOM_ERROR, /**< User specified error */
} VsmZoneState;
/**
- * Zone information structure
- */
-typedef struct {
- char* id;
- int terminal;
- VsmZoneState state;
- char *rootfs_path;
-} VsmZoneStructure;
-
-/**
* Zone information
*/
-typedef VsmZoneStructure* VsmZone;
+typedef void* VsmZone;
/**
* Netowrk device type
*/
typedef enum {
- VETH,
- PHYS,
- MACVLAN
+ VSMNETDEV_VETH,
+ VSMNETDEV_PHYS,
+ VSMNETDEV_MACVLAN
} VsmNetdevType;
/**
- * Network device information structure
- */
-typedef struct {
- char* name;
- VsmNetdevType type;
-} VsmNetdevStructure;
-
-/**
* Network device information
*/
-typedef VsmNetdevStructure* VsmNetdev;
+typedef void* VsmNetdev;
/**
* File type
} VsmFileType;
/**
- * Start glib loop.
+ * Event dispacher types.
+ */
+typedef enum {
+ VSMDISPATCHER_EXTERNAL, /**< User must handle dispatching messages */
+ VSMDISPATCHER_INTERNAL /**< Library will take care of dispatching messages */
+} VsmDispacherType;
+
+/**
+ * Get file descriptor associated with event dispatcher of zone client
*
- * Do not call this function if an application creates a glib loop itself.
- * Otherwise, call it before any other function from this library.
+ * The function vsm_get_poll_fd() returns the file descriptor associated with the event dispatcher of vsm client.
+ * The file descriptor can be bound to another I/O multiplexing facilities like epoll, select, and poll.
*
+ * @param[in] client vsm client
+ * @param[out] fd epoll file descriptor
* @return status of this function call
- */
-VsmStatus vsm_start_glib_loop();
+*/
+VsmStatus vsm_get_poll_fd(VsmClient client, int* fd);
+
+/**
+ * Wait for an I/O event on a vsm client
+ *
+ * vsm_enter_eventloop() waits for event on the vsm client
+ *
+ * The call waits for a maximum time of timout milliseconds. Specifying a timeout of -1 makes vsm_enter_eventloop() wait indefinitely,
+ * while specifying a timeout equal to zero makes vsm_enter_eventloop() to return immediately even if no events are available.
+ *
+ * @param[in] client vasum-server's client
+ * @param[in] flags Reserved
+ * @param[in] timeout Timeout time (milisecond), -1 is infinite
+ * @return status of this function call
+*/
+VsmStatus vsm_enter_eventloop(VsmClient client, int flags, int timeout);
/**
- * Stop glib loop.
+ * Set dispatching method
*
- * Call only if vsm_start_glib_loop() was called.
+ * @param[in] client vasum-server's client
+ * @param[in] dispacher dispatching method
+ * @return status of this function call
+ */
+VsmStatus vsm_set_dispatcher_type(VsmClient client, VsmDispacherType dispacher);
+
+/**
+ * Get dispatching method
*
+ * @param[in] client vasum-server's client
+ * @param[out] dispacher dispatching method
* @return status of this function call
*/
-VsmStatus vsm_stop_glib_loop();
+VsmStatus vsm_get_dispatcher_type(VsmClient client, VsmDispacherType* dispacher);
/**
* Create a new vasum-server's client.
VsmStatus vsm_connect_custom(VsmClient client, const char* address);
/**
+ * Disconnect client from vasum-server.
+ *
+ * @param[in] client vasum-server's client
+ * @return status of this function call
+ */
+VsmStatus vsm_disconnect(VsmClient client);
+
+/**
* Release VsmArrayString.
*
* @param[in] astring VsmArrayString
void vsm_string_free(VsmString string);
/**
+ * Get zone id (offline)
+ *
+ * @param zone VsmZone
+ * @return zone id
+ */
+VsmString vsm_zone_get_id(VsmZone zone);
+
+/**
+ * Get zone terminal (offline)
+ *
+ * @param zone VsmZone
+ * @return zone terminal
+ */
+int vsm_zone_get_terminal(VsmZone zone);
+
+/**
+ * Get zone state (offline)
+ *
+ * @param zone VsmZone
+ * @return zone state
+ */
+VsmZoneState vsm_zone_get_state(VsmZone zone);
+
+/**
+ * Get zone rootfs path (offline)
+ *
+ * @param zone VsmZone
+ * @return zone rootfs path
+ */
+VsmString vsm_zone_get_rootfs(VsmZone zone);
+
+/**
* Release VsmZone
*
* @param zone VsmZone
void vsm_zone_free(VsmZone zone);
/**
- * Release VsmNetdev
+ * Get netdev name (offline)
*
* @param netdev VsmNetdev
+ * @return netdev name
*/
-void vsm_netdev_free(VsmNetdev netdev);
+VsmString vsm_netdev_get_name(VsmNetdev netdev);
/**
- * @name Host API
+ * Get netdev type (offline)
*
- * Functions using org.tizen.vasum.host.manager D-Bus interface.
+ * @param netdev VsmNetdev
+ * @return netdev type
+ */
+VsmNetdevType vsm_netdev_get_type(VsmNetdev netdev);
+
+/**
+ * Release VsmNetdev
*
- * @{
+ * @param netdev VsmNetdev
*/
+void vsm_netdev_free(VsmNetdev netdev);
/**
* Zone's D-Bus state change callback function signature.
*
* @param[in] zoneId affected zone id
- * @param[in] dbusAddress new D-Bus address
+ * @param[in] address new D-Bus address
* @param data custom user's data pointer passed to vsm_add_state_callback() function
*/
typedef void (*VsmZoneDbusStateCallback)(const char* zoneId,
- const char* dbusAddress,
+ const char* address,
void* data);
/**
+ * Lock the command queue exclusively.
+ *
+ * @param[in] client vasum-server's client
+ * @return status of this function call
+ */
+VsmStatus vsm_lock_queue(VsmClient client);
+
+/**
+ * Unlock the command queue.
+ *
+ * @param[in] client vasum-server's client
+ * @return status of this function call
+ */
+VsmStatus vsm_unlock_queue(VsmClient client);
+
+/**
* Get dbus address of each zone.
*
* @param[in] client vasum-server's client
*/
VsmStatus vsm_zone_get_netdevs(VsmClient client, const char* zone, VsmArrayString* netdevIds);
+
+/**
+ * Get ipv4 address for given netdevId
+ *
+ * @param[in] client vasum-server's client
+ * @param[in] zone zone name
+ * @param[in] netdevId netdev id
+ * @param[out] addrs ip address array
+ * @return status of this function call
+ * @remark Use vsm_netdev_addr_free() to free memory occupied by address array.
+ */
+VsmStatus vsm_netdev_get_ip_addr(VsmClient client,
+ const char* zone,
+ const char* netdevId,
+ VsmAddrList *addrs);
+
+/**
+ * Release VsmAddrList
+ *
+ * @param addrs VsmAddrList
+ */
+void vsm_addrlist_free(VsmAddrList addrs);
+
/**
* Get ipv4 address for given netdevId
*
struct in6_addr *addr);
/**
- * Set ipv4 address for given netdevId
+ * Add ipv4 address for given netdevId
*
* @param[in] client vasum-server's client
* @param[in] zone zone name
* @param[in] prefix bit-length of the network prefix
* @return status of this function call
*/
-VsmStatus vsm_netdev_set_ipv4_addr(VsmClient client,
+VsmStatus vsm_netdev_add_ipv4_addr(VsmClient client,
const char* zone,
const char* netdevId,
struct in_addr *addr,
int prefix);
/**
- * Set ipv6 address for given netdevId
+ * Add ipv6 address for given netdevId
*
* @param[in] client vasum-server's client
* @param[in] zone zone name
* @param[in] prefix bit-length of the network prefix
* @return status of this function call
*/
-VsmStatus vsm_netdev_set_ipv6_addr(VsmClient client,
+VsmStatus vsm_netdev_add_ipv6_addr(VsmClient client,
const char* zone,
const char* netdevId,
struct in6_addr *addr,
int prefix);
/**
+ * Remove ipv4 address from netdev
+ *
+ * @param[in] client vasum-server's client
+ * @param[in] zone zone name
+ * @param[in] netdevId network device id
+ * @param[in] addr ipv4 address
+ * @param[in] prefix bit-length of the network prefix
+ * @return status of this function call
+ */
+VsmStatus vsm_netdev_del_ipv4_addr(VsmClient client,
+ const char* zone,
+ const char* netdevId,
+ struct in_addr* addr,
+ int prefix);
+
+/**
+ * Remove ipv6 address from netdev
+ *
+ * @param[in] client vasum-server's client
+ * @param[in] zone zone name
+ * @param[in] netdevId network device id
+ * @param[in] addr ipv6 address
+ * @param[in] prefix bit-length of the network prefix
+ * @return status of this function call
+ */
+VsmStatus vsm_netdev_del_ipv6_addr(VsmClient client,
+ const char* zone,
+ const char* netdevId,
+ struct in6_addr* addr,
+ int prefix);
+
+/**
+ * Turn up a network device in the zone
+ *
+ * @param[in] client vasum-server's client
+ * @param[in] zone zone name
+ * @param[in] netdevId netdev id
+ * @return status of this function call
+ */
+VsmStatus vsm_netdev_up(VsmClient client,
+ const char* zone,
+ const char* netdevId);
+
+/**
+ * Turn down a network device in the zone
+ *
+ * @param[in] client vasum-server's client
+ * @param[in] zone zone name
+ * @param[in] netdevId netdev id
+ * @return status of this function call
+ */
+VsmStatus vsm_netdev_down(VsmClient client,
+ const char* zone,
+ const char* netdevId);
+
+
+/**
* Create veth netdev in zone
*
* @param[in] client vasum-server's client
* @param[in] zone zone name
- * @param[in] zoneDev in host network device id
- * @param[in] hostDev in zone network device id
+ * @param[in] zoneDev Device ID in Zone network
+ * @param[in] hostDev Device ID in Host network
* @return status of this function call
*/
VsmStatus vsm_create_netdev_veth(VsmClient client,
const char* zoneDev,
const char* hostDev);
/**
- * Create macvlab in zone
+ * Create macvlan in zone
*
- * @param[in] client vasum-server's client
- * @param[in] zone zone name
- * @param[in] zoneDev in host network device id
- * @param[in] hostDev in zone network device id
+ * @param[in] client vasum-server's client
+ * @param[in] zone Zone name
+ * @param[in] zoneDev Device ID in Zone network
+ * @param[in] hostDev Device ID in Host network
+ * @param[in] mode Mode with which macvlan will be created.
* @return status of this function call
+ *
+ * @see macvlan_mode
*/
VsmStatus vsm_create_netdev_macvlan(VsmClient client,
const char* zone,
* Get all declarations
*
* Gets all declarations of resourcies
- * (@see ::vsm_declare_link, @see ::vsm_declare_mount, @see ::vsm_declare_linki)
+ * (@see ::vsm_declare_link, @see ::vsm_declare_mount, @see ::vsm_declare_file)
*
* @param[in] client vasum-server's client
* @param[in] zone zone id
const char* zone,
VsmString declaration);
-
-/** @} Host API */
-
-
/**
- * @name Zone API
- *
- * Functions using org.tizen.vasum.zone.manager D-Bus interface.
+ * Clean up zones root directory
*
- * @{
+ * Removes all unknown zones root directory entry
+ * @return status of this function call
*/
+VsmStatus vsm_clean_up_zones_root(VsmClient client);
/**
- * Notification callback function signature.
- *
- * @param[in] zone source zone
- * @param[in] application sending application name
- * @param[in] message notification message
- * @param data custom user's data pointer passed to vsm_add_notification_callback()
- */
-typedef void (*VsmNotificationCallback)(const char* zone,
- const char* application,
- const char* message,
- void* data);
-/**
- * Send message to active zone.
+ * Retrieve array size
*
- * @param[in] client vasum-server's client
- * @param[in] application application name
- * @param[in] message message
- * @return status of this function call
+ * @return array size
*/
-VsmStatus vsm_notify_active_zone(VsmClient client, const char* application, const char* message);
+unsigned int vsm_addrlist_size(VsmAddrList addrs);
/**
- * Move file between zones.
+ * Get address type for i'th entry
*
- * @param[in] client vasum-server's client
- * @param[in] destZone destination zone id
- * @param[in] path path to moved file
- * @return status of this function call
+ * @return network type (AF_INET or AF_INET6)
*/
-VsmStatus vsm_file_move_request(VsmClient client, const char* destZone, const char* path);
+int vsm_addrlist_get_type(VsmAddrList addrs, unsigned int i);
/**
- * Register notification callback function.
- *
- * @note The callback function will be invoked on a different thread.
+ * Get pointer to in_addr property for i'th entry
+ * see inet_ntop man pages
*
- * @param[in] client vasum-server's client
- * @param[in] notificationCallback callback function
- * @param[in] data some extra data that will be passed to callback function
- * @param[out] subscriptionId subscription identifier that can be used to unsubscribe signal,
- * pointer can be NULL.
- * @return status of this function call
+ * @return poiner of in_addr
*/
-VsmStatus vsm_add_notification_callback(VsmClient client,
- VsmNotificationCallback notificationCallback,
- void* data,
- VsmSubscriptionId* subscriptionId);
+const void *vsm_addrlist_get_addr(VsmAddrList addrs, unsigned int i);
/**
- * Unregister notification callback function.
+ * Get address prefix for i'th entry
*
- * @param[in] client vasum-server's client
- * @param[in] subscriptionId subscription identifier returned by vsm_add_notification_callback
- * @return status of this function call
+ * @return adress prefix (mask bits count)
*/
-VsmStatus vsm_del_notification_callback(VsmClient client, VsmSubscriptionId subscriptionId);
-
-/** @} Zone API */
+unsigned int vsm_addrlist_get_prefix(VsmAddrList addrs, unsigned int i);
#ifdef __cplusplus
}
#endif
#endif /* VASUM_CLIENT_H */
+/*@}*/
projects / platform / core / security / vasum.git / blobdiff