docs/user/storage/Mime.dox

   1 /*
   2  * Copyright 2013-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Ingo Weinhold, bonefish@users.sf.net
   7  *              John Scipione, jscipione@gmail.com
   8  *
   9  * Corresponds to:
  10  *              headers/os/storage/Mime.h        hrev47402
  11  *              src/kits/storage/Mime.cpp        hrev47402
  12  */
  13
  14
  15 /*!
  16         \file Mime.h
  17         \ingroup storage
  18         \ingroup libbe
  19         \brief Provides C and Haiku-only C++ MIME-type handling functions.
  20 */
  21
  22
  23 /*!
  24         \enum icon_size
  25         \ingroup storage
  26         \brief Legacy BeOS icon size constants.
  27
  28         \since BeOS R3
  29 */
  30
  31
  32 /*!
  33         \var icon_size B_LARGE_ICON
  34
  35         32x32 "Large" icon.
  36
  37         \since BeOS R3
  38 */
  39
  40
  41 /*!
  42         \var icon_size B_MINI_ICON
  43
  44         16x16 "Mini" icon.
  45
  46         \since BeOS R3
  47 */
  48
  49
  50 /*!
  51         \var B_UPDATE_MIME_INFO_NO_FORCE
  52         \brief Files that already have a \c BEOS:TYPE attribute won't be updated.
  53
  54         \since Haiku R1
  55 */
  56
  57
  58 /*!
  59         \var B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE
  60         \brief Files that already have a \c BEOS:TYPE attribute will be updated
  61                too, but \c BEOS:TYPE itself will remain untouched.
  62
  63         \since Haiku R1
  64 */
  65
  66
  67 /*!
  68         \var B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL
  69         \brief Similar to \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE, but the
  70                \c BEOS:TYPE attribute will be updated too.
  71
  72         \since Haiku R1
  73 */
  74
  75
  76 /*!
  77         \fn int update_mime_info(const char* path, int recursive, int synchronous,
  78                 int force)
  79         \brief Updates the MIME information (i.e MIME type) for one or more files.
  80
  81         If \a path points to a file, the MIME information for this file are
  82         updated only. If it points to a directory and \a recursive is non-null,
  83         the information for all the files in the given directory tree are updated.
  84         If path is \c NULL all files are considered; \a recursive is ignored in
  85         this case.
  86
  87         \param path The path to a file or directory, or \c NULL.
  88         \param recursive Triggers recursive behavior if not \c NULL.
  89         \param synchronous If not \c NULL update_mime_info() waits until the
  90                operation is finished, otherwise it returns immediately and the
  91                update is done asynchronously.
  92         \param force Specifies how to handle files that already have MIME
  93                information. See enum definitions for more information:
  94                - \c B_UPDATE_MIME_INFO_NO_FORCE
  95                - \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE
  96                - \c B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL
  97
  98         \return A status code, \c B_OK if everything went fine, an error code
  99                 otherwise.
 100
 101         \since BeOS R3
 102 */
 103
 104
 105 /*!
 106         \fn status_t create_app_meta_mime(const char* path, int recursive,
 107                 int synchronous, int force)
 108         \brief Creates a MIME database entry for one or more applications.
 109
 110         If \a path points to an application file, a MIME DB entry is create for
 111         the application. If it points to a directory and \a recursive is not
 112         \c NULL then entries are created for all application files in the given
 113         directory tree. If path is \c NULL then all files are considered and
 114         \a recursive is ignored.
 115
 116         \param path The path to an application file, a directory, or \c NULL.
 117         \param recursive Trigger recursive behavior if not \c NULL.
 118         \param synchronous Waits until the operation is finished if not \c NULL,
 119                otherwise it returns immediately and the operation is done
 120                asynchronously.
 121         \param force Entries are created even if they do already exist if not
 122                \c NULL.
 123
 124         \return A status code, \c B_OK if everything went fine, an error code
 125                 otherwise.
 126
 127         \since BeOS R3
 128 */
 129
 130
 131 /*!
 132         \fn status_t get_device_icon(const char* device, void* icon, int32 size)
 133         \brief Retrieves an icon associated with a given device.
 134
 135         \param device The path to the device.
 136         \param icon A pointer to a buffer the icon data shall be written to.
 137         \param size The size of the icon to retrieve. Currently 16
 138                (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
 139
 140         \return A status code, \c B_OK if everything went fine, an error code
 141                 otherwise.
 142         \retval B_OK Retrieved the icon successfully.
 143         \retval B_BAD_VALUE \a device or \a icon was \c NULL.
 144         \retval B_NO_MEMORY Ran out of memory allocating bitmap.
 145
 146         \since BeOS R3
 147 */
 148
 149
 150 /*!
 151         \fn status_t get_device_icon(const char* device, BBitmap* icon,
 152                 icon_size which)
 153         \brief Retrieves an icon associated with a given device into a BBitmap,
 154                C++ only.
 155
 156         \param device The path to the device.
 157         \param icon A pointer to a pre-allocated BBitmap of the correct dimension
 158                to store the requested icon (16x16 for the mini and 32x32 for the
 159                large icon).
 160         \param which The size of the icon to retrieve. Currently 16
 161                (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
 162
 163         \return A status code, \c B_OK if everything went fine, an error code
 164                 otherwise.
 165         \retval B_OK Retrieved the icon successfully.
 166         \retval B_BAD_VALUE \a device or \a icon was \c NULL.
 167
 168         \since Haiku R1
 169 */
 170
 171
 172 /*!
 173         \fn status_t get_device_icon(const char* device, uint8** _data,
 174                 size_t* _size, type_code* _type);
 175         \brief Try to get the icon by name first, if that fails try to get the
 176                vector icon, C++ only.
 177
 178         \param device The path to the device.
 179         \param _data A pointer to a pointer to an array of uint8 pixel data to
 180                fill out.
 181         \param _size The size of the icon to fill out. If vector, it is filled in
 182                with the width in pixels, if bitmap, one of the following constants:
 183                - \c B_MINI_ICON
 184                - \c B_LARGE_ICON
 185         \param _type The icon type code to fill out, one of the following:
 186                - \c B_MINI_ICON_TYPE
 187                - \c B_LARGE_ICON_TYPE
 188                - \c B_VECTOR_ICON_TYPE
 189
 190         \return A status code, \c B_OK if everything went fine, an error code
 191                 otherwise.
 192         \retval B_OK Retrieved the icon successfully.
 193         \retval B_BAD_VALUE \a device, \a _data, \a _size, or _type was \c NULL.
 194
 195         \since Haiku R1
 196 */
 197
 198
 199 /*!
 200         \fn status_t get_named_icon(const char* name, BBitmap* icon,
 201                 icon_size which);
 202         \brief Get the icon by name, C++ only.
 203
 204         \param name The name of the icon to get.
 205         \param icon A pointer to a pre-allocated BBitmap of the correct dimension
 206                to store the requested icon (16x16 for the mini and 32x32 for the
 207                large icon).
 208         \param which The size of the icon to retrieve. Currently 16
 209                (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported.
 210
 211         \return A status code, \c B_OK if everything went fine, an error code
 212                 otherwise.
 213         \retval B_OK Retrieved the icon successfully.
 214         \retval B_BAD_VALUE \a name or \a icon was \c NULL.
 215
 216         \since Haiku R1
 217 */
 218
 219
 220 /*!
 221         \fn status_t get_named_icon(const char* name, uint8** _data,
 222                 size_t* _size, type_code* _type);
 223         \brief Get the icon by name, C++ only.
 224
 225         \param name The name of the icon to get.
 226         \param _data A pointer to a pointer to an array of uint8 pixel data to
 227                fill out.
 228         \param _size The size of the icon to fill out. If vector, it is filled in
 229                with the width in pixels, if bitmap, one of the following constants:
 230                - \c B_MINI_ICON
 231                - \c B_LARGE_ICON
 232         \param _type The icon type code to fill out, one of the following:
 233                - \c B_MINI_ICON_TYPE
 234                - \c B_LARGE_ICON_TYPE
 235                - \c B_VECTOR_ICON_TYPE
 236
 237         \return A status code, \c B_OK if everything went fine, an error code
 238                 otherwise.
 239         \retval B_OK Retrieved the icon successfully.
 240         \retval B_BAD_VALUE \a name, \a _data, \a _size, or \c _type was \c NULL.
 241
 242         \since Haiku R1
 243 */