ceph/src/include/rbd/librbd.hpp

   1 // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
   2 // vim: ts=8 sw=2 smarttab
   3 /*
   4  * Ceph - scalable distributed file system
   5  *
   6  * Copyright (C) 2011 New Dream Network
   7  *
   8  * This is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License version 2.1, as published by the Free Software
  11  * Foundation.  See file COPYING.
  12  *
  13  */
  14
  15 #ifndef __LIBRBD_HPP
  16 #define __LIBRBD_HPP
  17
  18 #include <string>
  19 #include <list>
  20 #include <map>
  21 #include <vector>
  22 #include "../rados/buffer.h"
  23 #include "../rados/librados.hpp"
  24 #include "librbd.h"
  25
  26 #if __GNUC__ >= 4
  27   #pragma GCC diagnostic push
  28   #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
  29 #endif
  30
  31 namespace librbd {
  32
  33   using librados::IoCtx;
  34
  35   class Image;
  36   class ImageOptions;
  37   class PoolStats;
  38   typedef void *image_ctx_t;
  39   typedef void *completion_t;
  40   typedef void (*callback_t)(completion_t cb, void *arg);
  41
  42   typedef struct {
  43     std::string id;
  44     std::string name;
  45   } image_spec_t;
  46
  47   typedef struct {
  48     int64_t pool_id;
  49     std::string pool_name;
  50     std::string pool_namespace;
  51     std::string image_id;
  52     std::string image_name;
  53     bool trash;
  54   } linked_image_spec_t;
  55
  56   typedef rbd_snap_namespace_type_t snap_namespace_type_t;
  57
  58   typedef struct {
  59     uint64_t id;
  60     snap_namespace_type_t namespace_type;
  61     std::string name;
  62   } snap_spec_t;
  63
  64   typedef struct {
  65     uint64_t id;
  66     uint64_t size;
  67     std::string name;
  68   } snap_info_t;
  69
  70   typedef struct {
  71     int64_t group_pool;
  72     std::string group_name;
  73     std::string group_snap_name;
  74   } snap_group_namespace_t;
  75
  76   typedef rbd_snap_mirror_state_t snap_mirror_state_t;
  77
  78   typedef struct {
  79     snap_mirror_state_t state;
  80     std::set<std::string> mirror_peer_uuids;
  81     bool complete;
  82     std::string primary_mirror_uuid;
  83     uint64_t primary_snap_id;
  84     uint64_t last_copied_object_number;
  85   } snap_mirror_namespace_t;
  86
  87   typedef struct {
  88     std::string client;
  89     std::string cookie;
  90     std::string address;
  91   } locker_t;
  92
  93   typedef rbd_mirror_peer_direction_t mirror_peer_direction_t;
  94
  95   typedef struct {
  96     std::string uuid;
  97     std::string cluster_name;
  98     std::string client_name;
  99   } mirror_peer_t CEPH_RBD_DEPRECATED;
 100
 101   typedef struct {
 102     std::string uuid;
 103     mirror_peer_direction_t direction;
 104     std::string site_name;
 105     std::string mirror_uuid;
 106     std::string client_name;
 107     time_t last_seen;
 108   } mirror_peer_site_t;
 109
 110   typedef rbd_mirror_image_mode_t mirror_image_mode_t;
 111   typedef rbd_mirror_image_state_t mirror_image_state_t;
 112
 113   typedef struct {
 114     std::string global_id;
 115     mirror_image_state_t state;
 116     bool primary;
 117   } mirror_image_info_t;
 118
 119   typedef rbd_mirror_image_status_state_t mirror_image_status_state_t;
 120
 121   typedef struct {
 122     std::string name;
 123     mirror_image_info_t info;
 124     mirror_image_status_state_t state;
 125     std::string description;
 126     time_t last_update;
 127     bool up;
 128   } mirror_image_status_t CEPH_RBD_DEPRECATED;
 129
 130   typedef struct {
 131     std::string mirror_uuid;
 132     mirror_image_status_state_t state;
 133     std::string description;
 134     time_t last_update;
 135     bool up;
 136   } mirror_image_site_status_t;
 137
 138   typedef struct {
 139     std::string name;
 140     mirror_image_info_t info;
 141     std::vector<mirror_image_site_status_t> site_statuses;
 142   } mirror_image_global_status_t;
 143
 144   typedef rbd_group_image_state_t group_image_state_t;
 145
 146   typedef struct {
 147     std::string name;
 148     int64_t pool;
 149     group_image_state_t state;
 150   } group_image_info_t;
 151
 152   typedef struct {
 153     std::string name;
 154     int64_t pool;
 155   } group_info_t;
 156
 157   typedef rbd_group_snap_state_t group_snap_state_t;
 158
 159   typedef struct {
 160     std::string name;
 161     group_snap_state_t state;
 162   } group_snap_info_t;
 163
 164   typedef rbd_image_info_t image_info_t;
 165
 166   class CEPH_RBD_API ProgressContext
 167   {
 168   public:
 169     virtual ~ProgressContext();
 170     virtual int update_progress(uint64_t offset, uint64_t total) = 0;
 171   };
 172
 173   typedef struct {
 174     std::string id;
 175     std::string name;
 176     rbd_trash_image_source_t source;
 177     time_t deletion_time;
 178     time_t deferment_end_time;
 179   } trash_image_info_t;
 180
 181   typedef struct {
 182     std::string pool_name;
 183     std::string image_name;
 184     std::string image_id;
 185     bool trash;
 186   } child_info_t;
 187
 188   typedef struct {
 189     std::string addr;
 190     int64_t id;
 191     uint64_t cookie;
 192   } image_watcher_t;
 193
 194   typedef rbd_image_migration_state_t image_migration_state_t;
 195
 196   typedef struct {
 197     int64_t source_pool_id;
 198     std::string source_pool_namespace;
 199     std::string source_image_name;
 200     std::string source_image_id;
 201     int64_t dest_pool_id;
 202     std::string dest_pool_namespace;
 203     std::string dest_image_name;
 204     std::string dest_image_id;
 205     image_migration_state_t state;
 206     std::string state_description;
 207   } image_migration_status_t;
 208
 209   typedef rbd_config_source_t config_source_t;
 210
 211   typedef struct {
 212     std::string name;
 213     std::string value;
 214     config_source_t source;
 215   } config_option_t;
 216
 217   typedef rbd_encryption_format_t encryption_format_t;
 218   typedef rbd_encryption_algorithm_t encryption_algorithm_t;
 219   typedef rbd_encryption_options_t encryption_options_t;
 220   typedef rbd_encryption_spec_t encryption_spec_t;
 221
 222   typedef struct {
 223     encryption_algorithm_t alg;
 224     std::string passphrase;
 225   } encryption_luks1_format_options_t;
 226
 227   typedef struct {
 228     encryption_algorithm_t alg;
 229     std::string passphrase;
 230   } encryption_luks2_format_options_t;
 231
 232   typedef struct {
 233     std::string passphrase;
 234   } encryption_luks_format_options_t;
 235
 236 class CEPH_RBD_API RBD
 237 {
 238 public:
 239   RBD();
 240   ~RBD();
 241
 242   // This must be dynamically allocated with new, and
 243   // must be released with release().
 244   // Do not use delete.
 245   struct AioCompletion {
 246     void *pc;
 247     AioCompletion(void *cb_arg, callback_t complete_cb);
 248     bool is_complete();
 249     int wait_for_complete();
 250     ssize_t get_return_value();
 251     void *get_arg();
 252     void release();
 253   };
 254
 255   void version(int *major, int *minor, int *extra);
 256
 257   int open(IoCtx& io_ctx, Image& image, const char *name);
 258   int open(IoCtx& io_ctx, Image& image, const char *name, const char *snapname);
 259   int open_by_id(IoCtx& io_ctx, Image& image, const char *id);
 260   int open_by_id(IoCtx& io_ctx, Image& image, const char *id, const char *snapname);
 261   int aio_open(IoCtx& io_ctx, Image& image, const char *name,
 262                const char *snapname, RBD::AioCompletion *c);
 263   int aio_open_by_id(IoCtx& io_ctx, Image& image, const char *id,
 264                      const char *snapname, RBD::AioCompletion *c);
 265   // see librbd.h
 266   int open_read_only(IoCtx& io_ctx, Image& image, const char *name,
 267                      const char *snapname);
 268   int open_by_id_read_only(IoCtx& io_ctx, Image& image, const char *id,
 269                            const char *snapname);
 270   int aio_open_read_only(IoCtx& io_ctx, Image& image, const char *name,
 271                          const char *snapname, RBD::AioCompletion *c);
 272   int aio_open_by_id_read_only(IoCtx& io_ctx, Image& image, const char *id,
 273                                const char *snapname, RBD::AioCompletion *c);
 274   int features_to_string(uint64_t features, std::string *str_features);
 275   int features_from_string(const std::string str_features, uint64_t *features);
 276
 277   int list(IoCtx& io_ctx, std::vector<std::string>& names)
 278     CEPH_RBD_DEPRECATED;
 279   int list2(IoCtx& io_ctx, std::vector<image_spec_t>* images);
 280
 281   int create(IoCtx& io_ctx, const char *name, uint64_t size, int *order);
 282   int create2(IoCtx& io_ctx, const char *name, uint64_t size,
 283               uint64_t features, int *order);
 284   int create3(IoCtx& io_ctx, const char *name, uint64_t size,
 285               uint64_t features, int *order,
 286               uint64_t stripe_unit, uint64_t stripe_count);
 287   int create4(IoCtx& io_ctx, const char *name, uint64_t size,
 288               ImageOptions& opts);
 289   int clone(IoCtx& p_ioctx, const char *p_name, const char *p_snapname,
 290                IoCtx& c_ioctx, const char *c_name, uint64_t features,
 291                int *c_order);
 292   int clone2(IoCtx& p_ioctx, const char *p_name, const char *p_snapname,
 293              IoCtx& c_ioctx, const char *c_name, uint64_t features,
 294              int *c_order, uint64_t stripe_unit, int stripe_count);
 295   int clone3(IoCtx& p_ioctx, const char *p_name, const char *p_snapname,
 296              IoCtx& c_ioctx, const char *c_name, ImageOptions& opts);
 297   int remove(IoCtx& io_ctx, const char *name);
 298   int remove_with_progress(IoCtx& io_ctx, const char *name, ProgressContext& pctx);
 299   int rename(IoCtx& src_io_ctx, const char *srcname, const char *destname);
 300
 301   int trash_move(IoCtx &io_ctx, const char *name, uint64_t delay);
 302   int trash_get(IoCtx &io_ctx, const char *id, trash_image_info_t *info);
 303   int trash_list(IoCtx &io_ctx, std::vector<trash_image_info_t> &entries);
 304   int trash_purge(IoCtx &io_ctx, time_t expire_ts, float threshold);
 305   int trash_purge_with_progress(IoCtx &io_ctx, time_t expire_ts, float threshold,
 306                                 ProgressContext &pctx);
 307   int trash_remove(IoCtx &io_ctx, const char *image_id, bool force);
 308   int trash_remove_with_progress(IoCtx &io_ctx, const char *image_id,
 309                                  bool force, ProgressContext &pctx);
 310   int trash_restore(IoCtx &io_ctx, const char *id, const char *name);
 311
 312   // Migration
 313   int migration_prepare(IoCtx& io_ctx, const char *image_name,
 314                         IoCtx& dest_io_ctx, const char *dest_image_name,
 315                         ImageOptions& opts);
 316   int migration_prepare_import(const char *source_spec, IoCtx& dest_io_ctx,
 317                                const char *dest_image_name, ImageOptions& opts);
 318   int migration_execute(IoCtx& io_ctx, const char *image_name);
 319   int migration_execute_with_progress(IoCtx& io_ctx, const char *image_name,
 320                                       ProgressContext &prog_ctx);
 321   int migration_abort(IoCtx& io_ctx, const char *image_name);
 322   int migration_abort_with_progress(IoCtx& io_ctx, const char *image_name,
 323                                     ProgressContext &prog_ctx);
 324   int migration_commit(IoCtx& io_ctx, const char *image_name);
 325   int migration_commit_with_progress(IoCtx& io_ctx, const char *image_name,
 326                                      ProgressContext &prog_ctx);
 327   int migration_status(IoCtx& io_ctx, const char *image_name,
 328                        image_migration_status_t *status, size_t status_size);
 329
 330   // RBD pool mirroring support functions
 331   int mirror_site_name_get(librados::Rados& rados, std::string* site_name);
 332   int mirror_site_name_set(librados::Rados& rados,
 333                            const std::string& site_name);
 334
 335   int mirror_mode_get(IoCtx& io_ctx, rbd_mirror_mode_t *mirror_mode);
 336   int mirror_mode_set(IoCtx& io_ctx, rbd_mirror_mode_t mirror_mode);
 337
 338   int mirror_uuid_get(IoCtx& io_ctx, std::string* mirror_uuid);
 339
 340   int mirror_peer_bootstrap_create(IoCtx& io_ctx, std::string* token);
 341   int mirror_peer_bootstrap_import(IoCtx& io_ctx,
 342                                    mirror_peer_direction_t direction,
 343                                    const std::string &token);
 344
 345   int mirror_peer_site_add(IoCtx& io_ctx, std::string *uuid,
 346                            mirror_peer_direction_t direction,
 347                            const std::string &site_name,
 348                            const std::string &client_name);
 349   int mirror_peer_site_set_name(IoCtx& io_ctx, const std::string& uuid,
 350                                 const std::string &site_name);
 351   int mirror_peer_site_set_client_name(IoCtx& io_ctx, const std::string& uuid,
 352                                        const std::string &client_name);
 353   int mirror_peer_site_set_direction(IoCtx& io_ctx, const std::string& uuid,
 354                                      mirror_peer_direction_t direction);
 355   int mirror_peer_site_remove(IoCtx& io_ctx, const std::string& uuid);
 356   int mirror_peer_site_list(IoCtx& io_ctx,
 357                             std::vector<mirror_peer_site_t> *peers);
 358   int mirror_peer_site_get_attributes(
 359       IoCtx& io_ctx, const std::string &uuid,
 360       std::map<std::string, std::string> *key_vals);
 361   int mirror_peer_site_set_attributes(
 362       IoCtx& io_ctx, const std::string &uuid,
 363       const std::map<std::string, std::string>& key_vals);
 364
 365   int mirror_image_global_status_list(
 366       IoCtx& io_ctx, const std::string &start_id, size_t max,
 367       std::map<std::string, mirror_image_global_status_t> *images);
 368   int mirror_image_status_summary(IoCtx& io_ctx,
 369       std::map<mirror_image_status_state_t, int> *states);
 370   int mirror_image_instance_id_list(IoCtx& io_ctx, const std::string &start_id,
 371       size_t max, std::map<std::string, std::string> *sevice_ids);
 372   int mirror_image_info_list(IoCtx& io_ctx, mirror_image_mode_t *mode_filter,
 373       const std::string &start_id, size_t max,
 374       std::map<std::string, std::pair<mirror_image_mode_t,
 375                                       mirror_image_info_t>> *entries);
 376
 377   /// mirror_peer_ commands are deprecated to mirror_peer_site_ equivalents
 378   int mirror_peer_add(IoCtx& io_ctx, std::string *uuid,
 379                       const std::string &cluster_name,
 380                       const std::string &client_name)
 381     CEPH_RBD_DEPRECATED;
 382   int mirror_peer_remove(IoCtx& io_ctx, const std::string &uuid)
 383     CEPH_RBD_DEPRECATED;
 384   int mirror_peer_list(IoCtx& io_ctx, std::vector<mirror_peer_t> *peers)
 385     CEPH_RBD_DEPRECATED;
 386   int mirror_peer_set_client(IoCtx& io_ctx, const std::string &uuid,
 387                              const std::string &client_name)
 388     CEPH_RBD_DEPRECATED;
 389   int mirror_peer_set_cluster(IoCtx& io_ctx, const std::string &uuid,
 390                               const std::string &cluster_name)
 391     CEPH_RBD_DEPRECATED;
 392   int mirror_peer_get_attributes(
 393       IoCtx& io_ctx, const std::string &uuid,
 394       std::map<std::string, std::string> *key_vals)
 395     CEPH_RBD_DEPRECATED;
 396   int mirror_peer_set_attributes(
 397       IoCtx& io_ctx, const std::string &uuid,
 398       const std::map<std::string, std::string>& key_vals)
 399     CEPH_RBD_DEPRECATED;
 400
 401   /// mirror_image_status_list command is deprecated to
 402   /// mirror_image_global_status_list
 403
 404   int mirror_image_status_list(
 405       IoCtx& io_ctx, const std::string &start_id, size_t max,
 406       std::map<std::string, mirror_image_status_t> *images)
 407     CEPH_RBD_DEPRECATED;
 408
 409   // RBD groups support functions
 410   int group_create(IoCtx& io_ctx, const char *group_name);
 411   int group_remove(IoCtx& io_ctx, const char *group_name);
 412   int group_list(IoCtx& io_ctx, std::vector<std::string> *names);
 413   int group_rename(IoCtx& io_ctx, const char *src_group_name,
 414                    const char *dest_group_name);
 415
 416   int group_image_add(IoCtx& io_ctx, const char *group_name,
 417                       IoCtx& image_io_ctx, const char *image_name);
 418   int group_image_remove(IoCtx& io_ctx, const char *group_name,
 419                          IoCtx& image_io_ctx, const char *image_name);
 420   int group_image_remove_by_id(IoCtx& io_ctx, const char *group_name,
 421                                IoCtx& image_io_ctx, const char *image_id);
 422   int group_image_list(IoCtx& io_ctx, const char *group_name,
 423                        std::vector<group_image_info_t> *images,
 424                        size_t group_image_info_size);
 425
 426   int group_snap_create(IoCtx& io_ctx, const char *group_name,
 427                         const char *snap_name);
 428   int group_snap_create2(IoCtx& io_ctx, const char *group_name,
 429                          const char *snap_name, uint32_t flags);
 430   int group_snap_remove(IoCtx& io_ctx, const char *group_name,
 431                         const char *snap_name);
 432   int group_snap_rename(IoCtx& group_ioctx, const char *group_name,
 433                         const char *old_snap_name, const char *new_snap_name);
 434   int group_snap_list(IoCtx& group_ioctx, const char *group_name,
 435                       std::vector<group_snap_info_t> *snaps,
 436                       size_t group_snap_info_size);
 437   int group_snap_rollback(IoCtx& io_ctx, const char *group_name,
 438                           const char *snap_name);
 439   int group_snap_rollback_with_progress(IoCtx& io_ctx, const char *group_name,
 440                                         const char *snap_name,
 441                                         ProgressContext& pctx);
 442
 443   int namespace_create(IoCtx& ioctx, const char *namespace_name);
 444   int namespace_remove(IoCtx& ioctx, const char *namespace_name);
 445   int namespace_list(IoCtx& io_ctx, std::vector<std::string>* namespace_names);
 446   int namespace_exists(IoCtx& io_ctx, const char *namespace_name, bool *exists);
 447
 448   int pool_init(IoCtx& io_ctx, bool force);
 449   int pool_stats_get(IoCtx& io_ctx, PoolStats *pool_stats);
 450
 451   int pool_metadata_get(IoCtx &io_ctx, const std::string &key,
 452                         std::string *value);
 453   int pool_metadata_set(IoCtx &io_ctx, const std::string &key,
 454                         const std::string &value);
 455   int pool_metadata_remove(IoCtx &io_ctx, const std::string &key);
 456   int pool_metadata_list(IoCtx &io_ctx, const std::string &start, uint64_t max,
 457                          std::map<std::string, ceph::bufferlist> *pairs);
 458
 459   int config_list(IoCtx& io_ctx, std::vector<config_option_t> *options);
 460
 461 private:
 462   /* We don't allow assignment or copying */
 463   RBD(const RBD& rhs);
 464   const RBD& operator=(const RBD& rhs);
 465 };
 466
 467 class CEPH_RBD_API ImageOptions {
 468 public:
 469   ImageOptions();
 470   ImageOptions(rbd_image_options_t opts);
 471   ImageOptions(const ImageOptions &imgopts);
 472   ~ImageOptions();
 473
 474   int set(int optname, const std::string& optval);
 475   int set(int optname, uint64_t optval);
 476   int get(int optname, std::string* optval) const;
 477   int get(int optname, uint64_t* optval) const;
 478   int is_set(int optname, bool* is_set);
 479   int unset(int optname);
 480   void clear();
 481   bool empty() const;
 482
 483 private:
 484   friend class RBD;
 485   friend class Image;
 486
 487   rbd_image_options_t opts;
 488 };
 489
 490 class CEPH_RBD_API PoolStats {
 491 public:
 492   PoolStats();
 493   ~PoolStats();
 494
 495   PoolStats(const PoolStats&) = delete;
 496   PoolStats& operator=(const PoolStats&) = delete;
 497
 498   int add(rbd_pool_stat_option_t option, uint64_t* opt_val);
 499
 500 private:
 501   friend class RBD;
 502
 503   rbd_pool_stats_t pool_stats;
 504 };
 505
 506 class CEPH_RBD_API UpdateWatchCtx {
 507 public:
 508   virtual ~UpdateWatchCtx() {}
 509   /**
 510    * Callback activated when we receive a notify event.
 511    */
 512   virtual void handle_notify() = 0;
 513 };
 514
 515 class CEPH_RBD_API QuiesceWatchCtx {
 516 public:
 517   virtual ~QuiesceWatchCtx() {}
 518   /**
 519    * Callback activated when we want to quiesce.
 520    */
 521   virtual void handle_quiesce() = 0;
 522
 523   /**
 524    * Callback activated when we want to unquiesce.
 525    */
 526   virtual void handle_unquiesce() = 0;
 527 };
 528
 529 class CEPH_RBD_API Image
 530 {
 531 public:
 532   Image();
 533   ~Image();
 534
 535   int close();
 536   int aio_close(RBD::AioCompletion *c);
 537
 538   int resize(uint64_t size);
 539   int resize2(uint64_t size, bool allow_shrink, ProgressContext& pctx);
 540   int resize_with_progress(uint64_t size, ProgressContext& pctx);
 541   int stat(image_info_t &info, size_t infosize);
 542   int get_name(std::string *name);
 543   int get_id(std::string *id);
 544   std::string get_block_name_prefix();
 545   int64_t get_data_pool_id();
 546   int parent_info(std::string *parent_poolname, std::string *parent_name,
 547                   std::string *parent_snapname)
 548       CEPH_RBD_DEPRECATED;
 549   int parent_info2(std::string *parent_poolname, std::string *parent_name,
 550                    std::string *parent_id, std::string *parent_snapname)
 551       CEPH_RBD_DEPRECATED;
 552   int get_parent(linked_image_spec_t *parent_image, snap_spec_t *parent_snap);
 553
 554   int get_migration_source_spec(std::string* source_spec);
 555
 556   int old_format(uint8_t *old);
 557   int size(uint64_t *size);
 558   int get_group(group_info_t *group_info, size_t group_info_size);
 559   int features(uint64_t *features);
 560   int update_features(uint64_t features, bool enabled);
 561   int get_op_features(uint64_t *op_features);
 562   int overlap(uint64_t *overlap);
 563   int get_flags(uint64_t *flags);
 564   int set_image_notification(int fd, int type);
 565
 566   /* exclusive lock feature */
 567   int is_exclusive_lock_owner(bool *is_owner);
 568   int lock_acquire(rbd_lock_mode_t lock_mode);
 569   int lock_release();
 570   int lock_get_owners(rbd_lock_mode_t *lock_mode,
 571                       std::list<std::string> *lock_owners);
 572   int lock_break(rbd_lock_mode_t lock_mode, const std::string &lock_owner);
 573
 574   /* object map feature */
 575   int rebuild_object_map(ProgressContext &prog_ctx);
 576
 577   int check_object_map(ProgressContext &prog_ctx);
 578
 579   int copy(IoCtx& dest_io_ctx, const char *destname);
 580   int copy2(Image& dest);
 581   int copy3(IoCtx& dest_io_ctx, const char *destname, ImageOptions& opts);
 582   int copy4(IoCtx& dest_io_ctx, const char *destname, ImageOptions& opts,
 583             size_t sparse_size);
 584   int copy_with_progress(IoCtx& dest_io_ctx, const char *destname,
 585                          ProgressContext &prog_ctx);
 586   int copy_with_progress2(Image& dest, ProgressContext &prog_ctx);
 587   int copy_with_progress3(IoCtx& dest_io_ctx, const char *destname,
 588                           ImageOptions& opts, ProgressContext &prog_ctx);
 589   int copy_with_progress4(IoCtx& dest_io_ctx, const char *destname,
 590                           ImageOptions& opts, ProgressContext &prog_ctx,
 591                           size_t sparse_size);
 592
 593   /* deep copy */
 594   int deep_copy(IoCtx& dest_io_ctx, const char *destname, ImageOptions& opts);
 595   int deep_copy_with_progress(IoCtx& dest_io_ctx, const char *destname,
 596                               ImageOptions& opts, ProgressContext &prog_ctx);
 597
 598   /* encryption */
 599   int encryption_format(encryption_format_t format, encryption_options_t opts,
 600                         size_t opts_size);
 601   int encryption_load(encryption_format_t format, encryption_options_t opts,
 602                       size_t opts_size);
 603   int encryption_load2(const encryption_spec_t *specs, size_t spec_count);
 604
 605   /* striping */
 606   uint64_t get_stripe_unit() const;
 607   uint64_t get_stripe_count() const;
 608
 609   int get_create_timestamp(struct timespec *timestamp);
 610   int get_access_timestamp(struct timespec *timestamp);
 611   int get_modify_timestamp(struct timespec *timestamp);
 612
 613   int flatten();
 614   int flatten_with_progress(ProgressContext &prog_ctx);
 615
 616   int sparsify(size_t sparse_size);
 617   int sparsify_with_progress(size_t sparse_size, ProgressContext &prog_ctx);
 618   /**
 619    * Returns a pair of poolname, imagename for each clone
 620    * of this image at the currently set snapshot.
 621    */
 622   int list_children(std::set<std::pair<std::string, std::string> > *children)
 623       CEPH_RBD_DEPRECATED;
 624   /**
 625   * Returns a structure of poolname, imagename, imageid and trash flag
 626   * for each clone of this image at the currently set snapshot.
 627   */
 628   int list_children2(std::vector<librbd::child_info_t> *children)
 629       CEPH_RBD_DEPRECATED;
 630   int list_children3(std::vector<linked_image_spec_t> *images);
 631   int list_descendants(std::vector<linked_image_spec_t> *images);
 632
 633   /* advisory locking (see librbd.h for details) */
 634   int list_lockers(std::list<locker_t> *lockers,
 635                    bool *exclusive, std::string *tag);
 636   int lock_exclusive(const std::string& cookie);
 637   int lock_shared(const std::string& cookie, const std::string& tag);
 638   int unlock(const std::string& cookie);
 639   int break_lock(const std::string& client, const std::string& cookie);
 640
 641   /* snapshots */
 642   int snap_list(std::vector<snap_info_t>& snaps);
 643   /* DEPRECATED; use snap_exists2 */
 644   bool snap_exists(const char *snapname) CEPH_RBD_DEPRECATED;
 645   int snap_exists2(const char *snapname, bool *exists);
 646   int snap_create(const char *snapname);
 647   int snap_create2(const char *snapname, uint32_t flags, ProgressContext& pctx);
 648   int snap_remove(const char *snapname);
 649   int snap_remove2(const char *snapname, uint32_t flags, ProgressContext& pctx);
 650   int snap_remove_by_id(uint64_t snap_id);
 651   int snap_rollback(const char *snap_name);
 652   int snap_rollback_with_progress(const char *snap_name, ProgressContext& pctx);
 653   int snap_protect(const char *snap_name);
 654   int snap_unprotect(const char *snap_name);
 655   int snap_is_protected(const char *snap_name, bool *is_protected);
 656   int snap_set(const char *snap_name);
 657   int snap_set_by_id(uint64_t snap_id);
 658   int snap_get_name(uint64_t snap_id, std::string *snap_name);
 659   int snap_get_id(const std::string snap_name, uint64_t *snap_id);
 660   int snap_rename(const char *srcname, const char *dstname);
 661   int snap_get_limit(uint64_t *limit);
 662   int snap_set_limit(uint64_t limit);
 663   int snap_get_timestamp(uint64_t snap_id, struct timespec *timestamp);
 664   int snap_get_namespace_type(uint64_t snap_id,
 665                               snap_namespace_type_t *namespace_type);
 666   int snap_get_group_namespace(uint64_t snap_id,
 667                                snap_group_namespace_t *group_namespace,
 668                                size_t snap_group_namespace_size);
 669   int snap_get_trash_namespace(uint64_t snap_id, std::string* original_name);
 670   int snap_get_mirror_namespace(
 671       uint64_t snap_id, snap_mirror_namespace_t *mirror_namespace,
 672       size_t snap_mirror_namespace_size);
 673
 674   /* I/O */
 675   ssize_t read(uint64_t ofs, size_t len, ceph::bufferlist& bl);
 676   /* @param op_flags see librados.h constants beginning with LIBRADOS_OP_FLAG */
 677   ssize_t read2(uint64_t ofs, size_t len, ceph::bufferlist& bl, int op_flags);
 678   int64_t read_iterate(uint64_t ofs, size_t len,
 679                        int (*cb)(uint64_t, size_t, const char *, void *), void *arg);
 680   int read_iterate2(uint64_t ofs, uint64_t len,
 681                     int (*cb)(uint64_t, size_t, const char *, void *), void *arg);
 682   /**
 683    * get difference between two versions of an image
 684    *
 685    * This will return the differences between two versions of an image
 686    * via a callback, which gets the offset and length and a flag
 687    * indicating whether the extent exists (1), or is known/defined to
 688    * be zeros (a hole, 0).  If the source snapshot name is NULL, we
 689    * interpret that as the beginning of time and return all allocated
 690    * regions of the image.  The end version is whatever is currently
 691    * selected for the image handle (either a snapshot or the writeable
 692    * head).
 693    *
 694    * @param fromsnapname start snapshot name, or NULL
 695    * @param ofs start offset
 696    * @param len len in bytes of region to report on
 697    * @param include_parent true if full history diff should include parent
 698    * @param whole_object 1 if diff extents should cover whole object
 699    * @param cb callback to call for each allocated region
 700    * @param arg argument to pass to the callback
 701    * @returns 0 on success, or negative error code on error
 702    */
 703   int diff_iterate(const char *fromsnapname,
 704                    uint64_t ofs, uint64_t len,
 705                    int (*cb)(uint64_t, size_t, int, void *), void *arg);
 706   int diff_iterate2(const char *fromsnapname,
 707                     uint64_t ofs, uint64_t len,
 708                     bool include_parent, bool whole_object,
 709                     int (*cb)(uint64_t, size_t, int, void *), void *arg);
 710
 711   ssize_t write(uint64_t ofs, size_t len, ceph::bufferlist& bl);
 712   /* @param op_flags see librados.h constants beginning with LIBRADOS_OP_FLAG */
 713   ssize_t write2(uint64_t ofs, size_t len, ceph::bufferlist& bl, int op_flags);
 714
 715   int discard(uint64_t ofs, uint64_t len);
 716   ssize_t writesame(uint64_t ofs, size_t len, ceph::bufferlist &bl, int op_flags);
 717   ssize_t write_zeroes(uint64_t ofs, size_t len, int zero_flags, int op_flags);
 718
 719   /**
 720    * compare and write from/to image
 721    *
 722    * Compare data in compare bufferlist to data at offset in image.
 723    * len bytes of the compare bufferlist are compared, i.e. the compare
 724    * bufferlist has to be at least len bytes long.
 725    * If the compare is successful len bytes from the write bufferlist
 726    * are written to the image, i.e. the write bufferlist also has to be
 727    * at least len bytes long.
 728    * If the compare is unsuccessful no data is written and the
 729    * offset in the bufferlist where the compare first differed
 730    * is returned through mismatch_off.
 731    *
 732    * @param off offset in image
 733    * @param len length of compare, length of write
 734    * @param cmp_bl bufferlist to compare from
 735    * @param bl bufferlist to write to image if compare succeeds
 736    * @param c aio completion to notify when compare and write is complete
 737    * @param mismatch_off (out) offset in bufferlist where compare first differed
 738    * @param op_flags see librados.h constants beginning with LIBRADOS_OP_FLAG
 739    */
 740   ssize_t compare_and_write(uint64_t ofs, size_t len, ceph::bufferlist &cmp_bl,
 741                             ceph::bufferlist& bl, uint64_t *mismatch_off, int op_flags);
 742
 743   int aio_write(uint64_t off, size_t len, ceph::bufferlist& bl, RBD::AioCompletion *c);
 744   /* @param op_flags see librados.h constants beginning with LIBRADOS_OP_FLAG */
 745   int aio_write2(uint64_t off, size_t len, ceph::bufferlist& bl,
 746                   RBD::AioCompletion *c, int op_flags);
 747
 748   int aio_discard(uint64_t off, uint64_t len, RBD::AioCompletion *c);
 749   int aio_writesame(uint64_t off, size_t len, ceph::bufferlist& bl,
 750                     RBD::AioCompletion *c, int op_flags);
 751   int aio_write_zeroes(uint64_t ofs, size_t len, RBD::AioCompletion *c,
 752                        int zero_flags, int op_flags);
 753
 754   int aio_compare_and_write(uint64_t off, size_t len, ceph::bufferlist& cmp_bl,
 755                             ceph::bufferlist& bl, RBD::AioCompletion *c,
 756                             uint64_t *mismatch_off, int op_flags);
 757
 758   /**
 759    * read async from image
 760    *
 761    * The target bufferlist is populated with references to buffers
 762    * that contain the data for the given extent of the image.
 763    *
 764    * NOTE: If caching is enabled, the bufferlist will directly
 765    * reference buffers in the cache to avoid an unnecessary data copy.
 766    * As a result, if the user intends to modify the buffer contents
 767    * directly, they should make a copy first (unconditionally, or when
 768    * the reference count on ther underlying buffer is more than 1).
 769    *
 770    * @param off offset in image
 771    * @param len length of read
 772    * @param bl bufferlist to read into
 773    * @param c aio completion to notify when read is complete
 774    */
 775   int aio_read(uint64_t off, size_t len, ceph::bufferlist& bl, RBD::AioCompletion *c);
 776   /* @param op_flags see librados.h constants beginning with LIBRADOS_OP_FLAG */
 777   int aio_read2(uint64_t off, size_t len, ceph::bufferlist& bl,
 778                   RBD::AioCompletion *c, int op_flags);
 779
 780   int flush();
 781   /**
 782    * Start a flush if caching is enabled. Get a callback when
 783    * the currently pending writes are on disk.
 784    *
 785    * @param image the image to flush writes to
 786    * @param c what to call when flushing is complete
 787    * @returns 0 on success, negative error code on failure
 788    */
 789   int aio_flush(RBD::AioCompletion *c);
 790
 791   /**
 792    * Drop any cached data for this image
 793    *
 794    * @returns 0 on success, negative error code on failure
 795    */
 796   int invalidate_cache();
 797
 798   int poll_io_events(RBD::AioCompletion **comps, int numcomp);
 799
 800   int metadata_get(const std::string &key, std::string *value);
 801   int metadata_set(const std::string &key, const std::string &value);
 802   int metadata_remove(const std::string &key);
 803   /**
 804    * Returns a pair of key/value for this image
 805    */
 806   int metadata_list(const std::string &start, uint64_t max, std::map<std::string, ceph::bufferlist> *pairs);
 807
 808   // RBD image mirroring support functions
 809   int mirror_image_enable() CEPH_RBD_DEPRECATED;
 810   int mirror_image_enable2(mirror_image_mode_t mode);
 811   int mirror_image_disable(bool force);
 812   int mirror_image_promote(bool force);
 813   int mirror_image_demote();
 814   int mirror_image_resync();
 815   int mirror_image_create_snapshot(uint64_t *snap_id);
 816   int mirror_image_create_snapshot2(uint32_t flags, uint64_t *snap_id);
 817   int mirror_image_get_info(mirror_image_info_t *mirror_image_info,
 818                             size_t info_size);
 819   int mirror_image_get_mode(mirror_image_mode_t *mode);
 820   int mirror_image_get_global_status(
 821       mirror_image_global_status_t *mirror_image_global_status,
 822       size_t status_size);
 823   int mirror_image_get_status(
 824       mirror_image_status_t *mirror_image_status, size_t status_size)
 825     CEPH_RBD_DEPRECATED;
 826   int mirror_image_get_instance_id(std::string *instance_id);
 827   int aio_mirror_image_promote(bool force, RBD::AioCompletion *c);
 828   int aio_mirror_image_demote(RBD::AioCompletion *c);
 829   int aio_mirror_image_get_info(mirror_image_info_t *mirror_image_info,
 830                                 size_t info_size, RBD::AioCompletion *c);
 831   int aio_mirror_image_get_mode(mirror_image_mode_t *mode,
 832                                 RBD::AioCompletion *c);
 833   int aio_mirror_image_get_global_status(
 834       mirror_image_global_status_t *mirror_image_global_status,
 835       size_t status_size, RBD::AioCompletion *c);
 836   int aio_mirror_image_get_status(
 837       mirror_image_status_t *mirror_image_status, size_t status_size,
 838       RBD::AioCompletion *c)
 839     CEPH_RBD_DEPRECATED;
 840   int aio_mirror_image_create_snapshot(uint32_t flags, uint64_t *snap_id,
 841       RBD::AioCompletion *c);
 842
 843   int update_watch(UpdateWatchCtx *ctx, uint64_t *handle);
 844   int update_unwatch(uint64_t handle);
 845
 846   int list_watchers(std::list<image_watcher_t> &watchers);
 847
 848   int config_list(std::vector<config_option_t> *options);
 849
 850   int quiesce_watch(QuiesceWatchCtx *ctx, uint64_t *handle);
 851   int quiesce_unwatch(uint64_t handle);
 852   void quiesce_complete(uint64_t handle, int r);
 853
 854 private:
 855   friend class RBD;
 856
 857   Image(const Image& rhs);
 858   const Image& operator=(const Image& rhs);
 859
 860   image_ctx_t ctx;
 861 };
 862
 863 } // namespace librbd
 864
 865 #if __GNUC__ >= 4
 866   #pragma GCC diagnostic pop
 867 #endif
 868
 869 #endif // __LIBRBD_HPP