libgnomevfs/gnome-vfs-file-info.h

   1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */
   2 /* gnome-vfs-file-info.h - Handling of file information for the GNOME
   3    Virtual File System.
   4
   5    Copyright (C) 1999,2001 Free Software Foundation
   6    Copyright (C) 2002 Seth Nickell
   7
   8    The Gnome Library is free software; you can redistribute it and/or
   9    modify it under the terms of the GNU Library General Public License as
  10    published by the Free Software Foundation; either version 2 of the
  11    License, or (at your option) any later version.
  12
  13    The Gnome Library is distributed in the hope that it will be useful,
  14    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16    Library General Public License for more details.
  17
  18    You should have received a copy of the GNU Library General Public
  19    License along with the Gnome Library; see the file COPYING.LIB.  If not,
  20    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21    Boston, MA 02111-1307, USA.
  22
  23    Author: Ettore Perazzoli <ettore@comm2000.it>
  24            Seth Nickell <snickell@stanford.edu>
  25 */
  26
  27 #ifndef GNOME_VFS_FILE_INFO_H
  28 #define GNOME_VFS_FILE_INFO_H
  29
  30 #include <libgnomevfs/gnome-vfs-file-size.h>
  31 #include <libgnomevfs/gnome-vfs-result.h>
  32 #include <libgnomevfs/gnome-vfs-uri.h>
  33 #include <sys/stat.h>
  34 #include <sys/types.h>
  35
  36 G_BEGIN_DECLS
  37
  38 /**
  39  * GnomeVFSInodeNumber:
  40  *
  41  * Represents the i-node of a file, this is a low level data structure
  42  * that the operating system uses to hold information about a file.
  43  **/
  44
  45 typedef GnomeVFSFileSize GnomeVFSInodeNumber;
  46
  47 /**
  48  * GnomeVFSFileFlags:
  49  * @GNOME_VFS_FILE_FLAGS_NONE: no flags
  50  * @GNOME_VFS_FILE_FLAGS_SYMLINK: whether the file is a symlink.
  51  * @GNOME_VFS_FILE_FLAGS_LOCAL: whether the file is on a local filesystem
  52  *
  53  * Packed boolean bitfield representing special
  54  * flags a #GnomeVFSFileInfo struct can have.
  55  **/
  56 typedef enum {
  57         GNOME_VFS_FILE_FLAGS_NONE = 0,
  58         GNOME_VFS_FILE_FLAGS_SYMLINK = 1 << 0,
  59         GNOME_VFS_FILE_FLAGS_LOCAL = 1 << 1
  60 } GnomeVFSFileFlags;
  61
  62 /**
  63  * GnomeVFSFileType:
  64  * @GNOME_VFS_FILE_TYPE_UNKNOWN:
  65  * @GNOME_VFS_FILE_TYPE_REGULAR:
  66  * @GNOME_VFS_FILE_TYPE_DIRECTORY:
  67  * @GNOME_VFS_FILE_TYPE_FIFO:
  68  * @GNOME_VFS_FILE_TYPE_SOCKET:
  69  * @GNOME_VFS_FILE_TYPE_CHARACTER_DEVICE:
  70  * @GNOME_VFS_FILE_TYPE_BLOCK_DEVICE:
  71  * @GNOME_VFS_FILE_TYPE_SYMBOLIC_LINK:
  72  *
  73  * Identifies the kind of file represented by a #GnomeVFSFileInfo struct. (note,
  74  * use of MIME types is preferred as this field may eventually disappear)
  75  **/
  76
  77 typedef enum {
  78         GNOME_VFS_FILE_TYPE_UNKNOWN,
  79         GNOME_VFS_FILE_TYPE_REGULAR,
  80         GNOME_VFS_FILE_TYPE_DIRECTORY,
  81         GNOME_VFS_FILE_TYPE_FIFO,
  82         GNOME_VFS_FILE_TYPE_SOCKET,
  83         GNOME_VFS_FILE_TYPE_CHARACTER_DEVICE,
  84         GNOME_VFS_FILE_TYPE_BLOCK_DEVICE,
  85         GNOME_VFS_FILE_TYPE_SYMBOLIC_LINK
  86 } GnomeVFSFileType;
  87
  88 /**
  89  * GnomeVFSFileInfoFields:
  90  * @GNOME_VFS_FILE_INFO_FIELDS_NONE: No fields are valid
  91  * @GNOME_VFS_FILE_INFO_FIELDS_TYPE: Type field is valid
  92  * @GNOME_VFS_FILE_INFO_FIELDS_PERMISSIONS: Permissions field is valid
  93  * @GNOME_VFS_FILE_INFO_FIELDS_FLAGS: Flags field is valid
  94  * @GNOME_VFS_FILE_INFO_FIELDS_DEVICE: Device field is valid
  95  * @GNOME_VFS_FILE_INFO_FIELDS_INODE: Inode field is valid
  96  * @GNOME_VFS_FILE_INFO_FIELDS_LINK_COUNT: Link count field is valid
  97  * @GNOME_VFS_FILE_INFO_FIELDS_SIZE: Size field is valid
  98  * @GNOME_VFS_FILE_INFO_FIELDS_BLOCK_COUNT: Block count field is valid
  99  * @GNOME_VFS_FILE_INFO_FIELDS_IO_BLOCK_SIZE: I/O Block Size field is valid
 100  * @GNOME_VFS_FILE_INFO_FIELDS_ATIME: Access time field is valid
 101  * @GNOME_VFS_FILE_INFO_FIELDS_MTIME: Modification time field is valid
 102  * @GNOME_VFS_FILE_INFO_FIELDS_CTIME: Creating time field is valid
 103  * @GNOME_VFS_FILE_INFO_FIELDS_SYMLINK_NAME: Symlink name field is valid
 104  * @GNOME_VFS_FILE_INFO_FIELDS_MIME_TYPE: Mime type field is valid
 105  * @GNOME_VFS_FILE_INFO_FIELDS_ACCESS: Access bits of the permissions
 106  * bitfield are valid
 107  *
 108  * Flags indicating what fields in a GnomeVFSFileInfo struct are valid.
 109  * Name is always assumed valid (how else would you have gotten a
 110  * FileInfo struct otherwise?)
 111  **/
 112
 113 typedef enum {
 114         GNOME_VFS_FILE_INFO_FIELDS_NONE = 0,
 115         GNOME_VFS_FILE_INFO_FIELDS_TYPE = 1 << 0,
 116         GNOME_VFS_FILE_INFO_FIELDS_PERMISSIONS = 1 << 1,
 117         GNOME_VFS_FILE_INFO_FIELDS_FLAGS = 1 << 2,
 118         GNOME_VFS_FILE_INFO_FIELDS_DEVICE = 1 << 3,
 119         GNOME_VFS_FILE_INFO_FIELDS_INODE = 1 << 4,
 120         GNOME_VFS_FILE_INFO_FIELDS_LINK_COUNT = 1 << 5,
 121         GNOME_VFS_FILE_INFO_FIELDS_SIZE = 1 << 6,
 122         GNOME_VFS_FILE_INFO_FIELDS_BLOCK_COUNT = 1 << 7,
 123         GNOME_VFS_FILE_INFO_FIELDS_IO_BLOCK_SIZE = 1 << 8,
 124         GNOME_VFS_FILE_INFO_FIELDS_ATIME = 1 << 9,
 125         GNOME_VFS_FILE_INFO_FIELDS_MTIME = 1 << 10,
 126         GNOME_VFS_FILE_INFO_FIELDS_CTIME = 1 << 11,
 127         GNOME_VFS_FILE_INFO_FIELDS_SYMLINK_NAME = 1 << 12,
 128         GNOME_VFS_FILE_INFO_FIELDS_MIME_TYPE = 1 << 13,
 129         GNOME_VFS_FILE_INFO_FIELDS_ACCESS = 1 << 14
 130 } GnomeVFSFileInfoFields;
 131
 132 /* FIXME: It's silly to use the symbolic constants for POSIX here.
 133  * This is supposed to be a virtual file system, so it makes no
 134  * sense to use the values of the POSIX-required constants on the
 135  * particular machine this code is compiled on. These should all be changed
 136  * to use numeric constants like GNOME_VFS_PERM_STICKY does now. However,
 137  * be careful in making such a change, since some existing code might
 138  * wrongly assume these equivalencies.
 139  */
 140
 141 /**
 142  * GnomeVFSFilePermissions:
 143  * @GNOME_VFS_PERM_SUID: UID bit
 144  * @GNOME_VFS_PERM_SGID: GID bit
 145  * @GNOME_VFS_PERM_STICKY: Sticky bit.
 146  * @GNOME_VFS_PERM_USER_READ: Owner has read permission
 147  * @GNOME_VFS_PERM_USER_WRITE: Owner has write permission
 148  * @GNOME_VFS_PERM_USER_EXEC: Owner has execution permission
 149  * @GNOME_VFS_PERM_USER_ALL: Owner has all permissions
 150  * @GNOME_VFS_PERM_GROUP_READ: Group has read permission
 151  * @GNOME_VFS_PERM_GROUP_WRITE: Group has write permission
 152  * @GNOME_VFS_PERM_GROUP_EXEC: Group has execution permission
 153  * @GNOME_VFS_PERM_GROUP_ALL: Group has all permissions
 154  * @GNOME_VFS_PERM_OTHER_READ: Others have read permission
 155  * @GNOME_VFS_PERM_OTHER_WRITE: Others have write permission
 156  * @GNOME_VFS_PERM_OTHER_EXEC: Others have execution permission
 157  * @GNOME_VFS_PERM_OTHER_ALL: Others have all permissions
 158  * @GNOME_VFS_PERM_ACCESS_READABLE:
 159  * @GNOME_VFS_PERM_ACCESS_WRITABLE:
 160  * @GNOME_VFS_PERM_ACCESS_EXECUTABLE:
 161  *
 162  * File permissions. These are the same as the Unix ones, but we wrap them
 163  * into a nicer VFS-like enum.
 164  **/
 165 typedef enum {
 166         GNOME_VFS_PERM_SUID = S_ISUID,
 167         GNOME_VFS_PERM_SGID = S_ISGID,
 168         GNOME_VFS_PERM_STICKY = 01000,  /* S_ISVTX not defined on all systems */
 169         GNOME_VFS_PERM_USER_READ = S_IRUSR,
 170         GNOME_VFS_PERM_USER_WRITE = S_IWUSR,
 171         GNOME_VFS_PERM_USER_EXEC = S_IXUSR,
 172         GNOME_VFS_PERM_USER_ALL = S_IRUSR | S_IWUSR | S_IXUSR,
 173         GNOME_VFS_PERM_GROUP_READ = S_IRGRP,
 174         GNOME_VFS_PERM_GROUP_WRITE = S_IWGRP,
 175         GNOME_VFS_PERM_GROUP_EXEC = S_IXGRP,
 176         GNOME_VFS_PERM_GROUP_ALL = S_IRGRP | S_IWGRP | S_IXGRP,
 177         GNOME_VFS_PERM_OTHER_READ = S_IROTH,
 178         GNOME_VFS_PERM_OTHER_WRITE = S_IWOTH,
 179         GNOME_VFS_PERM_OTHER_EXEC = S_IXOTH,
 180         GNOME_VFS_PERM_OTHER_ALL = S_IROTH | S_IWOTH | S_IXOTH,
 181         GNOME_VFS_PERM_ACCESS_READABLE   = 1 << 16,
 182         GNOME_VFS_PERM_ACCESS_WRITABLE   = 1 << 17,
 183         GNOME_VFS_PERM_ACCESS_EXECUTABLE = 1 << 18
 184 } GnomeVFSFilePermissions;
 185
 186
 187 /**
 188  * GnomeVFSFileInfo:
 189  *
 190  * The GnomeVFSFileInfo structure contains information about a file.
 191  **/
 192 typedef struct {
 193         /* Base name of the file (no path).  */
 194         char *name;
 195
 196         /* Fields which are actually valid in this structure. */
 197         GnomeVFSFileInfoFields valid_fields;
 198
 199         /* File type (i.e. regular, directory, block device...).  */
 200         GnomeVFSFileType type;
 201
 202         /* File permissions.  */
 203         GnomeVFSFilePermissions permissions;
 204
 205         /* Flags for this file.  */
 206         GnomeVFSFileFlags flags;
 207
 208         /* These are only valid if `is_local' is TRUE (see below).  */
 209         dev_t device;
 210         GnomeVFSInodeNumber inode;
 211
 212         /* Link count.  */
 213         guint link_count;
 214
 215         /* UID, GID.  */
 216         guint uid;
 217         guint gid;
 218
 219         /* Size in bytes.  */
 220         GnomeVFSFileSize size;
 221
 222         /* Size measured in units of 512-byte blocks.  */
 223         GnomeVFSFileSize block_count;
 224
 225         /* Optimal buffer size for reading/writing the file.  */
 226         guint io_block_size;
 227
 228         /* Access, modification and change times.  */
 229         time_t atime;
 230         time_t mtime;
 231         time_t ctime;
 232
 233         /* If the file is a symlink (see `flags'), this specifies the file the
 234            link points to.  */
 235         char *symlink_name;
 236
 237         /* MIME type.  */
 238         char *mime_type;
 239
 240         guint refcount;
 241
 242         /* Reserved for future expansions to GnomeVFSFileInfo without having
 243            to break ABI compatibility */
 244         void *reserved1;
 245         void *reserved2;
 246         void *reserved3;
 247         void *reserved4;
 248         void *reserved5;
 249 } GnomeVFSFileInfo;
 250
 251 /**
 252  * GnomeVFSFileInfoOptions:
 253  * @GNOME_VFS_FILE_INFO_DEFAULT: default flags
 254  * @GNOME_VFS_FILE_INFO_GET_MIME_TYPE: detect the MIME type
 255  * @GNOME_VFS_FILE_INFO_FORCE_FAST_MIME_TYPE: only use fast MIME type
 256  * detection (extensions)
 257  * @GNOME_VFS_FILE_INFO_FORCE_SLOW_MIME_TYPE: force slow MIME type
 258  * detection where available (sniffing, algorithmic detection, etc)
 259  * @GNOME_VFS_FILE_INFO_FOLLOW_LINKS: automatically follow symbolic
 260  * links and retrieve the properties of their target (recommended)
 261  * @GNOME_VFS_FILE_INFO_GET_ACCESS_RIGHTS: tries to get data similar
 262  * to what would return access(2) on a local file system (ie is the
 263  * file readable, writable and/or executable). Can be really slow on
 264  * remote file systems
 265  *
 266  * Packed boolean bitfield representing options that can
 267  * be passed into a gnome_vfs_get_file_info() call (or other
 268  * related calls that return file info) and affect the operation
 269  * of get_file_info.
 270  **/
 271
 272 typedef enum {
 273         GNOME_VFS_FILE_INFO_DEFAULT = 0,
 274         GNOME_VFS_FILE_INFO_GET_MIME_TYPE = 1 << 0,
 275         GNOME_VFS_FILE_INFO_FORCE_FAST_MIME_TYPE = 1 << 1,
 276         GNOME_VFS_FILE_INFO_FORCE_SLOW_MIME_TYPE = 1 << 2,
 277         GNOME_VFS_FILE_INFO_FOLLOW_LINKS = 1 << 3,
 278         GNOME_VFS_FILE_INFO_GET_ACCESS_RIGHTS = 1 << 4
 279 } GnomeVFSFileInfoOptions;
 280
 281 /**
 282  * GnomeVFSSetFileInfoMask:
 283  * @GNOME_VFS_SET_FILE_INFO_NONE: don't set any file info fields
 284  * @GNOME_VFS_SET_FILE_INFO_NAME: change the name
 285  * @GNOME_VFS_SET_FILE_INFO_PERMISSIONS: change the permissions
 286  * @GNOME_VFS_SET_FILE_INFO_OWNER: change the file's owner
 287  * @GNOME_VFS_SET_FILE_INFO_TIME: change the file's time stamp(s)
 288  *
 289  * Packed boolean bitfield representing the aspects of the file
 290  * to be changed in a gnome_vfs_set_file_info() call.
 291  **/
 292
 293 typedef enum {
 294         GNOME_VFS_SET_FILE_INFO_NONE = 0,
 295         GNOME_VFS_SET_FILE_INFO_NAME = 1 << 0,
 296         GNOME_VFS_SET_FILE_INFO_PERMISSIONS = 1 << 1,
 297         GNOME_VFS_SET_FILE_INFO_OWNER = 1 << 2,
 298         GNOME_VFS_SET_FILE_INFO_TIME = 1 << 3
 299 } GnomeVFSSetFileInfoMask;
 300
 301 typedef struct {
 302         GnomeVFSURI *uri;
 303         GnomeVFSResult result;
 304         GnomeVFSFileInfo *file_info;
 305 } GnomeVFSGetFileInfoResult;
 306
 307 /**
 308  * GNOME_VFS_FILE_INFO_SYMLINK:
 309  * @info: GnomeVFSFileInfo struct
 310  *
 311  * Determines whether a file is a symbolic link given @info.
 312  */
 313 #define GNOME_VFS_FILE_INFO_SYMLINK(info)               \
 314         ((info)->flags & GNOME_VFS_FILE_FLAGS_SYMLINK)
 315
 316 /**
 317  * GNOME_VFS_FILE_INFO_SET_SYMLINK:
 318  * @info: GnomeVFSFileInfo struct
 319  * @value: if %TRUE, @info is set to indicate the file is a symbolic link
 320  *
 321  * Set the symbolic link field in @info to @value.
 322  */
 323 #define GNOME_VFS_FILE_INFO_SET_SYMLINK(info, value)                    \
 324         (value ? ((info)->flags |= GNOME_VFS_FILE_FLAGS_SYMLINK)        \
 325                : ((info)->flags &= ~GNOME_VFS_FILE_FLAGS_SYMLINK))
 326
 327 /**
 328  * GNOME_VFS_FILE_INFO_LOCAL:
 329  * @info: GnomeVFSFileInfo struct
 330  *
 331  * Determines whether a file is local given @info.
 332  */
 333 #define GNOME_VFS_FILE_INFO_LOCAL(info)                 \
 334         ((info)->flags & GNOME_VFS_FILE_FLAGS_LOCAL)
 335
 336 /**
 337  * GNOME_VFS_FILE_INFO_SET_LOCAL:
 338  * @info: GnomeVFSFileInfo struct
 339  * @value: if %TRUE, @info is set to indicate the file is local
 340  *
 341  * Set the "local file" field in @info to @value.
 342  */
 343 #define GNOME_VFS_FILE_INFO_SET_LOCAL(info, value)                      \
 344         (value ? ((info)->flags |= GNOME_VFS_FILE_FLAGS_LOCAL)          \
 345                : ((info)->flags &= ~GNOME_VFS_FILE_FLAGS_LOCAL))
 346
 347
 348 /**
 349  * GNOME_VFS_FILE_INFO_SUID:
 350  * @info: GnomeVFSFileInfo struct
 351  *
 352  * Determines whether a file belongs to the super user.
 353  */
 354 #define GNOME_VFS_FILE_INFO_SUID(info)                  \
 355         ((info)->permissions & GNOME_VFS_PERM_SUID)
 356
 357 /**
 358  * GNOME_VFS_FILE_INFO_SGID:
 359  * @info: GnomeVFSFileInfo struct
 360  *
 361  * Determines whether a file belongs to the super user's group.
 362  */
 363 #define GNOME_VFS_FILE_INFO_SGID(info)                  \
 364         ((info)->permissions & GNOME_VFS_PERM_SGID)
 365
 366 /**
 367  * GNOME_VFS_FILE_INFO_STICKY:
 368  * @info: GnomeVFSFileInfo struct
 369  *
 370  * Determines whether a file has the sticky bit set, given @info
 371  */
 372 #define GNOME_VFS_FILE_INFO_STICKY(info)                \
 373         ((info)->permissions & GNOME_VFS_PERM_STICKY)
 374
 375 /**
 376  * GNOME_VFS_FILE_INFO_SET_SUID:
 377  * @info: GnomeVFSFileInfo struct
 378  * @value: if %TRUE, @info is set to indicate the file belongs to the super user
 379  *
 380  * Set the SUID field in @info to @value.
 381  */
 382 #define GNOME_VFS_FILE_INFO_SET_SUID(info, value)               \
 383         (value ? ((info)->permissions |= GNOME_VFS_PERM_SUID)   \
 384                : ((info)->permissions &= ~GNOME_VFS_PERM_SUID))
 385
 386 /**
 387  * GNOME_VFS_FILE_INFO_SET_SGID:
 388  * @info: GnomeVFSFileInfo struct
 389  * @value: if %TRUE, @info is set to indicate the file belongs to the super user's group
 390  *
 391  * Set the SGID field in @info to @value.
 392  */
 393 #define GNOME_VFS_FILE_INFO_SET_SGID(info, value)               \
 394         (value ? ((info)->permissions |= GNOME_VFS_PERM_SGID)   \
 395                : ((info)->permissions &= ~GNOME_VFS_PERM_SGID))
 396 /**
 397  * GNOME_VFS_FILE_INFO_SET_STICKY:
 398  * @info: GnomeVFSFileInfo struct
 399  * @value: if %TRUE, @info is set to indicate the file has the sticky bit set
 400  *
 401  * Set the sticky bit in @info to @value.
 402  */
 403 #define GNOME_VFS_FILE_INFO_SET_STICKY(info, value)                     \
 404         (value ? ((info)->permissions |= GNOME_VFS_PERM_STICKY)         \
 405                : ((info)->permissions &= ~GNOME_VFS_PERM_STICKY))
 406
 407 \f
 408
 409 GnomeVFSFileInfo *gnome_vfs_file_info_new           (void);
 410 void              gnome_vfs_file_info_unref         (GnomeVFSFileInfo       *info);
 411 void              gnome_vfs_file_info_ref           (GnomeVFSFileInfo       *info);
 412 void              gnome_vfs_file_info_clear         (GnomeVFSFileInfo       *info);
 413 const char *      gnome_vfs_file_info_get_mime_type (GnomeVFSFileInfo       *info);
 414 void              gnome_vfs_file_info_copy          (GnomeVFSFileInfo       *dest,
 415                                                      const GnomeVFSFileInfo *src);
 416 GnomeVFSFileInfo *gnome_vfs_file_info_dup           (const GnomeVFSFileInfo *orig);
 417 gboolean          gnome_vfs_file_info_matches       (const GnomeVFSFileInfo *a,
 418                                                      const GnomeVFSFileInfo *b);
 419 GList *           gnome_vfs_file_info_list_ref      (GList                  *list);
 420 GList *           gnome_vfs_file_info_list_unref    (GList                  *list);
 421 GList *           gnome_vfs_file_info_list_copy     (GList                  *list);
 422 void              gnome_vfs_file_info_list_free     (GList                  *list);
 423
 424 G_END_DECLS
 425
 426 #endif /* GNOME_VFS_FILE_INFO_H */