libgphoto2 photo camera library (libgphoto2) API: gphoto2/gphoto2-file.h File Reference

libgphoto2 photo camera library (libgphoto2) API 2.5.31

Data Structures | Macros | Typedefs | Enumerations | Functions
gphoto2-file.h File Reference

Abstracted gphoto2 file operations. More...

`#include <time.h>`
`#include <stdint.h>`

Go to the source code of this file.

## Data Structures
struct | _CameraFileHandler

## Macros
#define | GP_MIME_TXT "text/plain"
#define | GP_MIME_WAV "audio/wav"
#define | GP_MIME_RAW "image/x-raw"
#define | GP_MIME_PNG "image/png"
#define | GP_MIME_PGM "image/x-portable-graymap"
#define | GP_MIME_PPM "image/x-portable-pixmap"
#define | GP_MIME_PNM "image/x-portable-anymap"
#define | GP_MIME_JPEG "image/jpeg"
#define | GP_MIME_TIFF "image/tiff"
#define | GP_MIME_BMP "image/bmp"
#define | GP_MIME_QUICKTIME "video/quicktime"
#define | GP_MIME_AVI "video/x-msvideo"
#define | GP_MIME_CRW "image/x-canon-raw"
#define | GP_MIME_CR2 "image/x-canon-cr2"
#define | GP_MIME_CR3 "image/x-canon-cr3"
#define | GP_MIME_NEF "image/x-nikon-nef"
#define | GP_MIME_UNKNOWN "application/octet-stream"
#define | GP_MIME_EXIF "application/x-exif"
#define | GP_MIME_MP3 "audio/mpeg"
#define | GP_MIME_OGG "application/ogg"
#define | GP_MIME_WMA "audio/x-wma"
#define | GP_MIME_ASF "audio/x-asf"
#define | GP_MIME_MPEG "video/mpeg"
#define | GP_MIME_AVCHD "video/mp2t"
#define | GP_MIME_RW2 "image/x-panasonic-raw2"
#define | GP_MIME_ARW "image/x-sony-arw"

## Typedefs
typedef struct _CameraFileHandler | CameraFileHandler
typedef struct _CameraFile | CameraFile

## Enumerations
enum | CameraFileType { GP_FILE_TYPE_PREVIEW , GP_FILE_TYPE_NORMAL , GP_FILE_TYPE_RAW , GP_FILE_TYPE_AUDIO , GP_FILE_TYPE_EXIF , GP_FILE_TYPE_METADATA }
| The type of view on the specified file. More...
enum | CameraFileAccessType { GP_FILE_ACCESSTYPE_MEMORY , GP_FILE_ACCESSTYPE_FD , GP_FILE_ACCESSTYPE_HANDLER }
| File storage type. More...

## Functions
int | gp_file_new (CameraFile **file)
int | gp_file_new_from_fd (CameraFile **file, int fd)
int | gp_file_new_from_handler (CameraFile **file, CameraFileHandler *handler, void *priv)
int | gp_file_ref (CameraFile *file)
| Increase reference counter for CameraFile object.
int | gp_file_unref (CameraFile *file)
| Decrease reference counter for CameraFile object.
int | gp_file_free (CameraFile *file)
| descruct a CameraFile object.
int | gp_file_set_name (CameraFile *file, const char *name)
int | gp_file_get_name (CameraFile *file, const char **name)
int | gp_file_set_mime_type (CameraFile *file, const char *mime_type)
int | gp_file_get_mime_type (CameraFile *file, const char **mime_type)
int | gp_file_set_mtime (CameraFile *file, time_t mtime)
int | gp_file_get_mtime (CameraFile *file, time_t *mtime)
int | gp_file_detect_mime_type (CameraFile *file)
int | gp_file_adjust_name_for_mime_type (CameraFile *file)
int | gp_file_get_name_by_type (CameraFile *file, const char *basename, CameraFileType type, char **newname)
int | gp_file_set_data_and_size (CameraFile *, char *data, unsigned long int size)
int | gp_file_get_data_and_size (CameraFile *, const char **data, unsigned long int *size)
int | gp_file_open (CameraFile *file, const char *filename)
int | gp_file_save (CameraFile *file, const char *filename)
int | gp_file_clean (CameraFile *file)
int | gp_file_copy (CameraFile *destination, CameraFile *source)
int | gp_file_append (CameraFile *, const char *data, unsigned long int size)
int | gp_file_slurp (CameraFile *, char *data, size_t size, size_t *readlen)

