src/lib/Eeze_Disk.h

   1 #ifndef EEZE_DISK_H
   2 #define EEZE_DISK_H
   3
   4 #ifdef EAPI
   5 # undef EAPI
   6 #endif
   7
   8 #ifdef __GNUC__
   9 # if __GNUC__ >= 4
  10 #  define EAPI __attribute__ ((visibility("default")))
  11 # else
  12 #  define EAPI
  13 # endif
  14 #else
  15 # define EAPI
  16 #endif
  17
  18 #include <Eina.h>
  19 #include <Ecore.h>
  20
  21 /**
  22  * @file Eeze_Disk.h
  23  * @brief Disk manipulation
  24  * @since 1.1
  25  *
  26  * Eeze disk functions allow you to quickly and efficiently manipulate disks
  27  * through simple function calls.
  28  *
  29  * @addtogroup disk Disk
  30  * @{
  31  */
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38  * @enum Eeze_Disk_Type
  39  * @since 1.1
  40  *
  41  * All disk types known to Eeze.
  42  */
  43 typedef enum
  44 {
  45    EEZE_DISK_TYPE_UNKNOWN = 0, /**< type could not be determined */
  46    EEZE_DISK_TYPE_INTERNAL = (1 << 0), /**< internal drive */
  47    EEZE_DISK_TYPE_CDROM = (1 << 1), /**< cdrom drive */
  48    EEZE_DISK_TYPE_USB = (1 << 2), /**< usb drive */
  49    EEZE_DISK_TYPE_FLASH = (1 << 3) /**< flash disk */
  50 } Eeze_Disk_Type;
  51
  52 /**
  53  * @enum Eeze_Mount_Opts
  54  * @since 1.1
  55  *
  56  * All mount options known to Eeze.
  57  */
  58 typedef enum
  59 {
  60 #define EEZE_DISK_MOUNTOPT_DEFAULTS (EEZE_DISK_MOUNTOPT_UTF8 | EEZE_DISK_MOUNTOPT_NOEXEC | EEZE_DISK_MOUNTOPT_NOSUID)
  61    EEZE_DISK_MOUNTOPT_LOOP = (1 << 1),
  62    EEZE_DISK_MOUNTOPT_UTF8 = (1 << 2),
  63    EEZE_DISK_MOUNTOPT_NOEXEC = (1 << 3),
  64    EEZE_DISK_MOUNTOPT_NOSUID = (1 << 4),
  65    EEZE_DISK_MOUNTOPT_REMOUNT = (1 << 5),
  66    EEZE_DISK_MOUNTOPT_UID = (1 << 6), /**< use current user's uid */
  67    EEZE_DISK_MOUNTOPT_NODEV = (1 << 7) /**< @since 1.7 */
  68 } Eeze_Mount_Opts;
  69
  70
  71 EAPI extern int EEZE_EVENT_DISK_MOUNT;
  72 EAPI extern int EEZE_EVENT_DISK_UNMOUNT;
  73 EAPI extern int EEZE_EVENT_DISK_EJECT;
  74 EAPI extern int EEZE_EVENT_DISK_ERROR;
  75
  76 typedef struct _Eeze_Event_Disk Eeze_Event_Disk_Mount;
  77 typedef struct _Eeze_Event_Disk Eeze_Event_Disk_Unmount;
  78 typedef struct _Eeze_Event_Disk Eeze_Event_Disk_Eject;
  79
  80 /**
  81  * @typedef Eeze_Disk
  82  * @since 1.1
  83  *
  84  * Handle for an Eeze Disk.
  85  */
  86 typedef struct _Eeze_Disk Eeze_Disk;
  87
  88 struct _Eeze_Event_Disk
  89 {
  90    Eeze_Disk *disk;
  91 };
  92
  93 /**
  94  * @typedef Eeze_Event_Disk_Error
  95  * @since 1.1
  96  *
  97  * Contains the human readable error message.
  98  */
  99 typedef struct _Eeze_Event_Disk_Error Eeze_Event_Disk_Error;
 100
 101 struct _Eeze_Event_Disk_Error
 102 {
 103    Eeze_Disk *disk;
 104    const char *message;
 105 };
 106
 107 /**
 108  * @brief Use this function to determine whether your eeze is disk-capable
 109  *
 110  * Since applications will die if they run/compile against a function that doesn't exist,
 111  * if your application successfully runs/compiles with this function then you have eeze_disk.
 112  * @since 1.1
 113  */
 114 EAPI void           eeze_disk_function(void);
 115
 116 /**
 117  * @brief Return whether mount support is available in eeze
 118  *
 119  * Use this function to determine whether your Eeze library was compiled with a mount
 120  * binary available.
 121  * @since 1.1
 122  */
 123 EAPI Eina_Bool      eeze_disk_can_mount(void);
 124
 125 /**
 126  * @brief Return whether unmount support is available in eeze
 127  *
 128  * Use this function to determine whether your Eeze library was compiled with an unmount
 129  * binary available.
 130  * @since 1.1
 131  */
 132 EAPI Eina_Bool      eeze_disk_can_unmount(void);
 133
 134 /**
 135  * @brief Return whether eject support is available in eeze
 136  *
 137  * Use this function to determine whether your Eeze library was compiled with an eject
 138  * binary available.
 139  * @since 1.1
 140  */
 141 EAPI Eina_Bool      eeze_disk_can_eject(void);
 142
 143 /**
 144  * @brief Create a new disk object from a /sys/ path or /dev/ path
 145  * @param path The /sys/ or /dev path of the disk; CANNOT be @c NULL.
 146  * @return The new disk object
 147  *
 148  * This function creates a new #Eeze_Disk from @p path.  Note that this function
 149  * does the minimal amount of work in order to save memory, and udev info about the disk
 150  * is not retrieved in this call.
 151  * @since 1.1
 152  */
 153 EAPI Eeze_Disk     *eeze_disk_new(const char *path);
 154
 155 /**
 156  * @brief Create a new disk object from a mount point
 157  * @param mount_point The mount point of the disk; CANNOT be @c NULL
 158  * @return The new disk object
 159  *
 160  * This function creates a new #Eeze_Disk from @p mount_point.  Note that this function
 161  * does the minimal amount of work in order to save memory, and udev info about the disk
 162  * is not retrieved in this call.  If the disk is not currently mounted, it must have an entry
 163  * in /etc/fstab.
 164  * @since 1.1
 165  */
 166 EAPI Eeze_Disk     *eeze_disk_new_from_mount(const char *mount_point);
 167
 168 /**
 169  * @brief Frees a disk object
 170  * @param disk The disk object to free
 171  *
 172  * This call frees an #Eeze_Disk.  Once freed, the disk can no longer be used.
 173  * @since 1.1
 174  */
 175 EAPI void           eeze_disk_free(Eeze_Disk *disk);
 176
 177 /**
 178  * @brief Retrieve all disk information
 179  * @param disk
 180  *
 181  * Use this function to retrieve all of a disk's information at once, then use
 182  * a "get" function to retrieve the value.  Data retrieved in this call is cached,
 183  * meaning that subsequent calls will return immediately without performing any work.
 184  * @since 1.1
 185  */
 186 EAPI void           eeze_disk_scan(Eeze_Disk *disk);
 187
 188 /**
 189  * @brief Associate data with a disk
 190  * @param disk The disk
 191  * @param data The data
 192  *
 193  * Data can be associated with @p disk with this function.
 194  * @see eeze_disk_data_get
 195  * @since 1.1
 196  */
 197 EAPI void           eeze_disk_data_set(Eeze_Disk *disk, void *data);
 198
 199 /**
 200  * @brief Retrieve data previously associated with a disk
 201  * @param disk The disk
 202  * @return The data
 203  *
 204  * Data that has been previously associated with @p disk
 205  * is returned with this function.
 206  * @see eeze_disk_data_set
 207  * @since 1.1
 208  */
 209 EAPI void          *eeze_disk_data_get(Eeze_Disk *disk);
 210
 211 /**
 212  * @brief Return the /sys/ path of a disk
 213  * @param disk The disk
 214  * @return The /sys/ path
 215  *
 216  * This retrieves the /sys/ path that udev associates with @p disk.
 217  * @since 1.1
 218  */
 219 EAPI const char    *eeze_disk_syspath_get(Eeze_Disk *disk);
 220
 221 /**
 222  * @brief Return the /dev/ path of a disk
 223  * @param disk The disk
 224  * @return The /dev/ path
 225  *
 226  * This retrieves the /dev/ path that udev has created a device node at for @p disk.
 227  * @since 1.1
 228  */
 229 EAPI const char    *eeze_disk_devpath_get(Eeze_Disk *disk);
 230
 231 /**
 232  * @brief Return the filesystem of the disk (if known)
 233  * @param disk The disk
 234  * @return The filesystem type
 235  *
 236  * This retrieves the filesystem that the disk is using, or @c NULL if unknown.
 237  * @since 1.1
 238  */
 239 EAPI const char    *eeze_disk_fstype_get(Eeze_Disk *disk);
 240
 241 /**
 242  * @brief Return the manufacturing vendor of the disk
 243  * @param disk The disk
 244  * @return The vendor
 245  *
 246  * This retrieves the vendor which manufactured the disk, or @c NULL if unknown.
 247  * @since 1.1
 248  */
 249 EAPI const char    *eeze_disk_vendor_get(Eeze_Disk *disk);
 250
 251 /**
 252  * @brief Return the model of the disk
 253  * @param disk The disk
 254  * @return The model
 255  *
 256  * This retrieves the model of the disk, or @c NULL if unknown.
 257  * @since 1.1
 258  */
 259 EAPI const char    *eeze_disk_model_get(Eeze_Disk *disk);
 260
 261 /**
 262  * @brief Return the serial number of the disk
 263  * @param disk The disk
 264  * @return The serial number
 265  *
 266  * This retrieves the serial number the disk, or @c NULL if unknown.
 267  * @since 1.1
 268  */
 269 EAPI const char    *eeze_disk_serial_get(Eeze_Disk *disk);
 270
 271 /**
 272  * @brief Return the UUID of the disk
 273  * @param disk The disk
 274  * @return The UUID
 275  *
 276  * This retrieves the UUID of the disk, or @c NULL if unknown.
 277  * A UUID is a 36 character (hopefully) unique identifier which can
 278  * be used to store persistent information about a disk.
 279  * @since 1.1
 280  */
 281 EAPI const char    *eeze_disk_uuid_get(Eeze_Disk *disk);
 282
 283 /**
 284  * @brief Return the label of the disk
 285  * @param disk The disk
 286  * @return The label
 287  *
 288  * This retrieves the label (name) of the disk, or @c NULL if unknown.
 289  * @since 1.1
 290  */
 291 EAPI const char    *eeze_disk_label_get(Eeze_Disk *disk);
 292
 293 /**
 294  * @brief Return the #Eeze_Disk_Type of the disk
 295  * @param disk The disk
 296  * @return The type
 297  *
 298  * This retrieves the #Eeze_Disk_Type of the disk.  This call is useful for determining
 299  * the bus that the disk is connected through.
 300  * @since 1.1
 301  */
 302 EAPI Eeze_Disk_Type eeze_disk_type_get(Eeze_Disk *disk);
 303
 304 /**
 305  * @brief Return whether the disk is removable
 306  * @param disk The disk
 307  * @return @c EINA_TRUE if removable, @c EINA_FALSE otherwise.
 308  * @since 1.1
 309  */
 310 EAPI Eina_Bool      eeze_disk_removable_get(Eeze_Disk *disk);
 311
 312
 313 /**
 314  * @brief Return the mount state of a disk
 315  * @param disk The disk
 316  * @return The mount state
 317  *
 318  * This returns the mounted state of the disk.  @c EINA_TRUE if mounted,
 319  * @c EINA_FALSE otherwise.
 320  * @since 1.1
 321  */
 322 EAPI Eina_Bool      eeze_disk_mounted_get(Eeze_Disk *disk);
 323
 324 /**
 325  * @brief Get the previously set mount wrapper for a disk
 326  * @param disk The disk
 327  * @return The wrapper, or @c NULL on failure.
 328  *
 329  * This returns the wrapper previously set with eeze_disk_mount_wrapper_set
 330  * @since 1.1
 331  */
 332 EAPI const char    *eeze_disk_mount_wrapper_get(Eeze_Disk *disk);
 333
 334 /**
 335  * @brief Set a wrapper to run mount commands with
 336  * @param disk The disk to wrap mount commands for
 337  * @param wrapper The wrapper executable
 338  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 339  *
 340  * Use this function to set up a wrapper for running mount/umount commands. The wrapper must
 341  * NOT use any of the standard mount/umount error code return values, and it must return 0 on success.
 342  * Note that this function will call stat() on @p wrapper if not @c NULL to test for existence.
 343  * @since 1.1
 344  */
 345 EAPI Eina_Bool      eeze_disk_mount_wrapper_set(Eeze_Disk *disk, const char *wrapper);
 346
 347 /**
 348  * @brief Begin a mount operation on the disk
 349  * @param disk The disk
 350  * @return @c EINA_TRUE if the operation was started, @c EINA_FALSE otherwise.
 351  *
 352  * This call is used to begin a mount operation on @p disk.  The operation will
 353  * run asynchronously in a pipe, emitting an EEZE_EVENT_DISK_MOUNT event with the disk object
 354  * as its event on completion.  If any errors are encountered, they will automatically logged
 355  * to the eeze_disk domain and an EEZE_EVENT_DISK_ERROR event will be generated with an #Eeze_Event_Disk_Error
 356  * struct as its event.
 357  *
 358  * NOTE: The return value of this function does not in any way reflect the mount state of a disk.
 359  * @since 1.1
 360  */
 361 EAPI Eina_Bool      eeze_disk_mount(Eeze_Disk *disk);
 362
 363 /**
 364  * @brief Begin an unmount operation on the disk
 365  * @param disk The disk
 366  * @return @c EINA_TRUE if the operation was started, @c EINA_FALSE otherwise.
 367  *
 368  * This call is used to begin an unmount operation on @p disk.  The operation will
 369  * run asynchronously in a pipe, emitting an EEZE_EVENT_DISK_UNMOUNT event with the disk object
 370  * as its event on completion.  If any errors are encountered, they will automatically logged
 371  * to the eeze_disk domain and an EEZE_EVENT_DISK_ERROR event will be generated with
 372  * an #Eeze_Event_Disk_Error struct as its event.
 373  *
 374  * NOTE: The return value of this function does not in any way reflect the mount state of a disk.
 375  * @since 1.1
 376  */
 377 EAPI Eina_Bool      eeze_disk_unmount(Eeze_Disk *disk);
 378
 379 /**
 380  * @brief Begin an eject operation on the disk
 381  * @param disk The disk
 382  * @return @c EINA_TRUE if the operation was started, @c EINA_FALSE otherwise.
 383  *
 384  * This call is used to begin an eject operation on @p disk.  The operation will
 385  * run asynchronously in a pipe, emitting an EEZE_EVENT_DISK_EJECT event with the disk object
 386  * as its event on completion.  If any errors are encountered, they will automatically logged
 387  * to the eeze_disk domain and an EEZE_EVENT_DISK_ERROR event will be generated with
 388  * an #Eeze_Event_Disk_Error struct as its event.
 389  *
 390  * NOTE: The return value of this function does not in any way reflect the mount state of a disk.
 391  * @since 1.1
 392  */
 393 EAPI Eina_Bool      eeze_disk_eject(Eeze_Disk *disk);
 394 /**
 395  * @brief Cancel a pending operation on the disk
 396  * @param disk The disk
 397  *
 398  * This function cancels the current pending operation on @p disk which was previously
 399  * started with eeze_disk_mount or eeze_disk_unmount.
 400  * @since 1.1
 401  */
 402 EAPI void           eeze_disk_cancel(Eeze_Disk *disk);
 403
 404 /**
 405  * @brief Return the mount point of a disk
 406  * @param disk The disk
 407  * @return The mount point
 408  *
 409  * This function returns the mount point associated with @p disk.
 410  * Note that to determine whether the disk is actually mounted, eeze_disk_mounted_get should be used.
 411  * @since 1.1
 412  */
 413 EAPI const char    *eeze_disk_mount_point_get(Eeze_Disk *disk);
 414
 415 /**
 416  * @brief Set the mount point of a disk
 417  * @param disk The disk
 418  * @param mount_point The mount point
 419  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 420  *
 421  * This function sets the mount point associated with @p disk.
 422  * Note that to determine whether the disk is actually mounted, eeze_disk_mounted_get should be used.
 423  * Also note that this function cannot be used while the disk is mounted to avoid losing the current mount point.
 424  * @since 1.1
 425  */
 426 EAPI Eina_Bool      eeze_disk_mount_point_set(Eeze_Disk *disk, const char *mount_point);
 427
 428 /**
 429  * @brief Set the mount options using flags
 430  * @param disk The disk
 431  * @param opts An ORed set of #Eeze_Mount_Opts
 432  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise.
 433  *
 434  * This function replaces the current mount opts of a disk with the ones in @p opts.
 435  * @since 1.1
 436  */
 437 EAPI Eina_Bool      eeze_disk_mountopts_set(Eeze_Disk *disk, unsigned long opts);
 438
 439 /**
 440  * @brief Get the flags of a disk's current mount options
 441  * @param disk The disk
 442  * @return An ORed set of #Eeze_Mount_Opts, 0 on failure
 443  *
 444  * This function returns the current mount opts of a disk.
 445  * @since 1.1
 446  */
 447 EAPI unsigned long  eeze_disk_mountopts_get(Eeze_Disk *disk);
 448
 449
 450 /**
 451  * @brief Begin watching mtab and fstab
 452  * @return @c EINA_TRUE if watching was started, @c EINA_FALSE otherwise.
 453  *
 454  * This function creates inotify watches on /etc/mtab and /etc/fstab and watches
 455  * them for changes.  This function should be used when expecting a lot of disk
 456  * mounting/unmounting while you need disk data since it will automatically update
 457  * certain necessary data instead of waiting.
 458  * @see eeze_mount_mtab_scan, eeze_mount_fstab_scan
 459  * @since 1.1
 460  */
 461 EAPI Eina_Bool      eeze_mount_tabs_watch(void);
 462
 463 /**
 464  * @brief Stop watching /etc/fstab and /etc/mtab
 465  *
 466  * This function stops watching fstab and mtab.  Data obtained previously will be saved.
 467  * @since 1.1
 468  */
 469 EAPI void           eeze_mount_tabs_unwatch(void);
 470
 471 /**
 472  * @brief Scan /etc/mtab a single time
 473  * @return @c EINA_TRUE if mtab could be scanned, @c EINA_FALSE otherwise.
 474  *
 475  * This function is used to perform a single scan on /etc/mtab.  It is used to gather
 476  * information about mounted filesystems which can then be used with your #Eeze_Disk objects
 477  * where appropriate.  These files will automatically be scanned any time a mount point or mount state
 478  * is requested unless eeze_mount_tabs_watch has been called previously, in which case data is stored for
 479  * use.
 480  * If this function is called after eeze_mount_tabs_watch, @c EINA_TRUE will be returned.
 481  * @see eeze_mount_tabs_watch, eeze_mount_fstab_scan
 482  * @since 1.1
 483  */
 484 EAPI Eina_Bool      eeze_mount_mtab_scan(void);
 485
 486 /**
 487  * @brief Scan /etc/fstab a single time
 488  * @return @c EINA_TRUE if mtab could be scanned, @c EINA_FALSE otherwise.
 489  *
 490  * This function is used to perform a single scan on /etc/fstab.  It is used to gather
 491  * information about mounted filesystems which can then be used with your #Eeze_Disk objects
 492  * where appropriate.  These files will automatically be scanned any time a mount point or mount state
 493  * is requested unless eeze_mount_tabs_watch has been called previously, in which case data is stored for
 494  * use.
 495  * If this function is called after eeze_mount_tabs_watch, @c EINA_TRUE will be returned.
 496  * @see eeze_mount_tabs_watch, eeze_mount_mtab_scan
 497  * @since 1.1
 498  */
 499 EAPI Eina_Bool      eeze_mount_fstab_scan(void);
 500
 501 /**
 502  * @brief Get the property value of a disk
 503  *
 504  * @param disk The disk
 505  * @param property The property to get; full list of these is a FIXME
 506  * @return A stringshared char* with the property or @c NULL on failure.
 507  * @since 1.1
 508  */
 509
 510 EAPI const char    *eeze_disk_udev_get_property(Eeze_Disk *disk, const char *property);
 511
 512 /**
 513  * @brief Get the sysattr value of a disk.
 514  *
 515  * @param disk The disk
 516  * @param sysattr The sysattr to get; full list of these is a FIXME
 517  * @return A stringshared char* with the sysattr or @c NULL on failure.
 518  * @since 1.1
 519  */
 520
 521 EAPI const char    *eeze_disk_udev_get_sysattr(Eeze_Disk *disk, const char *sysattr);
 522
 523 /**
 524  * Find the root device of a disk.
 525  *
 526  * @param disk The disk
 527  * @return The syspath of the parent device
 528  *
 529  * Return a stringshared syspath (/sys/$syspath) for the parent device.
 530  * @since 1.1
 531  */
 532 EAPI const char    *eeze_disk_udev_get_parent(Eeze_Disk *disk);
 533
 534 /**
 535  * Walks up the device chain using the device from @p disk,
 536  * checking each device for @p sysattr with (optional) @p value.
 537  *
 538  * @param disk The disk to walk
 539  * @param sysattr The attribute to find
 540  * @param value OPTIONAL: The value that @p sysattr should have, or @c NULL.
 541  *
 542  * @return If the sysattr (with value) is found, returns @c EINA_TRUE,
 543  * @c EINA_FALSE otherwise.
 544  * @since 1.1
 545  */
 546 EAPI Eina_Bool      eeze_disk_udev_walk_check_sysattr(Eeze_Disk *disk, const char *sysattr, const char *value);
 547
 548 /**
 549  * @brief Walks up the device chain of @p disk
 550  * checking each device for @p sysattr and returns the value if found.
 551  *
 552  * @param disk The disk
 553  * @param sysattr The attribute to find
 554  *
 555  * @return The stringshared value of @p sysattr if found, or @c NULL.
 556  * @since 1.1
 557  */
 558 EAPI const char    *eeze_disk_udev_walk_get_sysattr(Eeze_Disk *disk, const char *sysattr);
 559
 560 #ifdef __cplusplus
 561 }
 562 #endif
 563
 564 /**
 565  * @}
 566  */
 567 #endif