/**
* @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;
- 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;
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
} VsmNetdevType;
/**
- * Network device information structure
- */
-typedef struct {
- char* name;
- VsmNetdevType type;
-} VsmNetdevStructure;
-
-/**
* Network device information
*/
-typedef VsmNetdevStructure* VsmNetdev;
+typedef void* VsmNetdev;
/**
* File type
/**
* Event dispacher types.
- *
- * @par Example usage:
- * @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
*/
typedef enum {
VSMDISPATCHER_EXTERNAL, /**< User must handle dispatching messages */
VSMDISPATCHER_INTERNAL /**< Library will take care of dispatching messages */
} VsmDispacherType;
-#ifndef __VASUM_WRAPPER_SOURCE__
-
/**
* Get file descriptor associated with event dispatcher of zone client
*
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.
VsmStatus vsm_get_active_zone_id(VsmClient client, VsmString* id);
/**
- * Get zone rootfs path.
- *
- * @param[in] client vasum-server's client
- * @param[in] id zone name
- * @param[out] rootpath zone rootfs path
- * @return status of this function call
- * @remark Use @p vsm_string_free() to free memory occupied by @p rootpath.
- */
-VsmStatus vsm_get_zone_rootpath(VsmClient client, const char* id, VsmString* rootpath);
-
-/**
* Get zone name of process with given pid.
*
* @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,
*
* @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.
+ * Retrieve array size
*
- * @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.
- *
- * @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.
+ * Get pointer to in_addr property for i'th entry
+ * see inet_ntop man pages
*
- * @note The callback function will be invoked on a different thread.
- *
- * @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);
-
-#endif /* __VASUM_WRAPPER_SOURCE__ */
-
-/** @} Zone API */
+unsigned int vsm_addrlist_get_prefix(VsmAddrList addrs, unsigned int i);
#ifdef __cplusplus
}
#endif
#endif /* VASUM_CLIENT_H */
+/*@}*/