inode.h

Go to the documentation of this file.
00001 /** @file   include/dmlite/c/inode.h
00002  *  @brief  C wrapper for DMLite INode API.
00003  *  @author Alejandro Álvarez Ayllon <aalvarez@cern.ch>
00004  *  @note   This is a low-level API, so security checks will NOT be done.
00005  */
00006 #ifndef DMLITE_INODE_H
00007 #define DMLITE_INODE_H
00008 
00009 #include <stdint.h>
00010 #include "any.h"
00011 #include "dmlite.h"
00012 #include "utils.h"
00013 
00014 #ifdef  __cplusplus
00015 extern "C" {
00016 #endif
00017 
00018 /** Possible replica statuses */
00019 enum dmlite_replica_status { kAvailable      = '-',
00020                              kBeingPopulated = 'P',
00021                              kToBeDeleted    = 'D'
00022                            };
00023 /** Possible replica types */
00024 enum dmlite_replica_type   { kVolatile  = 'V',
00025                              kPermanent = 'P'
00026                            };
00027 
00028 /** A replica of a file */
00029 typedef struct dmlite_replica {
00030   int64_t    replicaid;
00031   int64_t    fileid;
00032 
00033   int64_t    nbaccesses;
00034   time_t     atime;
00035   time_t     ptime;
00036   time_t     ltime;
00037 
00038   enum dmlite_replica_status status;
00039   enum dmlite_replica_type   type;
00040 
00041   char server[HOST_NAME_MAX];
00042   char rfn   [URL_MAX];
00043   
00044   dmlite_any_dict* extra; /**< @brief   If != NULL, additional metadata will be
00045                            *            put here.
00046                            *   @details Caller is generally responsible for
00047                            *            allocating and freeing. Exception:
00048                            *            when an array is allocated by the called
00049                            *            method */
00050 } dmlite_replica;
00051 
00052 /** Posible file statuses */
00053 enum dmlite_file_status { kOnline = '-',
00054                           kMigrated = 'm'
00055                         };
00056                         
00057 /** File metadata */
00058 typedef struct dmlite_xstat {
00059   ino_t                   parent;
00060   struct stat             stat;
00061   enum dmlite_file_status status;
00062   char                    name     [NAME_MAX];
00063   char                    guid     [GUID_MAX];
00064   char                    csumtype [CSUMTYPE_MAX];
00065   char                    csumvalue[CSUMVALUE_MAX];
00066   char                    acl      [ACL_ENTRIES_MAX * ACL_SIZE];
00067   
00068   dmlite_any_dict* extra; /**< @brief   If != NULL, additional metadata will be
00069                            *            put here.
00070                            *   @details Caller is responsible for allocating
00071                            *            and freeing*/
00072 } dmlite_xstat;
00073 
00074 /** Opaque directory handler */
00075 typedef struct dmlite_idir dmlite_idir;
00076 
00077 /** 
00078  * @brief         Starts a transaction.
00079  * @details       Depending on the plugin stack, it can be possible to nest
00080  *                several calls.
00081  * @param context The DM context.
00082  * @return        0 on success, error code otherwise.
00083  */
00084 int dmlite_ibegin(dmlite_context* context);
00085 
00086 /**
00087  * @brief         Commits the changes.
00088  * @details       Depending on the plugin stack, it can be possible to nest
00089  *                several calls, and there must be one icommit per ibegin
00090  *                for the changes to be permanent.
00091  * @param context The DM context.
00092  * @return        0 on success, error code otherwise.
00093  */
00094 int dmlite_icommit(dmlite_context* context);
00095 
00096 /**
00097  * @brief         Undo the changes.
00098  * @details       If several ibegin were nested, all the transactions will
00099  *                be probable be undone, regardless on the nesting level.
00100  * @param context The DM context.
00101  * @return        0 on success, error code otherwise.
00102  */
00103 int dmlite_irollback(dmlite_context* context);
00104 
00105 /**
00106  * @brief         Creates a new file.
00107  * @param context The DM context.
00108  * @param f       Only some fields from this struct will be used. That would depend
00109  *                on the plugin, but usually it will be: parent, name, mode, uid, gid,
00110  *                size, status, checksum and ACL.
00111  * @return        0 on success, error code otherwise.
00112  * @note          mode will probably be used raw (i.e. no cleanup or set of format bits)
00113  */
00114 int dmlite_icreate(dmlite_context* context, const dmlite_xstat* f);
00115 
00116 /**
00117  * @brief         Associates a symlink with an existing file.
00118  * @param context The DM context.
00119  * @param inode   The file that will be a symlink.
00120  * @param link    The destination link.
00121  * @return        0 on success, error code otherwise.
00122  */
00123 int dmlite_isymlink(dmlite_context* context, ino_t inode, const char* link);
00124 
00125 /**
00126  * @brief         Removes a file or directory from the database.
00127  * @param context The DM context.
00128  * @param inode   The id of the entry to remove.
00129  * @return        0 on success, error code otherwise.
00130  * @note          Not empty directories, or files will replicas may fail.
00131  */
00132 int dmlite_iunlink(dmlite_context* context, ino_t inode);
00133 
00134 /**
00135  * @brief         Moves a file to a different parent directory.
00136  * @param context The DM context.
00137  * @param inode   The file id.
00138  * @param dest    The destination id.
00139  * @return        0 on success, error code otherwise.
00140  */
00141 int dmlite_imove(dmlite_context* context, ino_t inode, ino_t dest);
00142 
00143 /**
00144  * @brief         Changes the name of an entry.
00145  * @param context The DM context.
00146  * @param inode   The file id.
00147  * @param name    The new name.
00148  * @return        0 on success, error code otherwise.
00149  */
00150 int dmlite_irename(dmlite_context* context, ino_t inode, const char* name);
00151 
00152 /**
00153  * @brief         Does a stat of an entry using the inode instead of the path.
00154  * @param context The DM context.
00155  * @param inode   The entry inode.
00156  * @param buf     Where to put the retrieved information.
00157  * @return        0 on success, error code otherwise.
00158  * @note          Security checks won't be done if you use this function,
00159  *                so keep in mind doing it yourself.
00160  */
00161 int dmlite_istat(dmlite_context* context, ino_t inode, struct stat* buf);
00162 
00163 /**
00164  * @brief         Does an extended stat of an entry using the inode instead of
00165  *                the path.
00166  * @param context The DM context.
00167  * @param inode   The entry inode.
00168  * @param buf     Where to put the retrieved information.
00169  * @return        0 on success, error code otherwise.
00170  * @note          Security checks won't be done if you use this function,
00171  *                so keep in mind doing it yourself.
00172  */
00173 int dmlite_istatx(dmlite_context* context, ino_t inode, dmlite_xstat* buf);
00174 
00175 /**
00176  * @brief         Does an extended stat using the parent inode and the entry name.
00177  * @param context The DM context.
00178  * @param parent  The parent id.
00179  * @param name    The entry name.
00180  * @param buf     Where to put the retrieved information.
00181  * @return        0 on success, error code otherwise.
00182  */
00183 int dmlite_istatx_by_name(dmlite_context* context, ino_t parent, const char* name,
00184                           dmlite_xstat* buf);
00185 
00186 /**
00187  * @brief         Reads a symbolic link.
00188  * @param context The DM context.
00189  * @param inode   The file id.
00190  * @param path    The link will be put here.
00191  * @param bufsize The size of the memory area pointed by path.
00192  * @return        0 on success, error code otherwise.
00193  */
00194 int dmlite_ireadlink(dmlite_context* context, ino_t inode,
00195                      char* path, size_t bufsize);
00196 
00197 /**
00198  * @brief         Adds a new replica.
00199  * @param context The DM context.
00200  * @param replica The replica to add. replica->fileid must point to a valid file.
00201  * @return        0 on success, error code otherwise.
00202  */
00203 int dmlite_iaddreplica(dmlite_context* context, const dmlite_replica* replica);
00204 
00205 /**
00206  * @brief         Deletes a replica.
00207  * @param context The DM context.
00208  * @param replica The replica to remove.
00209  * @return        0 on success, error code otherwise.
00210  */
00211 int dmlite_ideletereplica(dmlite_context* context, const dmlite_replica* replica);
00212 
00213 /**
00214  * @brief         Gets a specific replica using its replica id.
00215  * @param context The DM context.
00216  * @param rid     The replica id.
00217  * @param buf     Where to put the retrieved data.
00218  * @return        0 on success, error code otherwise.
00219  */
00220 int dmlite_igetreplica(dmlite_context* context, int64_t rid, dmlite_replica* buf);
00221 
00222 /**
00223  * @brief           Gets all the replicas associated to a file.
00224  * @param context   The DM context.
00225  * @param inode     The file id.
00226  * @param nreplicas The number of replicas will be put here.
00227  * @param replicas  It will be initialized to an array of nreplicas replicas.
00228  *                  Free it with <b>dmlite_replicas_free</b>.
00229  * @return          0 on success, error code otherwise.
00230  */
00231 int dmlite_igetreplicas(dmlite_context* context, ino_t inode,
00232                         unsigned* nreplicas, dmlite_replica** replicas);
00233 
00234 /**
00235  * @brief         Sets the access and modification time.
00236  * @param context The DM context.
00237  * @param inode   The file id.
00238  * @param buf     The timestamps.
00239  * @return        0 on success, error code otherwise.
00240  */
00241 int dmlite_iutime(dmlite_context* context, ino_t inode,
00242                   const struct utimbuf* buf);
00243 
00244 /**
00245  * @brief          Sets the mode and ACL of a file.
00246  * @param context  The DM context.
00247  * @param inode    The file id.
00248  * @param uid      The new UID.
00249  * @param gid      The new GID.
00250  * @param mode     The new mode.
00251  * @param nentries The number of acl entries.
00252  * @param acl      The new ACL.
00253  * @return         0 on success, error code otherwise.
00254  * @note           This call may not validate that uid, gid, mode and acl
00255  *                 are coherent.
00256  */
00257 int dmlite_isetmode(dmlite_context* context, ino_t inode, uid_t uid, gid_t gid,
00258                     mode_t mode, unsigned nentries, dmlite_aclentry* acl);
00259 
00260 /**
00261  * @brief         Sets the size of a file.
00262  * @param context The DM context.
00263  * @param inode   The file id.
00264  * @param size    The new size.
00265  * @return        0 on success, error code otherwise.
00266  */
00267 int dmlite_isetsize(dmlite_context* context, ino_t inode, size_t size);
00268 
00269 /**
00270  * @brief           Sets the checksum of a file.
00271  * @param context   The DM context.
00272  * @param inode     The file id.
00273  * @param csumtype  The new checksum type.
00274  * @param csumvalue The new checksum value.
00275  * @return          0 on success, error code otherwise.
00276  */
00277 int dmlite_isetchecksum(dmlite_context* context, ino_t inode,
00278                         const char* csumtype, const char* csumvalue);
00279 
00280 /**
00281  * @brief         Gets the comment associated with an entry.
00282  * @param context The DM context.
00283  * @param inode   The file id.
00284  * @param comment Where to put the comment.
00285  * @param bufsize The size of the memory pointed by comment.
00286  * @return        0 on success, error code otherwise.
00287  */
00288 int dmlite_igetcomment(dmlite_context* context, ino_t inode,
00289                        char* comment, size_t bufsize);
00290 
00291 /**
00292  * @brief         Sets the comment associated with an entry.
00293  * @param context The DM context.
00294  * @param inode   The file id.
00295  * @param comment The new comment.
00296  * @return        0 on success, error code otherwise.
00297  */
00298 int dmlite_isetcomment(dmlite_context* context,  ino_t inode,
00299                        const char* comment);
00300 
00301 /**
00302  * @brief         Deletes the comment associated with an entry.
00303  * @param context The DM context.
00304  * @param inode   The file id.
00305  * @return        0 on success, error code otherwise.
00306  */
00307 int dmlite_ideletecomment(dmlite_context* context, ino_t inode);
00308 
00309 /**
00310  * @brief         Sets the file Grid Unique Identifier.
00311  * @param context The DM context.
00312  * @param inode   The entry id.
00313  * @param guid    The new GUID.
00314  * @return        0 on success, error code otherwise.
00315  */
00316 int dmlite_isetguid(dmlite_context* context, ino_t inode, const char* guid);
00317 
00318 /**
00319  * @brief         Updates the file extended attributes.
00320  * @param context The DM context.
00321  * @param inode   The entry id.
00322  * @param xattr   The new set of extended attributes.
00323  * @return        0 on success, error code otherwise.
00324  */
00325 int dmlite_iupdate_xattr(dmlite_context* context, ino_t inode,
00326                          const dmlite_any_dict* xattr);
00327 
00328 /**
00329  * @brief         Opens a directory.
00330  * @param context The DM context.
00331  * @param inode   The directory ID.
00332  * @return        NULL on failure. A pointer to an internal struct to be used
00333  *                with dmlite_ireaddir*
00334  */
00335 dmlite_idir* dmlite_iopendir(dmlite_context* context, ino_t inode);
00336 
00337 /**
00338  * @brief         Closes a directory, freeing any internally allocated memory.
00339  * @param context The DM context.
00340  * @param dir     The directory to close, as returned by dmlite_opendir.
00341  * @return        0 on success, error code otherwise.
00342  */
00343 int dmlite_iclosedir(dmlite_context* context, dmlite_idir* dir);
00344 
00345 /**
00346  * @brief         Reads a directory. Extended data.
00347  * @param context The DM context.
00348  * @param dir     The directory to read, as returned by dmlite_opendir.
00349  * @return        NULL on failure, or end of dir.
00350  */
00351 dmlite_xstat* dmlite_ireaddirx(dmlite_context* context, dmlite_idir* dir);
00352 
00353 /**
00354  * @brief         Reads a directory.
00355  * @param context The DM context.
00356  * @param dir     The directory to read, as returned by dmlite_opendir.
00357  * @return        NULL on failure, or end of dir.
00358  */
00359 struct dirent* dmlite_ireaddir(dmlite_context* context, dmlite_idir* dir);
00360 
00361 #ifdef  __cplusplus
00362 }
00363 #endif
00364 
00365 #endif /* DMLITE_INODE_H */

Generated on 3 Mar 2013 for dmlite by  doxygen 1.4.7