client/vasum-client.h

   1 /*
   2  *  Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  *  Contact: Mateusz Malicki <m.malicki2@samsung.com>
   5  *
   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
   9  *
  10  *      http://www.apache.org/licenses/LICENSE-2.0
  11  *
  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
  17  */
  18
  19
  20 /**
  21  * @file
  22  * @author  Mateusz Malicki (m.malicki2@samsung.com)
  23  * @brief   This file contains the public API for Vasum Client
  24  *
  25  * @par Example usage:
  26  * @code
  27 #include <stdio.h>
  28 #include "client/vasum-client.h"
  29
  30 int main(int argc, char** argv)
  31 {
  32     VsmStatus status;
  33     VsmClient client;
  34     VsmArrayString values = NULL;
  35     int ret = 0;
  36
  37     status = vsm_start_glib_loop(); // start glib loop (if not started any yet)
  38     if (VSMCLIENT_SUCCESS != status) {
  39         // error!
  40         return 1;
  41     }
  42
  43     client = vsm_client_create(); // create client handle
  44     if (NULL == client) {
  45         // error!
  46         ret = 1;
  47         goto finish;
  48     }
  49
  50     status = vsm_connect(client); // connect to dbus
  51     if (VSMCLIENT_SUCCESS != status) {
  52         // error!
  53         ret = 1;
  54         goto finish;
  55     }
  56
  57     status = vsm_get_zone_ids(client, &values);
  58     if (VSMCLIENT_SUCCESS != status) {
  59         // error!
  60         ret = 1;
  61         goto finish;
  62     }
  63
  64     // print array
  65     for (VsmArrayString iValues = values; *iValues; iValues++) {
  66         printf("%s\n", *iValues);
  67     }
  68
  69 finish:
  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)
  73     return ret;
  74 }
  75  @endcode
  76  */
  77
  78 #ifndef VASUM_CLIENT_H
  79 #define VASUM_CLIENT_H
  80
  81 #include <stdint.h>
  82 #include <sys/stat.h>
  83 #include <netinet/ip.h>
  84
  85 #ifdef __cplusplus
  86 extern "C"
  87 {
  88 #endif
  89
  90 /**
  91  * vasum-server's client pointer.
  92  */
  93 typedef void* VsmClient;
  94
  95 /**
  96  * NULL-terminated string type.
  97  *
  98  * @sa vsm_array_string_free
  99  */
 100 typedef char* VsmString;
 101
 102 /**
 103  * NULL-terminated array of strings type.
 104  *
 105  * @sa vsm_string_free
 106  */
 107 typedef VsmString* VsmArrayString;
 108
 109 /**
 110  * Completion status of communication function.
 111  */
 112 typedef enum {
 113     VSMCLIENT_CUSTOM_ERROR,     /**< User specified error */
 114     VSMCLIENT_IO_ERROR,         /**< Input/Output error */
 115     VSMCLIENT_OPERATION_FAILED, /**< Operation failed */
 116     VSMCLIENT_INVALID_ARGUMENT, /**< Invalid argument */
 117     VSMCLIENT_OTHER_ERROR,      /**< Other error */
 118     VSMCLIENT_SUCCESS           /**< Success */
 119 } VsmStatus;
 120
 121 /**
 122  * Subscription id
 123  */
 124 typedef unsigned int VsmSubscriptionId;
 125
 126 /**
 127  * States of zone
 128  */
 129 typedef enum {
 130     STOPPED,
 131     STARTING,
 132     RUNNING,
 133     STOPPING,
 134     ABORTING,
 135     FREEZING,
 136     FROZEN,
 137     THAWED,
 138     LOCKED,
 139     MAX_STATE,
 140     ACTIVATING = 128
 141 } VsmZoneState;
 142
 143 /**
 144  * Zone information structure
 145  */
 146 typedef struct {
 147     char* id;
 148     int terminal;
 149     VsmZoneState state;
 150     char *rootfs_path;
 151 } VsmZoneStructure;
 152
 153 /**
 154  * Zone information
 155  */
 156 typedef VsmZoneStructure* VsmZone;
 157
 158 /**
 159  * Netowrk device type
 160  */
 161 typedef enum {
 162     VETH,
 163     PHYS,
 164     MACVLAN
 165 } VsmNetdevType;
 166
 167 /**
 168  * Network device information structure
 169  */
 170 typedef struct {
 171     char* name;
 172     VsmNetdevType type;
 173 } VsmNetdevStructure;
 174
 175 /**
 176  * Network device information
 177  */
 178 typedef VsmNetdevStructure* VsmNetdev;
 179
 180 /**
 181  * File type
 182  */
 183 typedef enum {
 184     VSMFILE_DIRECTORY,
 185     VSMFILE_FIFO,
 186     VSMFILE_REGULAR
 187 } VsmFileType;
 188
 189 /**
 190  * Start glib loop.
 191  *
 192  * Do not call this function if an application creates a glib loop itself.
 193  * Otherwise, call it before any other function from this library.
 194  *
 195  * @return status of this function call
 196  */
 197 VsmStatus vsm_start_glib_loop();
 198
 199 /**
 200  * Stop glib loop.
 201  *
 202  * Call only if vsm_start_glib_loop() was called.
 203  *
 204  * @return status of this function call
 205  */
 206 VsmStatus vsm_stop_glib_loop();
 207
 208 /**
 209  * Create a new vasum-server's client.
 210  *
 211  * @return Created client pointer or NULL on failure.
 212  */
 213 VsmClient vsm_client_create();
 214
 215 /**
 216  * Release client resources.
 217  *
 218  * @param[in] client vasum-server's client
 219  */
 220 void vsm_client_free(VsmClient client);
 221
 222 /**
 223  * Get status code of last vasum-server communication.
 224  *
 225  * @param[in] client vasum-server's client
 226  * @return status of this function call
 227  */
 228 VsmStatus vsm_get_status(VsmClient client);
 229
 230 /**
 231  * Get status message of the last vasum-server communication.
 232  *
 233  * @param[in] client vasum-server's client
 234  * @return last status message from vasum-server communication
 235  */
 236 const char* vsm_get_status_message(VsmClient client);
 237
 238 /**
 239  * Connect client to the vasum-server.
 240  *
 241  * @param[in] client vasum-server's client
 242  * @return status of this function call
 243  */
 244 VsmStatus vsm_connect(VsmClient client);
 245
 246 /**
 247  * Connect client to the vasum-server via custom address.
 248  *
 249  * @param[in] client vasum-server's client
 250  * @param[in] address dbus address
 251  * @return status of this function call
 252  */
 253 VsmStatus vsm_connect_custom(VsmClient client, const char* address);
 254
 255 /**
 256  * Release VsmArrayString.
 257  *
 258  * @param[in] astring VsmArrayString
 259  */
 260 void vsm_array_string_free(VsmArrayString astring);
 261
 262 /**
 263  * Release VsmString.
 264  *
 265  * @param string VsmString
 266  */
 267 void vsm_string_free(VsmString string);
 268
 269 /**
 270  * Release VsmZone
 271  *
 272  * @param zone VsmZone
 273  */
 274 void vsm_zone_free(VsmZone zone);
 275
 276 /**
 277  * Release VsmNetdev
 278  *
 279  * @param netdev VsmNetdev
 280  */
 281 void vsm_netdev_free(VsmNetdev netdev);
 282
 283 /**
 284  * @name Host API
 285  *
 286  * Functions using org.tizen.vasum.host.manager D-Bus interface.
 287  *
 288  * @{
 289  */
 290
 291 /**
 292  * Zone's D-Bus state change callback function signature.
 293  *
 294  * @param[in] zoneId affected zone id
 295  * @param[in] dbusAddress new D-Bus address
 296  * @param data custom user's data pointer passed to vsm_add_state_callback() function
 297  */
 298 typedef void (*VsmZoneDbusStateCallback)(const char* zoneId,
 299                                              const char* dbusAddress,
 300                                              void* data);
 301
 302 /**
 303  * Get dbus address of each zone.
 304  *
 305  * @param[in] client vasum-server's client
 306  * @param[out] keys array of zones name
 307  * @param[out] values array of zones dbus address
 308  * @return status of this function call
 309  * @post keys[i] corresponds to values[i]
 310  * @remark Use vsm_array_string_free() to free memory occupied by @p keys and @p values.
 311  */
 312 VsmStatus vsm_get_zone_dbuses(VsmClient client, VsmArrayString* keys, VsmArrayString* values);
 313
 314 /**
 315  * Get zones name.
 316  *
 317  * @param[in] client vasum-server's client
 318  * @param[out] array array of zones name
 319  * @return status of this function call
 320  * @remark Use vsm_array_string_free() to free memory occupied by @p array.
 321  */
 322 VsmStatus vsm_get_zone_ids(VsmClient client, VsmArrayString* array);
 323
 324 /**
 325  * Get active (foreground) zone name.
 326  *
 327  * @param[in] client vasum-server's client
 328  * @param[out] id active zone name
 329  * @return status of this function call
 330  * @remark Use @p vsm_string_free() to free memory occupied by @p id.
 331  */
 332 VsmStatus vsm_get_active_zone_id(VsmClient client, VsmString* id);
 333
 334 /**
 335  * Get zone name of process with given pid.
 336  *
 337  * @param[in] client vasum-server's client
 338  * @param[in] pid process id
 339  * @param[out] id active zone name
 340  * @return status of this function call
 341  * @remark Use @p vsm_string_free() to free memory occupied by @p id.
 342  */
 343 VsmStatus vsm_lookup_zone_by_pid(VsmClient client, int pid, VsmString* id);
 344
 345 /**
 346  * Get zone informations of zone with given id.
 347  *
 348  * @param[in] client vasum-server's client
 349  * @param[in] id zone name
 350  * @param[out] zone zone informations
 351  * @return status of this function call
 352  * @remark Use @p vsm_zone_free() to free memory occupied by @p zone
 353  */
 354 VsmStatus vsm_lookup_zone_by_id(VsmClient client, const char* id, VsmZone* zone);
 355
 356 /**
 357  * Get zone name with given terminal.
 358  *
 359  * @param[in] client vasum-server's client
 360  * @param[in] terminal terminal id
 361  * @param[out] id zone name with given terminal
 362  * @return status of this function call
 363  * @remark Use @p vsm_string_free() to free memory occupied by @p id.
 364  */
 365 VsmStatus vsm_lookup_zone_by_terminal_id(VsmClient client, int terminal, VsmString* id);
 366
 367 /**
 368  * Set active (foreground) zone.
 369  *
 370  * @param[in] client vasum-server's client
 371  * @param[in] id zone name
 372  * @return status of this function call
 373  */
 374 VsmStatus vsm_set_active_zone(VsmClient client, const char* id);
 375
 376 /**
 377  * Create and add zone
 378  *
 379  * @param[in] client vasum-server's client
 380  * @param[in] id zone id
 381  * @param[in] tname template name, NULL for default
 382  * @return status of this function call
 383  */
 384 VsmStatus vsm_create_zone(VsmClient client, const char* id, const char* tname);
 385
 386 /**
 387  * Remove zone
 388  *
 389  * @param[in] client vasum-server's client
 390  * @param[in] id zone id
 391  * @param[in] force if 0 data will be kept, otherwise data will be lost
 392  * @return status of this function call
 393  */
 394 VsmStatus vsm_destroy_zone(VsmClient client, const char* id, int force);
 395
 396 /**
 397  * Shutdown zone
 398  *
 399  * @param[in] client vasum-server's client
 400  * @param[in] id zone name
 401  * @return status of this function call
 402  */
 403 VsmStatus vsm_shutdown_zone(VsmClient client, const char* id);
 404
 405 /**
 406  * Start zone
 407  *
 408  * @param[in] client vasum-server's client
 409  * @param[in] id zone name
 410  * @return status of this function call
 411  */
 412 VsmStatus vsm_start_zone(VsmClient client, const char* id);
 413
 414 /**
 415  * Lock zone
 416  *
 417  * @param[in] client vasum-server's client
 418  * @param[in] id zone name
 419  * @return status of this function call
 420  */
 421 VsmStatus vsm_lock_zone(VsmClient client, const char* id);
 422
 423 /**
 424  * Unlock zone
 425  *
 426  * @param[in] client vasum-server's client
 427  * @param[in] id zone name
 428  * @return status of this function call
 429  */
 430 VsmStatus vsm_unlock_zone(VsmClient client, const char* id);
 431
 432 /**
 433  * Register dbus state change callback function.
 434  *
 435  * @note The callback function will be invoked on a different thread.
 436  *
 437  * @param[in] client vasum-server's client
 438  * @param[in] zoneDbusStateCallback callback function
 439  * @param[in] data some extra data that will be passed to callback function
 440  * @param[out] subscriptionId subscription identifier that can be used to unsubscribe signal,
 441  *                      pointer can be NULL.
 442  * @return status of this function call
 443  */
 444 VsmStatus vsm_add_state_callback(VsmClient client,
 445                                  VsmZoneDbusStateCallback zoneDbusStateCallback,
 446                                  void* data,
 447                                  VsmSubscriptionId* subscriptionId);
 448
 449 /**
 450  * Unregister dbus state change callback function.
 451  *
 452  * @param[in] client vasum-server's client
 453  * @param[in] subscriptionId subscription identifier returned by vsm_add_state_callback
 454  * @return status of this function call
 455  */
 456 VsmStatus vsm_del_state_callback(VsmClient client, VsmSubscriptionId subscriptionId);
 457
 458 /**
 459  * Grant access to device
 460  *
 461  * @param[in] client vasum-server's client
 462  * @param[in] zone zone name
 463  * @param[in] device device path
 464  * @param[in] flags access flags
 465  * @return status of this function call
 466  */
 467 VsmStatus vsm_grant_device(VsmClient client,
 468                            const char* zone,
 469                            const char* device,
 470                            uint32_t flags);
 471
 472 /**
 473  * Revoke access to device
 474  *
 475  * @param[in] client vasum-server's client
 476  * @param[in] zone zone name
 477  * @param[in] device device path
 478  * @return status of this function call
 479  */
 480 VsmStatus vsm_revoke_device(VsmClient client, const char* zone, const char* device);
 481
 482 /**
 483  * Get array of netdev from given zone
 484  *
 485  * @param[in] client vasum-server's client
 486  * @param[in] zone zone name
 487  * @param[out] netdevIds array of netdev id
 488  * @return status of this function call
 489  * @remark Use vsm_array_string_free() to free memory occupied by @p netdevIds.
 490  */
 491 VsmStatus vsm_zone_get_netdevs(VsmClient client, const char* zone, VsmArrayString* netdevIds);
 492
 493 /**
 494  * Get ipv4 address for given netdevId
 495  *
 496  * @param[in] client vasum-server's client
 497  * @param[in] zone zone name
 498  * @param[in] netdevId netdev id
 499  * @param[out] addr ipv4 address
 500  * @return status of this function call
 501  */
 502 VsmStatus vsm_netdev_get_ipv4_addr(VsmClient client,
 503                                    const char* zone,
 504                                    const char* netdevId,
 505                                    struct in_addr *addr);
 506
 507 /**
 508  * Get ipv6 address for given netdevId
 509  *
 510  * @param[in] client vasum-server's client
 511  * @param[in] zone zone name
 512  * @param[in] netdevId netdev id
 513  * @param[out] addr ipv6 address
 514  * @return status of this function call
 515  */
 516 VsmStatus vsm_netdev_get_ipv6_addr(VsmClient client,
 517                                    const char* zone,
 518                                    const char* netdevId,
 519                                    struct in6_addr *addr);
 520
 521 /**
 522  * Set ipv4 address for given netdevId
 523  *
 524  * @param[in] client vasum-server's client
 525  * @param[in] zone zone name
 526  * @param[in] netdevId netdev id
 527  * @param[in] addr ipv4 address
 528  * @param[in] prefix bit-length of the network prefix
 529  * @return status of this function call
 530  */
 531 VsmStatus vsm_netdev_set_ipv4_addr(VsmClient client,
 532                                    const char* zone,
 533                                    const char* netdevId,
 534                                    struct in_addr *addr,
 535                                    int prefix);
 536
 537 /**
 538  * Set ipv6 address for given netdevId
 539  *
 540  * @param[in] client vasum-server's client
 541  * @param[in] zone zone name
 542  * @param[in] netdevId netdev id
 543  * @param[in] addr ipv6 address
 544  * @param[in] prefix bit-length of the network prefix
 545  * @return status of this function call
 546  */
 547 VsmStatus vsm_netdev_set_ipv6_addr(VsmClient client,
 548                                    const char* zone,
 549                                    const char* netdevId,
 550                                    struct in6_addr *addr,
 551                                    int prefix);
 552
 553 /**
 554  * Create netdev in zone
 555  *
 556  * @param[in] client vasum-server's client
 557  * @param[in] zone zone name
 558  * @param[in] netdevType netdev type
 559  * @param[in] target TODO: this is taken form zone-control
 560  * @param[in] netdevId network device id
 561  * @return status of this function call
 562  */
 563 VsmStatus vsm_create_netdev(VsmClient client,
 564                             const char* zone,
 565                             VsmNetdevType netdevType,
 566                             const char* target,
 567                             const char* netdevId);
 568
 569 /**
 570  * Remove netdev from zone
 571  *
 572  * @param[in] client vasum-server's client
 573  * @param[in] zone zone name
 574  * @param[in] netdevId network device id
 575  * @return status of this function call
 576  */
 577 VsmStatus vsm_destroy_netdev(VsmClient client, const char* zone, const char* netdevId);
 578
 579 /**
 580  * Get netdev informations
 581  *
 582  * @param[in] client vasum-server's client
 583  * @param[in] zone zone name
 584  * @param[in] netdevId network device id
 585  * @param[out] netdev netdev informations
 586  * @return status of this function call
 587  * @remark Use vsm_netdev_free() to free memory occupied by @p netdev.
 588  */
 589 VsmStatus vsm_lookup_netdev_by_name(VsmClient client,
 590                                     const char* zone,
 591                                     const char* netdevId,
 592                                     VsmNetdev* netdev);
 593
 594 /**
 595  * Create file, directory or pipe in zone
 596  *
 597  * Declare file, directory or pipe that will be created while zone startup
 598  *
 599  * @param[in] client vasum-server's client
 600  * @param[in] type file type
 601  * @param[in] zone zone id
 602  * @param[in] path path to file
 603  * @param[in] flags if O_CREAT bit is set then file will be created in zone,
 604  *                  otherwise file will by copied from host;
 605  *                  it is meaningful only when O_CREAT is set
 606  * @param[in] mode mode of file
 607  * @return status of this function call
 608  */
 609 VsmStatus vsm_declare_file(VsmClient client,
 610                            const char* zone,
 611                            VsmFileType type,
 612                            const char* path,
 613                            int32_t flags,
 614                            mode_t mode);
 615
 616 /**
 617  * Create mount point in zone
 618  *
 619  * Declare mount that will be created while zone startup
 620  * Parameters are passed to mount system function
 621  *
 622  * @param[in] client vasum-server's client
 623  * @param[in] source device path (path in host)
 624  * @param[in] zone zone id
 625  * @param[in] target mount point (path in zone)
 626  * @param[in] type filesystem type
 627  * @param[in] flags mount flags as in mount function
 628  * @param[in] data additional data as in mount function
 629  * @return status of this function call
 630  */
 631 VsmStatus vsm_declare_mount(VsmClient client,
 632                             const char* source,
 633                             const char* zone,
 634                             const char* target,
 635                             const char* type,
 636                             uint64_t flags,
 637                             const char* data);
 638
 639 /**
 640  * Create link in zone
 641  *
 642  * Declare link that will be created while zone startup
 643  * Parameters are passed to link system function
 644  *
 645  * @param[in] client vasum-server's client
 646  * @param[in] source path to link source (in host)
 647  * @param[in] zone zone id
 648  * @param[in] target path to link name (in zone)
 649  * @return status of this function call
 650  */
 651 VsmStatus vsm_declare_link(VsmClient client,
 652                            const char *source,
 653                            const char* zone,
 654                            const char *target);
 655
 656 /**
 657  * Get all declarations
 658  *
 659  * Gets all declarations of resourcies
 660  * (@see ::vsm_declare_link, @see ::vsm_declare_mount, @see ::vsm_declare_linki)
 661  *
 662  * @param[in] client vasum-server's client
 663  * @param[in] zone zone id
 664  * @param[out] declarations array of declarations id
 665  * @return status of this function call
 666  */
 667 VsmStatus vsm_list_declarations(VsmClient client,
 668                                 const char* zone,
 669                                 VsmArrayString* declarations);
 670
 671 /**
 672  * Remove declaration
 673  *
 674  * Removes given declaration by its id (@see ::vsm_list_declarations)
 675  *
 676  * @param[in] client vasum-server's client
 677  * @param[in] zone zone id
 678  * @param[in] declaration declaration id
 679  * @return status of this function call
 680  */
 681 VsmStatus vsm_remove_declaration(VsmClient client,
 682                                  const char* zone,
 683                                  VsmString declaration);
 684
 685
 686 /** @} Host API */
 687
 688
 689 /**
 690  * @name Zone API
 691  *
 692  * Functions using org.tizen.vasum.zone.manager D-Bus interface.
 693  *
 694  * @{
 695  */
 696
 697 /**
 698  * Notification callback function signature.
 699  *
 700  * @param[in] zone source zone
 701  * @param[in] application sending application name
 702  * @param[in] message notification message
 703  * @param data custom user's data pointer passed to vsm_add_notification_callback()
 704  */
 705 typedef void (*VsmNotificationCallback)(const char* zone,
 706                                        const char* application,
 707                                        const char* message,
 708                                        void* data);
 709 /**
 710  * Send message to active zone.
 711  *
 712  * @param[in] client vasum-server's client
 713  * @param[in] application application name
 714  * @param[in] message message
 715  * @return status of this function call
 716  */
 717 VsmStatus vsm_notify_active_zone(VsmClient client, const char* application, const char* message);
 718
 719 /**
 720  * Move file between zones.
 721  *
 722  * @param[in] client vasum-server's client
 723  * @param[in] destZone destination zone id
 724  * @param[in] path path to moved file
 725  * @return status of this function call
 726  */
 727 VsmStatus vsm_file_move_request(VsmClient client, const char* destZone, const char* path);
 728
 729 /**
 730  * Register notification callback function.
 731  *
 732  * @note The callback function will be invoked on a different thread.
 733  *
 734  * @param[in] client vasum-server's client
 735  * @param[in] notificationCallback callback function
 736  * @param[in] data some extra data that will be passed to callback function
 737  * @param[out] subscriptionId subscription identifier that can be used to unsubscribe signal,
 738  *                      pointer can be NULL.
 739  * @return status of this function call
 740  */
 741 VsmStatus vsm_add_notification_callback(VsmClient client,
 742                                         VsmNotificationCallback notificationCallback,
 743                                         void* data,
 744                                         VsmSubscriptionId* subscriptionId);
 745
 746 /**
 747  * Unregister notification callback function.
 748  *
 749  * @param[in] client vasum-server's client
 750  * @param[in] subscriptionId subscription identifier returned by vsm_add_notification_callback
 751  * @return status of this function call
 752  */
 753 VsmStatus vsm_del_notification_callback(VsmClient client, VsmSubscriptionId subscriptionId);
 754
 755 /** @} Zone API */
 756
 757 #ifdef __cplusplus
 758 }
 759 #endif
 760
 761 #endif /* VASUM_CLIENT_H */