gphoto2/gphoto2-file.h

   1 /** \file
   2  * \brief Abstracted gphoto2 file operations.
   3  *
   4  * \author Copyright 2000 Scott Fritzinger
   5  *
   6  * \note
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Lesser General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * \note
  13  * This 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  * Lesser General Public License for more details.
  17  *
  18  * \note
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the
  21  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  22  * Boston, MA 02111-1307, USA.
  23  */
  24
  25 #ifndef __GPHOTO2_FILE_H__
  26 #define __GPHOTO2_FILE_H__
  27
  28 #include <time.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif /* __cplusplus */
  33
  34 #define GP_MIME_WAV       "audio/wav"
  35 #define GP_MIME_RAW       "image/x-raw"
  36 #define GP_MIME_PNG       "image/png"
  37 #define GP_MIME_PGM       "image/x-portable-graymap"
  38 #define GP_MIME_PPM       "image/x-portable-pixmap"
  39 #define GP_MIME_PNM       "image/x-portable-anymap"
  40 #define GP_MIME_JPEG      "image/jpeg"
  41 #define GP_MIME_TIFF      "image/tiff"
  42 #define GP_MIME_BMP       "image/bmp"
  43 #define GP_MIME_QUICKTIME "video/quicktime"
  44 #define GP_MIME_AVI       "video/x-msvideo"
  45 #define GP_MIME_CRW       "image/x-canon-raw"
  46 #define GP_MIME_CR2       "image/x-canon-cr2"
  47 #define GP_MIME_UNKNOWN   "application/octet-stream"
  48 #define GP_MIME_EXIF      "application/x-exif"
  49 #define GP_MIME_MP3       "audio/mpeg"
  50 #define GP_MIME_OGG       "application/ogg"
  51 #define GP_MIME_WMA       "audio/x-wma"
  52 #define GP_MIME_ASF       "audio/x-asf"
  53 #define GP_MIME_MPEG      "video/mpeg"
  54 #define GP_MIME_AVCHD     "video/avchd"
  55
  56 /**
  57  * \brief The type of view on the specified file.
  58  *
  59  * Specifies the file of the current file, usually passed
  60  * to the gp_camera_file_get() and gp_camera_file_put()
  61  * functions. This is useful for multiple views of one
  62  * file, like that an single image file has "raw", "normal",
  63  * "exif" and "preview" views, or a media file has "normal"
  64  * and "metadata" file views.
  65  */
  66 typedef enum {
  67         GP_FILE_TYPE_PREVIEW,   /**< A preview of an image. */
  68         GP_FILE_TYPE_NORMAL,    /**< The regular normal data of a file. */
  69         GP_FILE_TYPE_RAW,       /**< The raw mode of a file, for instance the raw bayer data for cameras
  70                                  * where postprocessing is done in the driver. The RAW files of modern
  71                                  * DSLRs are GP_FILE_TYPE_NORMAL usually. */
  72         GP_FILE_TYPE_AUDIO,     /**< The audio view of a file. Perhaps an embedded comment or similar. */
  73         GP_FILE_TYPE_EXIF,      /**< The embedded EXIF data of an image. */
  74         GP_FILE_TYPE_METADATA   /**< The metadata of a file, like Metadata of files on MTP devices. */
  75 } CameraFileType;
  76
  77 /**
  78  * \brief File storage type.
  79  *
  80  * The file storage type. Only used internally for now, but might
  81  * be exposed later on. See gp_file_new() and gp_file_new_from_fd().
  82  */
  83 typedef enum {
  84         GP_FILE_ACCESSTYPE_MEMORY,      /**< File is in system memory. */
  85         GP_FILE_ACCESSTYPE_FD           /**< File is associated with a UNIX filedescriptor. */
  86 } CameraFileAccessType;
  87
  88 /*! \struct CameraFile
  89  * \brief File structure.
  90  *
  91  * The internals of the CameraFile struct are private, please use
  92  * the accessor functions.
  93  */
  94 typedef struct _CameraFile CameraFile;
  95
  96 int gp_file_new            (CameraFile **file);
  97 int gp_file_new_from_fd    (CameraFile **file, int fd);
  98 int gp_file_ref            (CameraFile *file);
  99 int gp_file_unref          (CameraFile *file);
 100 int gp_file_free           (CameraFile *file);
 101
 102 /* "Do not use those"
 103  *
 104  * These functions probably were originally intended for internal use only.
 105  * However, due to
 106  *   - the lack of good documentation
 107  *   - this being the obvious way to save a file
 108  *   - the fact that libgphoto2 has been exporting all its internal
 109  *     symbols for years (until 2005-06)
 110  *   - our in-house frontends gphoto2 and gtkam using them
 111  * a number of external frontends started to use these functions, as
 112  * of 2005-06:
 113  *    - digikam
 114  *    - f-spot
 115  *    - gthumb
 116  * But a few frontends can live without it (and thus are likely to
 117  * use the correct API):
 118  *    - flphoto
 119  *    - kamera
 120  *
 121  * So we're going to phase these functions out over the next year or
 122  * so, going the GTK way of keeping the ABI but breaking the API. So
 123  * we'll continue to export functionally equivalent functions, but the
 124  * header files will not contain definitions for you to use any more.
 125  */
 126 int gp_file_open           (CameraFile *file, const char *filename);
 127 int gp_file_save           (CameraFile *file, const char *filename);
 128 int gp_file_clean          (CameraFile *file);
 129 int gp_file_copy           (CameraFile *destination, CameraFile *source);
 130
 131 int gp_file_set_name       (CameraFile *file, const char  *name);
 132 int gp_file_get_name       (CameraFile *file, const char **name);
 133
 134 int gp_file_set_mime_type  (CameraFile *file, const char  *mime_type);
 135 int gp_file_get_mime_type  (CameraFile *file, const char **mime_type);
 136
 137 int gp_file_set_type       (CameraFile *file, CameraFileType  type);
 138 int gp_file_get_type       (CameraFile *file, CameraFileType *type);
 139
 140 int gp_file_set_mtime   (CameraFile *file, time_t  mtime);
 141 int gp_file_get_mtime   (CameraFile *file, time_t *mtime);
 142
 143 int gp_file_detect_mime_type          (CameraFile *file);
 144 int gp_file_adjust_name_for_mime_type (CameraFile *file);
 145
 146 int gp_file_append            (CameraFile*, const char *data,
 147                                unsigned long int size);
 148 int gp_file_slurp             (CameraFile*, char *data,
 149                                size_t size, size_t *readlen);
 150 int gp_file_set_data_and_size (CameraFile*,       char *data,
 151                                unsigned long int size);
 152 int gp_file_get_data_and_size (CameraFile*, const char **data,
 153                                unsigned long int *size);
 154
 155 #ifdef __cplusplus
 156 }
 157 #endif /* __cplusplus */
 158
 159 #endif /* __GPHOTO2_FILE_H__ */