diff --git a/docs/user/storage/Mime.dox b/docs/user/storage/Mime.dox new file mode 100644 index 0000000000..2488a75cba --- /dev/null +++ b/docs/user/storage/Mime.dox @@ -0,0 +1,187 @@ +/* + * Copyright 2013 Haiku Inc. + * Distributed under the terms of the MIT License. + * + * Documentation by: + * Ingo Weinhold, bonefish@users.sf.net + * John Scipione, jscipione@gmail.com + * + * Corresponds to: + * /trunk/headers/os/storage/Mime.h hrev45224 + * /trunk/src/kits/storage/Mime.cpp hrev45224 + */ + + +/*! + \file Mime.h + \ingroup storage + \brief Provides C and Haiku-only C++ MIME-type handling functions. +*/ + + +/*! + \enum icon_size + \brief Legacy BeOS icon size constants. +*/ + + +/*! + \var icon_size B_LARGE_ICON + + 32x32 "Large" icon. +*/ + + +/*! + \var icon_size B_MINI_ICON + + 16x16 "Mini" icon. +*/ + + +/*! + \var B_UPDATE_MIME_INFO_NO_FORCE + + Files that already have a \c BEOS:TYPE attribute won't be updated. +*/ + + +/*! + \var B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE + + Files that already have a \c BEOS:TYPE attribute will be updated too, but + \c BEOS:TYPE itself will remain untouched. +*/ + + +/*! + \var B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL + + Similar to \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE, but the \c BEOS:TYPE + attribute will be updated too. +*/ + + +/*! + \fn status_t do_mime_update(int32 what, const char *path, int recursive, + int synchronous, int force) + \brief Helper function that contacts the registrar for mime update calls. + + \param what The message identifier. + \param path The path to a file or directory, or \c NULL. + \param recursive Triggers recursive behavior if not \c NULL. + \param synchronous If not \c NULL update_mime_info() waits until the + operation is finished, otherwise it returns immediately and the + update is done asynchronously. + \param force Specifies how to handle files that already have MIME + information. + + \returns A status code. + + \see update_mime_info +*/ + + +/*! + \fn int update_mime_info(const char *path, int recursive, int synchronous, + int force) + \brief Updates the MIME information (i.e MIME type) for one or more files. + + If \a path points to a file, the MIME information for this file are + updated only. If it points to a directory and \a recursive is non-null, + the information for all the files in the given directory tree are updated. + If path is \c NULL all files are considered; \a recursive is ignored in + this case. + + \param path The path to a file or directory, or \c NULL. + \param recursive Triggers recursive behavior if not \c NULL. + \param synchronous If not \c NULL update_mime_info() waits until the + operation is finished, otherwise it returns immediately and the + update is done asynchronously. + \param force Specifies how to handle files that already have MIME + information. See enum definitions for more information. + - \c B_UPDATE_MIME_INFO_NO_FORCE + - \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE + - \c B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL + + \returns A status code. \c B_OK if everything went fine, an error code + otherwise. +*/ + + +/*! + \fn status_t create_app_meta_mime(const char *path, int recursive, + int synchronous, int force) + \brief Creates a MIME database entry for one or more applications. + + If \a path points to an application file, a MIME DB entry is create for + the application. If it points to a directory and \a recursive is not + \c NULL then entries are created for all application files in the given + directory tree. If path is \c NULL then all files are considered and + \a recursive is ignored. + + \param path The path to an application file, a directory, or \c NULL. + \param recursive Trigger recursive behavior if not \c NULL. + \param synchronous Waits until the operation is finished if not \c NULL, + otherwise it returns immediately and the operation is done + asynchronously. + \param force Entries are created even if they do already exist if not + \c NULL. + + \returns A status code. \c B_OK if everything went fine, an error code + otherwise. +*/ + + +/*! + \fn status_t get_device_icon(const char *device, void *icon, int32 size) + \brief Retrieves an icon associated with a given device. + + \param device The path to the device. + \param icon A pointer to a buffer the icon data shall be written to. + \param size The size of the icon to retrieve. Currently 16 + (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported. + + \returns A status code. + \retval B_OK Everything went fine. + \retval B_BAD_VALUE \a device or \a icon was \c NULL. + \retval B_NO_MEMORY Ran out of memory allocating bitmap. +*/ + + +/*! + \fn status_t get_device_icon(const char *device, BBitmap *icon, + icon_size which) + \brief Retrieves an icon associated with a given device into a BBitmap. + + \param device The path to the device. + \param icon A pointer to a pre-allocated BBitmap of the correct dimension + to store the requested icon (16x16 for the mini and 32x32 for the + large icon). + \param which The size of the icon to retrieve. Currently 16 + (\c B_MINI_ICON) and 32 (\c B_LARGE_ICON) are supported. + + \returns A status code. \c B_OK if everything went fine, an error code + otherwise. +*/ + + +/*! + \fn status_t get_device_icon(const char* device, uint8** _data, + size_t* _size, type_code* _type); + \brief Undocumented. +*/ + + +/*! + \fn status_t get_named_icon(const char* name, BBitmap* icon, + icon_size which); + \brief Undocumented. +*/ + + +/*! + \fn status_t get_named_icon(const char* name, uint8** _data, + size_t* _size, type_code* _type); + \brief Undocumented. +*/ diff --git a/src/kits/storage/Mime.cpp b/src/kits/storage/Mime.cpp index 7c7d18d455..8058be2594 100644 --- a/src/kits/storage/Mime.cpp +++ b/src/kits/storage/Mime.cpp @@ -38,14 +38,15 @@ #include #include + using namespace BPrivate; enum { NOT_IMPLEMENTED = B_ERROR, }; -// do_mime_update -//! Helper function that contacts the registrar for mime update calls + +// Helper function that contacts the registrar for mime update calls status_t do_mime_update(int32 what, const char *path, int recursive, int synchronous, int force) @@ -82,32 +83,8 @@ do_mime_update(int32 what, const char *path, int recursive, return err; } -// update_mime_info -/*! \brief Updates the MIME information (i.e MIME type) for one or more files. - If \a path points to a file, the MIME information for this file are - updated only. If it points to a directory and \a recursive is non-null, - the information for all the files in the given directory tree are updated. - If path is \c NULL all files are considered; \a recursive is ignored in - this case. - \param path The path to a file or directory, or \c NULL. - \param recursive Non-null to trigger recursive behavior. - \param synchronous If non-null update_mime_info() waits until the - operation is finished, otherwise it returns immediately and the - update is done asynchronously. - \param force Specifies how to handle files that already have MIME - information: - - \c B_UPDATE_MIME_INFO_NO_FORCE: Files that already have a - \c BEOS:TYPE attribute won't be updated. - - \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE: Files that already have a - \c BEOS:TYPE attribute will be updated too, but \c BEOS:TYPE - itself will remain untouched. - - \c B_UPDATE_MIME_INFO_FORCE_UPDATE_ALL: Similar to - \c B_UPDATE_MIME_INFO_FORCE_KEEP_TYPE, but the \c BEOS:TYPE - attribute will be updated too. - \return - - \c B_OK: Everything went fine. - - An error code otherwise. -*/ + +// Updates the MIME information (i.e MIME type) for one or more files. int update_mime_info(const char *path, int recursive, int synchronous, int force) { @@ -119,24 +96,8 @@ update_mime_info(const char *path, int recursive, int synchronous, int force) synchronous, force); } -// create_app_meta_mime -/*! Creates a MIME database entry for one or more applications. - If \a path points to an application file, a MIME DB entry is create for the - application. If it points to a directory and \a recursive is non-null, - entries are created for all application files in the given directory - tree. If path is \c NULL all files are considered; \a recursive is - ignored in this case. - \param path The path to an application file, a directory, or \c NULL. - \param recursive Non-null to trigger recursive behavior. - \param synchronous If non-null create_app_meta_mime() waits until the - operation is finished, otherwise it returns immediately and the - operation is done asynchronously. - \param force If non-null, entries are created even if they do already - exist. - \return - - \c B_OK: Everything went fine. - - An error code otherwise. -*/ + +// Creates a MIME database entry for one or more applications. status_t create_app_meta_mime(const char *path, int recursive, int synchronous, int force) @@ -150,21 +111,7 @@ create_app_meta_mime(const char *path, int recursive, int synchronous, } -/*! Retrieves an icon associated with a given device. - \param dev The path to the device. - \param icon A pointer to a buffer the icon data shall be written to. - \param size The size of the icon. Currently the sizes 16 (small, i.e - \c B_MINI_ICON) and 32 (large, i.e. \c B_LARGE_ICON) are - supported. - - \todo The mounted directories for volumes can also have META:X:STD_ICON - attributes. Should those attributes override the icon returned - by ioctl(,B_GET_ICON,)? - - \return - - \c B_OK: Everything went fine. - - An error code otherwise. -*/ +// Retrieves an icon associated with a given device. status_t get_device_icon(const char *device, void *icon, int32 size) { @@ -176,6 +123,9 @@ get_device_icon(const char *device, void *icon, int32 size) if (fd < 0) return errno; + // ToDo: The mounted directories for volumes can also have META:X:STD_ICON + // attributes. Should those attributes override the icon returned by + // ioctl(,B_GET_ICON,)? device_icon iconData = {size, icon}; if (ioctl(fd, B_GET_ICON, &iconData) != 0) { // legacy icon was not available, try vector icon @@ -218,22 +168,7 @@ get_device_icon(const char *device, void *icon, int32 size) } -/*! Retrieves an icon associated with a given device. - \param dev The path to the device. - \param icon A pointer to a pre-allocated BBitmap of the correct dimension - to store the requested icon (16x16 for the mini and 32x32 for the - large icon). - \param which Specifies the size of the icon to be retrieved: - \c B_MINI_ICON for the mini and \c B_LARGE_ICON for the large icon. - - \todo The mounted directories for volumes can also have META:X:STD_ICON - attributes. Should those attributes override the icon returned - by ioctl(,B_GET_ICON,)? - - \return - - \c B_OK: Everything went fine. - - An error code otherwise. -*/ +// Retrieves an icon associated with a given device. status_t get_device_icon(const char *device, BBitmap *icon, icon_size which) {