src/include/eina_xattr.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2011 Cedric Bail
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library;
  16  * if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef EINA_XATTR_H_
  20 #define EINA_XATTR_H_
  21
  22 #include "eina_types.h"
  23
  24 /**
  25  * @addtogroup Eina_Tools_Group Tools
  26  *
  27  * @{
  28  */
  29
  30 /**
  31  * @typedef Eina_Xattr_Flags
  32  * define extended attribute creation
  33  *
  34  * @since 1.1
  35  */
  36 typedef enum {
  37   EINA_XATTR_INSERT, /**< This is the default behaviour, it will either create or replace the extended attribute */
  38   EINA_XATTR_REPLACE, /**< This will only succeed if the extended attribute previously existed */
  39   EINA_XATTR_CREATED /**< This will only succeed if the extended attribute wasn't previously set */
  40 } Eina_Xattr_Flags;
  41
  42 typedef struct _Eina_Xattr Eina_Xattr;
  43 struct _Eina_Xattr
  44 {
  45    const char *name; /**< The eXtended attribute name @since 1.2 */
  46    const char *value; /**< The eXtended attribute value @since 1.2 */
  47
  48    size_t length; /**< The length of the eXtended attribute value @since 1.2 */
  49 };
  50
  51 /**
  52  * @brief Get an iterator that list all extended attribute of a file.
  53  *
  54  * @param file The filename to retrieve the extended attribute list from.
  55  * @return an iterator.
  56  *
  57  * The iterator will not allocate any data during the iteration step, so you need to copy them yourself
  58  * if you need.
  59  *
  60  * @since 1.1
  61  */
  62 EAPI Eina_Iterator *eina_xattr_ls(const char *file);
  63
  64 /**
  65  * @brief Get an iterator that list all extended attribute value related to a fd.
  66  *
  67  * @param file The filename to retrieve the extended attribute list from.
  68  * @return an iterator.
  69  *
  70  * The iterator will not allocate any data during the iteration step, so you need to copy them yourself
  71  * if you need. The iterator will provide an Eina_Xattr structure.
  72  *
  73  * @since 1.2
  74  */
  75 EAPI Eina_Iterator *eina_xattr_value_ls(const char *file);
  76
  77 /**
  78  * @brief Get an iterator that list all extended attribute related to a fd.
  79  *
  80  * @param fd The file descriptor to retrieve the extended attribute list from.
  81  * @return an iterator.
  82  *
  83  * The iterator will not allocate any data during the iteration step, so you need to copy them yourself
  84  * if you need.
  85  *
  86  * @since 1.2
  87  */
  88 EAPI Eina_Iterator *eina_xattr_fd_ls(int fd);
  89
  90 /**
  91  * @brief Get an iterator that list all extended attribute value related to a fd.
  92  *
  93  * @param fd The file descriptor to retrieve the extended attribute list from.
  94  * @return an iterator.
  95  *
  96  * The iterator will not allocate any data during the iteration step, so you need to copy them yourself
  97  * if you need. The iterator will provide an Eina_Xattr structure.
  98  *
  99  * @since 1.2
 100  */
 101 EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd);
 102
 103 /**
 104  * @brief Retrieve an extended attribute from a file.
 105  *
 106  * @param file The file to retrieve the extended attribute from.
 107  * @param attribute The extended attribute name to retrieve.
 108  * @param size The size of the retrieved extended attribute.
 109  * @return the allocated data that hold the extended attribute value.
 110  *
 111  * It will return @c NULL and *size will be @c 0 if it fails.
 112  *
 113  * @since 1.1
 114  */
 115 EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size);
 116
 117 /**
 118  * @brief Set an extended attribute on a file.
 119  *
 120  * @param file The file to set the extended attribute to.
 121  * @param attribute The attribute to set.
 122  * @param data The data to set.
 123  * @param length The length of the data to set.
 124  * @param flags Define the set policy.
 125  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 126  *
 127  * @since 1.1
 128  */
 129 EAPI Eina_Bool eina_xattr_set(const char *file, const char *attribute, const void *data, ssize_t length, Eina_Xattr_Flags flags);
 130
 131 /**
 132  * @brief Set a string as a extended attribute properties.
 133  *
 134  * @param file The file to set the string to.
 135  * @param attribute The attribute to set.
 136  * @param data The NULL-terminated string to set.
 137  * @param flags Define the set policy.
 138  * @return EINA_TRUE on success, EINA_FALSE otherwise.
 139  *
 140  * @since 1.1
 141  */
 142 EAPI Eina_Bool eina_xattr_string_set(const char *file, const char *attribute, const char *data, Eina_Xattr_Flags flags);
 143
 144 /**
 145  * @brief Get a string from an extended attribute properties.
 146  *
 147  * @param file The file to get the string from.
 148  * @param attribute The attribute to get.
 149  * @return A valid string on success, @c NULL otherwise.
 150  *
 151  * This call check that the string is properly NULL-terminated before returning it.
 152  *
 153  * @since 1.1
 154  */
 155 EAPI char *eina_xattr_string_get(const char *file, const char *attribute);
 156
 157 /**
 158  * @brief Set a double as a extended attribute properties.
 159  *
 160  * @param file The file to set the double to.
 161  * @param attribute The attribute to set.
 162  * @param value The NULL-terminated double to set.
 163  * @param flags Define the set policy.
 164  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 165  *
 166  * @since 1.1
 167  */
 168 EAPI Eina_Bool eina_xattr_double_set(const char *file, const char *attribute, double value, Eina_Xattr_Flags flags);
 169
 170 /**
 171  * @brief Get a double from an extended attribute properties.
 172  *
 173  * @param file The file to get the string from.
 174  * @param attribute The attribute to get.
 175  * @param value Where to put the extracted value
 176  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 177  *
 178  * This call check that the double is correctly set.
 179  *
 180  * @since 1.1
 181  */
 182 EAPI Eina_Bool eina_xattr_double_get(const char *file, const char *attribute, double *value);
 183
 184 /**
 185  * @brief Set an int as a extended attribute properties.
 186  *
 187  * @param file The file to set the int to.
 188  * @param attribute The attribute to set.
 189  * @param value The NULL-terminated int to set.
 190  * @param flags Define the set policy.
 191  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 192  *
 193  * @since 1.1
 194  */
 195 EAPI Eina_Bool eina_xattr_int_set(const char *file, const char *attribute, int value, Eina_Xattr_Flags flags);
 196
 197 /**
 198  * @brief Get a int from an extended attribute properties.
 199  *
 200  * @param file The file to get the string from.
 201  * @param attribute The attribute to get.
 202  * @param value Where to put the extracted value
 203  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 204  *
 205  * This call check that the int is correctly set.
 206  *
 207  * @since 1.1
 208  */
 209 EAPI Eina_Bool eina_xattr_int_get(const char *file, const char *attribute, int *value);
 210
 211 /**
 212  * @}
 213  */
 214
 215 #endif