## Detailed Description

Abstracted gphoto2 file operations.

Author
  Copyright 2000 Scott Fritzinger
  Copyright 2008-2009 Marcus Meissner

Note
  This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
  This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

## Enumeration Type Documentation

## ◆ CameraFileAccessType

enum CameraFileAccessType

File storage type.

The file storage type. Only used internally for now, but might be exposed later on. See gp_file_new() and gp_file_new_from_fd().

Enumerator
GP_FILE_ACCESSTYPE_MEMORY | File is in system memory.
GP_FILE_ACCESSTYPE_FD | File is associated with a UNIX filedescriptor.
GP_FILE_ACCESSTYPE_HANDLER | File is associated with a programmatic handler.

## ◆ CameraFileType

enum CameraFileType

The type of view on the specified file.

Specifies the file of the current file, usually passed to the gp_camera_file_get() and gp_camera_file_put() functions. This is useful for multiple views of one file, like that an single image file has "raw", "normal", "exif" and "preview" views, or a media file has "normal" and "metadata" file views.

Enumerator
GP_FILE_TYPE_PREVIEW | A preview of an image.
GP_FILE_TYPE_NORMAL | The regular normal data of a file.
GP_FILE_TYPE_RAW | The raw mode of a file, for instance the raw bayer data for cameras where postprocessing is done in the driver. The RAW files of modern DSLRs are GP_FILE_TYPE_NORMAL usually.
GP_FILE_TYPE_AUDIO | The audio view of a file. Perhaps an embedded comment or similar.
GP_FILE_TYPE_EXIF | The embedded EXIF data of an image.
GP_FILE_TYPE_METADATA | The metadata of a file, like Metadata of files on MTP devices.

## Function Documentation

## ◆ gp_file_adjust_name_for_mime_type()

int gp_file_adjust_name_for_mime_type | ( | CameraFile * | file | ) |

Parameters

  file | a CameraFile

Returns
  a gphoto2 error code.

References GP_OK.

Referenced by gp_filesystem_get_file().

## ◆ gp_file_append()

int gp_file_append | ( | CameraFile * | file,
|  | const char * | data,
|  | unsigned long int | size
| ) |  |

Parameters

  file | a CameraFile
  data |
  size |

Returns
  a gphoto2 error code.

References GP_ERROR, GP_ERROR_IO_WRITE, GP_FILE_ACCESSTYPE_FD, GP_FILE_ACCESSTYPE_HANDLER, GP_FILE_ACCESSTYPE_MEMORY, and GP_OK.

## ◆ gp_file_clean()

int gp_file_clean | ( | CameraFile * | file | ) |

Parameters

  file | a CameraFile

Returns
  a gphoto2 error code.

References GP_FILE_ACCESSTYPE_FD, GP_FILE_ACCESSTYPE_MEMORY, and GP_OK.

Referenced by gp_camera_capture_preview(), gp_camera_file_get(), gp_file_free(), and gp_file_open().

## ◆ gp_file_copy()

int gp_file_copy | ( | CameraFile * | destination,
|  | CameraFile * | source
| ) |  |

Parameters

  destination | a CameraFile
  source | a CameraFile

Returns
  a gphoto2 error code.

References GP_ERROR, GP_ERROR_IO, GP_ERROR_IO_READ, GP_ERROR_IO_WRITE, GP_FILE_ACCESSTYPE_FD, GP_FILE_ACCESSTYPE_HANDLER, GP_FILE_ACCESSTYPE_MEMORY, and GP_OK.

## ◆ gp_file_detect_mime_type()

int gp_file_detect_mime_type | ( | CameraFile * | file | ) |

Parameters

  file | a CameraFile

Returns
  a gphoto2 error code.

References GP_ERROR_IO_READ, GP_FILE_ACCESSTYPE_FD, GP_FILE_ACCESSTYPE_MEMORY, gp_file_set_mime_type(), and GP_OK.

## ◆ gp_file_free()

