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