int gp_file_free | ( | CameraFile * | file | ) |

descruct a CameraFile object.

Parameters

  file | a CameraFile

Returns
  a gphoto2 error code.

References GP_FILE_ACCESSTYPE_FD, gp_file_clean(), and GP_OK.

Referenced by gp_file_unref().

## ◆ gp_file_get_data_and_size()

int gp_file_get_data_and_size | ( | CameraFile * | file,
|  | const char ** | data,
|  | unsigned long int * | size
| ) |  |

Get a pointer to the data and the file's size.

Parameters

  file | a CameraFile
  data |
  size |

Returns
  a gphoto2 error code.

Both data and size can be NULL and will then be ignored.

For regular CameraFiles, the pointer to data that is returned is still owned by libgphoto2 and its lifetime is the same as the #file.

For filedescriptor or handler based CameraFile types, the returned data pointer is owned by the caller and needs to be free()d to avoid memory leaks.

References GP_ERROR, GP_ERROR_IO, GP_ERROR_IO_READ, GP_FILE_ACCESSTYPE_FD, GP_FILE_ACCESSTYPE_HANDLER, GP_FILE_ACCESSTYPE_MEMORY, and GP_OK.

Referenced by gp_camera_file_get_info(), gp_filesystem_get_file(), gp_filesystem_read_file(), and gp_filesystem_set_file_noop().

## ◆ gp_file_get_mime_type()

int gp_file_get_mime_type | ( | CameraFile * | file,
|  | const char ** | mime_type
| ) |  |

Parameters

  file | a CameraFile
  mime_type | a pointer to a MIME type string

Returns
  a gphoto2 error code.

References GP_OK.

Referenced by gp_camera_file_get_info().

## ◆ gp_file_get_mtime()

int gp_file_get_mtime | ( | CameraFile * | file,
|  | time_t * | mtime
| ) |  |

Parameters

  file | a CameraFile
  mtime |

Returns
  a gphoto2 error code.

References GP_OK.

Referenced by gp_filesystem_set_file_noop().

## ◆ gp_file_get_name()

int gp_file_get_name | ( | CameraFile * | file,
|  | const char ** | name
| ) |  |

Parameters

  file | a CameraFile
  name | a pointer to a name string

Returns
  a gphoto2 error code.

References GP_OK.

## ◆ gp_file_get_name_by_type()

int gp_file_get_name_by_type | ( | CameraFile * | file,
|  | const char * | basename,
|  | CameraFileType | type,
|  | char ** | newname
| ) |  |

Parameters

  file | a CameraFile
  basename | the basename of the file
  type | the gphoto type of the file
  newname | the new name generated

Returns
  a gphoto2 error code.

This function takes the basename and generates a filename out of it depending on the gphoto filetype and the mime type in the file. The gphoto filetype will be converted to a prefix, like thumb_ or raw_, the mimetype will replace the current suffix by a different one (if necessary).

This can be used so that saving thumbnails or metadata will not overwrite the normal files.

References GP_FILE_TYPE_AUDIO, GP_FILE_TYPE_EXIF, GP_FILE_TYPE_METADATA, GP_FILE_TYPE_NORMAL, GP_FILE_TYPE_PREVIEW, GP_FILE_TYPE_RAW, and GP_OK.

Referenced by gp_camera_capture_preview().

## ◆ gp_file_new()

int gp_file_new | ( | CameraFile ** | file | ) |

Create new CameraFile object.

Parameters

  file | a pointer to a CameraFile

Returns
  a gphoto2 error code.

References GP_FILE_ACCESSTYPE_MEMORY, and GP_OK.

Referenced by gp_camera_file_get_info(), gp_filesystem_get_file(), and gp_filesystem_read_file().

## ◆ gp_file_new_from_fd()

int gp_file_new_from_fd | ( | CameraFile ** | file,
|  | int | fd
| ) |  |

Create new CameraFile object from a UNIX filedescriptor.

This function takes ownership of the filedescriptor and will close it when closing the CameraFile.

Parameters

  file | a pointer to a CameraFile
  fd | a UNIX filedescriptor

Returns
  a gphoto2 error code.

References GP_FILE_ACCESSTYPE_FD, and GP_OK.

## ◆ gp_file_new_from_handler()

int gp_file_new_from_handler | ( | CameraFile ** | file,
|  | CameraFileHandler * | handler,
|  | void * | private
| ) |  |

Create new CameraFile object using a programmatic handler.

Parameters

  file | a pointer to a CameraFile
  handler | a CameraFileHandler
  private | a private pointer for frontend use

Returns
  a gphoto2 error code.

References GP_FILE_ACCESSTYPE_HANDLER, and GP_OK.

## ◆ gp_file_open()

int gp_file_open | ( | CameraFile * | file,
|  | const char * | filename
| ) |  |

Parameters

  file | a CameraFile
  filename |

Returns
  a gphoto2 error code.

References GP_ERROR, GP_ERROR_NO_MEMORY, GP_FILE_ACCESSTYPE_FD, GP_FILE_ACCESSTYPE_MEMORY, gp_file_clean(), and GP_OK.

## ◆ gp_file_ref()

int gp_file_ref | ( | CameraFile * | file | ) |

Increase reference counter for CameraFile object.

Parameters

  file | a CameraFile

Returns
  a gphoto2 error code.

References GP_OK.

Referenced by gp_filesystem_set_file_noop().

## ◆ gp_file_save()

int gp_file_save | ( | CameraFile * | file,
|  | const char * | filename
| ) |  |

Parameters

  file | a CameraFile
  filename |

Returns
  a gphoto2 error code.

References GP_ERROR, GP_ERROR_IO, GP_ERROR_IO_READ, GP_FILE_ACCESSTYPE_FD, GP_FILE_ACCESSTYPE_MEMORY, and GP_OK.

## ◆ gp_file_set_data_and_size()

int gp_file_set_data_and_size | ( | CameraFile * | file,
|  | char * | data,
|  | unsigned long int | size
| ) |  |

Parameters

  file | a CameraFile
  data |
  size |

Returns
  a gphoto2 error code.

References GP_ERROR, GP_ERROR_IO_WRITE, GP_FILE_ACCESSTYPE_FD, GP_FILE_ACCESSTYPE_HANDLER, GP_FILE_ACCESSTYPE_MEMORY, and GP_OK.

Referenced by gp_filesystem_get_file().

## ◆ gp_file_set_mime_type()

int gp_file_set_mime_type | ( | CameraFile * | file,
|  | const char * | mime_type
| ) |  |

Parameters

  file | a CameraFile
  mime_type | a MIME type string

Returns
  a gphoto2 error code.

References GP_OK.

Referenced by gp_file_detect_mime_type(), and gp_filesystem_get_file().

## ◆ gp_file_set_mtime()

int gp_file_set_mtime | ( | CameraFile * | file,
|  | time_t | mtime
| ) |  |

Parameters

  file | a CameraFile
  mtime |

Returns
  a gphoto2 error code.

References GP_OK.

Referenced by gp_filesystem_set_file_noop().

## ◆ gp_file_set_name()

int gp_file_set_name | ( | CameraFile * | file,
|  | const char * | name
| ) |  |

Parameters

  file | a CameraFile
  name | a pointer to a MIME type string

Returns
  a gphoto2 error code.

References GP_OK.

Referenced by gp_camera_capture_preview(), and gp_filesystem_get_file().

## ◆ gp_file_slurp()

int gp_file_slurp | ( | CameraFile * | file,
|  | char * | data,
|  | size_t | size,
|  | size_t * | readlen
| ) |  |

Parameters

  file | a CameraFile
  data |
  size |

Returns
  a gphoto2 error code.

Internal.

References GP_ERROR, GP_ERROR_IO_READ, GP_FILE_ACCESSTYPE_FD, GP_FILE_ACCESSTYPE_HANDLER, GP_FILE_ACCESSTYPE_MEMORY, and GP_OK.

## ◆ gp_file_unref()

int gp_file_unref | ( | CameraFile * | file | ) |

Decrease reference counter for CameraFile object.

Parameters

  file | a CameraFile

Returns
  a gphoto2 error code.

References gp_file_free(), and GP_OK.

Referenced by gp_camera_file_get_info(), gp_filesystem_get_file(), gp_filesystem_read_file(), and gp_filesystem_set_file_noop().