485 lines
17 KiB
C
485 lines
17 KiB
C
/** \file
|
|
*
|
|
* \brief Implement Camera object representing a camera attached to the system.
|
|
*
|
|
* \author Copyright 2000 Scott Fritzinger
|
|
*
|
|
* \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.
|
|
*
|
|
* \note
|
|
* 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.
|
|
*
|
|
* \note
|
|
* 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
|
|
*/
|
|
|
|
#ifndef LIBGPHOTO2_GPHOTO2_CAMERA_H
|
|
#define LIBGPHOTO2_GPHOTO2_CAMERA_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif /* __cplusplus */
|
|
|
|
/**
|
|
* \brief Object representing a camera attached to the system.
|
|
*
|
|
* A Camera object represents a specific instance of a (physical of
|
|
* virtual) camera attached to the system.
|
|
*
|
|
* The abilities of this type of camera are stored in a CameraAbility
|
|
* object.
|
|
*
|
|
* The details of the Camera object are internal.
|
|
*/
|
|
typedef struct _Camera Camera;
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* __cplusplus */
|
|
|
|
|
|
#include <gphoto2/gphoto2-abilities-list.h>
|
|
#include <gphoto2/gphoto2-port.h>
|
|
|
|
#include <gphoto2/gphoto2-widget.h>
|
|
#include <gphoto2/gphoto2-filesys.h>
|
|
#include <gphoto2/gphoto2-result.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif /* __cplusplus */
|
|
|
|
/**
|
|
* \brief CameraText structure used in various functions.
|
|
*
|
|
* A text structure containing translated text returned
|
|
* by various functions (about, manual, summary). You should
|
|
* not assume a size.
|
|
*/
|
|
typedef struct {
|
|
char text [32 * 1024]; /**< \brief Character string containing the translated text. */
|
|
} CameraText;
|
|
|
|
/**
|
|
* \brief A structure created by the capture operation.
|
|
*
|
|
* A structure containing the folder and filename of an object
|
|
* after a successful capture and is passed as reference to the
|
|
* gp_camera_capture() function.
|
|
*/
|
|
typedef struct {
|
|
char name [128]; /**< \brief Name of the captured file. */
|
|
char folder [1024]; /**< \brief Name of the folder of the captured file. */
|
|
} CameraFilePath;
|
|
|
|
/**
|
|
* \brief Type of the capture to do.
|
|
*
|
|
* Specifies the type of capture the user wants to do with the
|
|
* gp_camera_capture() function.
|
|
*/
|
|
typedef enum {
|
|
GP_CAPTURE_IMAGE, /**< \brief Capture an image. */
|
|
GP_CAPTURE_MOVIE, /**< \brief Capture a movie. */
|
|
GP_CAPTURE_SOUND /**< \brief Capture audio. */
|
|
} CameraCaptureType;
|
|
|
|
/**
|
|
* \brief Specify what event we received from the camera.
|
|
*
|
|
* Used by gp_camera_wait_for_event() to specify what
|
|
* event happened on the camera.
|
|
*
|
|
*/
|
|
typedef enum {
|
|
GP_EVENT_UNKNOWN, /**< unknown and unhandled event. argument is a char* or NULL */
|
|
GP_EVENT_TIMEOUT, /**< timeout, no arguments */
|
|
GP_EVENT_FILE_ADDED, /**< CameraFilePath* = file path on camfs */
|
|
GP_EVENT_FOLDER_ADDED, /**< CameraFilePath* = folder on camfs */
|
|
GP_EVENT_CAPTURE_COMPLETE, /**< last capture is complete */
|
|
GP_EVENT_FILE_CHANGED /**< CameraFilePath* = file path on camfs */
|
|
} CameraEventType;
|
|
|
|
/**
|
|
* \name Camera object member functions
|
|
*
|
|
* These functions must be implemented by a camlib and the camlib's
|
|
* camera_init() function will add them to a Camera object.
|
|
*
|
|
* @{
|
|
*/
|
|
/**
|
|
* \brief The camera exit function
|
|
*
|
|
* \param camera the current camera
|
|
* \param context a #GPContext
|
|
*
|
|
* This functions is called in the camera driver for closing the camera
|
|
* connection. It should do the necessary cleanups of the internal camera
|
|
* state, free allocated private structures and similar.
|
|
*
|
|
* The driver does not need to close the #GPPort, this is done by libgphoto2
|
|
* itself.
|
|
*
|
|
* Implement this function if you need to any of this stuff, otherwise leave
|
|
* it out.
|
|
*
|
|
* \returns a gphoto error code
|
|
*/
|
|
typedef int (*CameraExitFunc) (Camera *camera, GPContext *context);
|
|
|
|
/**
|
|
* \brief Get a configuration tree for the camera and its driver
|
|
*
|
|
* \param camera the current camera
|
|
* \param widget pointer to store the toplevel widget of the tree
|
|
* \param context the active #GPContext
|
|
*
|
|
* A camera driver can support configuration of either its own behaviour
|
|
* or the camera device itself. To allow a flexible driver framework,
|
|
* the camera driver provides a generic configuration widget tree to the
|
|
* frontend, which then renders it, allows user input and sends it back
|
|
* via the #CameraSetConfigFunc function to have the driver configure itself
|
|
* or the camera.
|
|
*
|
|
* If you do not have configuration ability, there is no need to specify this
|
|
* function.
|
|
*
|
|
* \returns a gphoto error code
|
|
*/
|
|
typedef int (*CameraGetConfigFunc) (Camera *camera, CameraWidget **widget,
|
|
GPContext *context);
|
|
/**
|
|
* \brief Get a configuration widget for a specific configuration
|
|
*
|
|
* \param camera the current camera
|
|
* \param name the name of the widget
|
|
* \param widget pointer to store the toplevel widget of the tree
|
|
* \param context the active #GPContext
|
|
*
|
|
* A camera driver can support configuration of either its own behaviour
|
|
* or the camera device itself. To allow a flexible driver framework,
|
|
* the camera driver provides a generic configuration widget tree to the
|
|
* frontend, which then renders it, allows user input and sends it back
|
|
* via the #CameraSetConfigFunc function to have the driver configure itself
|
|
* or the camera.
|
|
*
|
|
* This specific function retrieves one specific named entry, and not the full
|
|
* tree to allow for querying specific settings faster.
|
|
*
|
|
* If you do not have configuration ability, there is no need to specify this
|
|
* function.
|
|
*
|
|
* \returns a gphoto error code
|
|
*/
|
|
typedef int (*CameraGetSingleConfigFunc) (Camera *camera, const char *name, CameraWidget **widget,
|
|
GPContext *context);
|
|
/**
|
|
* \brief List all configuration widgets for a specific configuration
|
|
*
|
|
* \param camera the current camera
|
|
* \param list the list of widgets available
|
|
* \param context the active #GPContext
|
|
*
|
|
* A camera driver can support configuration of either its own behaviour
|
|
* or the camera device itself. To allow a flexible driver framework,
|
|
* the camera driver provides a generic configuration widget tree to the
|
|
* frontend, which then renders it, allows user input and sends it back
|
|
* via the #CameraSetConfigFunc function to have the driver configure itself
|
|
* or the camera.
|
|
*
|
|
* This specific function retrieves all the available configuration values in a flat list.
|
|
*
|
|
* This is different than the GetConfigFunc, which returns a configuration tree.
|
|
*
|
|
* If you do not have configuration ability, there is no need to specify this
|
|
* function.
|
|
*
|
|
* \returns a gphoto error code
|
|
*/
|
|
typedef int (*CameraListConfigFunc) (Camera *camera, CameraList *list, GPContext *context);
|
|
/**
|
|
* \brief Set the configuration in the camera
|
|
*
|
|
* \param camera the current camera
|
|
* \param widget the configuration widget tree that was changed
|
|
* \param context the active #GPContext
|
|
*
|
|
* This function is called in the driver after the configuration is set.
|
|
* It is called directly after setting the value and might called multiple
|
|
* times (or never) after just one #CameraGetConfigFunc.
|
|
*
|
|
* \returns a gphoto error code
|
|
*/
|
|
typedef int (*CameraSetConfigFunc) (Camera *camera, CameraWidget *widget,
|
|
GPContext *context);
|
|
/**
|
|
* \brief Set a single configuration variable in the camera
|
|
*
|
|
* \param camera the current camera
|
|
* \param name the widget to set
|
|
* \param widget the configuration widget tree that was changed
|
|
* \param context the active #GPContext
|
|
*
|
|
* This function is called in the driver after the configuration value is set.
|
|
*
|
|
* \returns a gphoto error code
|
|
*/
|
|
typedef int (*CameraSetSingleConfigFunc) (Camera *camera, const char *name, CameraWidget *widget,
|
|
GPContext *context);
|
|
|
|
typedef int (*CameraCaptureFunc) (Camera *camera, CameraCaptureType type,
|
|
CameraFilePath *path, GPContext *context);
|
|
typedef int (*CameraTriggerCaptureFunc) (Camera *camera, GPContext *context);
|
|
typedef int (*CameraCapturePreviewFunc) (Camera *camera, CameraFile *file,
|
|
GPContext *context);
|
|
typedef int (*CameraSummaryFunc) (Camera *camera, CameraText *text,
|
|
GPContext *context);
|
|
typedef int (*CameraManualFunc) (Camera *camera, CameraText *text,
|
|
GPContext *context);
|
|
typedef int (*CameraAboutFunc) (Camera *camera, CameraText *text,
|
|
GPContext *context);
|
|
typedef int (*CameraWaitForEvent) (Camera *camera, int timeout,
|
|
CameraEventType *eventtype, void **eventdata,
|
|
GPContext *context);
|
|
/**@}*/
|
|
|
|
|
|
/**
|
|
* \param camera a \ref Camera object
|
|
* \param context a \ref GPContext object
|
|
* \return a gphoto2 error code
|
|
*
|
|
* Implement this function in the camera driver if the camera needs to
|
|
* be initialized before or reset the after each access from
|
|
* libgphoto2.
|
|
*
|
|
* For example, you would probably set the speed to the highest one
|
|
* right before downloading an image, and reset it to the default speed
|
|
* afterwards so that other programs will not be affected by this speed
|
|
* change.
|
|
*/
|
|
typedef int (*CameraPrePostFunc) (Camera *camera, GPContext *context);
|
|
|
|
/**
|
|
* \brief Various camera specific functions.
|
|
*
|
|
* This structure contains various pointers to functions that apply to
|
|
* the camera itself, and not the filesystem (which is handled by the
|
|
* filesystem functions). Set the ones you want to provide, leave the rest
|
|
* unset.
|
|
*
|
|
* This structure should only used by the driver itself, the frontend
|
|
* should use the gp_camera_xxx wrapper functions for it, who handle
|
|
* opening and locking around those hooks.
|
|
*/
|
|
typedef struct _CameraFunctions {
|
|
CameraPrePostFunc pre_func; /**< \brief Function called before each camera operation. */
|
|
CameraPrePostFunc post_func; /**< \brief Function called after each camera operation. */
|
|
|
|
CameraExitFunc exit; /**< \brief Function called on closing the camera. */
|
|
|
|
/* Configuration */
|
|
CameraGetConfigFunc get_config; /**< \brief Called for requesting the configuration widgets. */
|
|
CameraSetConfigFunc set_config; /**< \brief Called after a configuration was changed */
|
|
|
|
CameraListConfigFunc list_config; /**< \brief Called for listing the available configuration widgets. */
|
|
CameraGetSingleConfigFunc get_single_config; /**< \brief Called for requesteing a single widget. */
|
|
CameraSetSingleConfigFunc set_single_config; /**< \brief Called for setting a single configuration widget. */
|
|
|
|
/* Capturing */
|
|
CameraCaptureFunc capture; /**< \brief Remote control the camera to capture */
|
|
CameraTriggerCaptureFunc trigger_capture;/**< \brief Remote control the camera to trigger capture */
|
|
CameraCapturePreviewFunc capture_preview;/**< \brief Preview viewfinder content. */
|
|
|
|
/* Textual information */
|
|
CameraSummaryFunc summary; /**< \brief Give a summary about the current camera status, translated. */
|
|
CameraManualFunc manual; /**< \brief Give a brief manual about any specific items a user has to know, translated. */
|
|
CameraAboutFunc about; /**< \brief A little About text, including authors and credits. */
|
|
|
|
/* Event Interface */
|
|
CameraWaitForEvent wait_for_event; /**< \brief Wait for a specific event from the camera */
|
|
/* Reserved space to use in the future without changing the struct size */
|
|
void *reserved1; /**< \brief reserved for future use */
|
|
void *reserved2; /**< \brief reserved for future use */
|
|
void *reserved3; /**< \brief reserved for future use */
|
|
void *reserved4; /**< \brief reserved for future use */
|
|
void *reserved5; /**< \brief reserved for future use */
|
|
void *reserved6; /**< \brief reserved for future use */
|
|
void *reserved7; /**< \brief reserved for future use */
|
|
void *reserved8; /**< \brief reserved for future use */
|
|
} CameraFunctions;
|
|
|
|
typedef struct _CameraPrivateLibrary CameraPrivateLibrary;
|
|
typedef struct _CameraPrivateCore CameraPrivateCore;
|
|
|
|
struct _Camera {
|
|
|
|
/** \name Those should be accessed only by the camera driver.
|
|
* @{ */
|
|
GPPort *port;
|
|
CameraFilesystem *fs;
|
|
CameraFunctions *functions;
|
|
/**@}*/
|
|
|
|
CameraPrivateLibrary *pl; /**< Private data of camera libraries. */
|
|
CameraPrivateCore *pc; /**< Private data of the core of gphoto2. */
|
|
};
|
|
|
|
|
|
/** Create a new camera device. */
|
|
int gp_camera_new (Camera **camera);
|
|
|
|
|
|
/** \name Preparing initialization
|
|
* @{
|
|
*/
|
|
int gp_camera_set_abilities (Camera *camera, CameraAbilities abilities);
|
|
int gp_camera_get_abilities (Camera *camera, CameraAbilities *abilities);
|
|
int gp_camera_set_port_info (Camera *camera, GPPortInfo info);
|
|
int gp_camera_get_port_info (Camera *camera, GPPortInfo *info);
|
|
|
|
/**@}*/
|
|
|
|
|
|
/**
|
|
* \name camera speed
|
|
*
|
|
* You normally don't use that. If you do, you prevent the camera driver
|
|
* from selecting the optimal speed.
|
|
*
|
|
* @{
|
|
*/
|
|
int gp_camera_set_port_speed (Camera *camera, int speed);
|
|
int gp_camera_get_port_speed (Camera *camera);
|
|
|
|
/**@}*/
|
|
|
|
|
|
/** \name Initialization
|
|
* @{
|
|
*/
|
|
int gp_camera_autodetect (CameraList *list, GPContext *context);
|
|
int gp_camera_init (Camera *camera, GPContext *context);
|
|
int gp_camera_exit (Camera *camera, GPContext *context);
|
|
|
|
/**@}*/
|
|
|
|
|
|
|
|
/** \name Operations on cameras
|
|
* @{
|
|
*/
|
|
int gp_camera_ref (Camera *camera);
|
|
int gp_camera_unref (Camera *camera);
|
|
int gp_camera_free (Camera *camera);
|
|
|
|
int gp_camera_get_config (Camera *camera, CameraWidget **window,
|
|
GPContext *context);
|
|
int gp_camera_list_config (Camera *camera, CameraList *list,
|
|
GPContext *context);
|
|
int gp_camera_get_single_config (Camera *camera, const char *name, CameraWidget **widget,
|
|
GPContext *context);
|
|
int gp_camera_set_config (Camera *camera, CameraWidget *window,
|
|
GPContext *context);
|
|
int gp_camera_set_single_config (Camera *camera, const char *name, CameraWidget *widget,
|
|
GPContext *context);
|
|
int gp_camera_get_summary (Camera *camera, CameraText *summary,
|
|
GPContext *context);
|
|
int gp_camera_get_manual (Camera *camera, CameraText *manual,
|
|
GPContext *context);
|
|
int gp_camera_get_about (Camera *camera, CameraText *about,
|
|
GPContext *context);
|
|
int gp_camera_capture (Camera *camera, CameraCaptureType type,
|
|
CameraFilePath *path, GPContext *context);
|
|
int gp_camera_trigger_capture (Camera *camera, GPContext *context);
|
|
int gp_camera_capture_preview (Camera *camera, CameraFile *file,
|
|
GPContext *context);
|
|
int gp_camera_wait_for_event (Camera *camera, int timeout,
|
|
CameraEventType *eventtype, void **eventdata,
|
|
GPContext *context);
|
|
|
|
int gp_camera_get_storageinfo (Camera *camera, CameraStorageInformation**,
|
|
int *, GPContext *context);
|
|
|
|
/**@}*/
|
|
|
|
|
|
/** \name Operations on folders
|
|
* @{
|
|
*/
|
|
int gp_camera_folder_list_files (Camera *camera, const char *folder,
|
|
CameraList *list, GPContext *context);
|
|
int gp_camera_folder_list_folders (Camera *camera, const char *folder,
|
|
CameraList *list, GPContext *context);
|
|
int gp_camera_folder_delete_all (Camera *camera, const char *folder,
|
|
GPContext *context);
|
|
int gp_camera_folder_put_file (Camera *camera,
|
|
const char *folder, const char *filename,
|
|
CameraFileType type,
|
|
CameraFile *file, GPContext *context);
|
|
int gp_camera_folder_make_dir (Camera *camera, const char *folder,
|
|
const char *name, GPContext *context);
|
|
int gp_camera_folder_remove_dir (Camera *camera, const char *folder,
|
|
const char *name, GPContext *context);
|
|
/**@}*/
|
|
|
|
|
|
/** \name Operations on files
|
|
* @{
|
|
*/
|
|
int gp_camera_file_get_info (Camera *camera, const char *folder,
|
|
const char *file, CameraFileInfo *info,
|
|
GPContext *context);
|
|
int gp_camera_file_set_info (Camera *camera, const char *folder,
|
|
const char *file, CameraFileInfo info,
|
|
GPContext *context);
|
|
int gp_camera_file_get (Camera *camera, const char *folder,
|
|
const char *file, CameraFileType type,
|
|
CameraFile *camera_file, GPContext *context);
|
|
int gp_camera_file_read (Camera *camera, const char *folder, const char *file,
|
|
CameraFileType type,
|
|
uint64_t offset, char *buf, uint64_t *size,
|
|
GPContext *context);
|
|
int gp_camera_file_delete (Camera *camera, const char *folder,
|
|
const char *file, GPContext *context);
|
|
/**@}*/
|
|
|
|
|
|
/**
|
|
* \name Some cameras need 'keep-alive-messages'.
|
|
* @{
|
|
*/
|
|
typedef int (* CameraTimeoutFunc) (Camera *camera,
|
|
GPContext *context);
|
|
typedef unsigned int (* CameraTimeoutStartFunc) (Camera *camera,
|
|
unsigned int timeout,
|
|
CameraTimeoutFunc func,
|
|
void *data);
|
|
typedef void (* CameraTimeoutStopFunc) (Camera *camera,
|
|
unsigned int id, void *data);
|
|
void gp_camera_set_timeout_funcs (Camera *camera,
|
|
CameraTimeoutStartFunc start_func,
|
|
CameraTimeoutStopFunc stop_func,
|
|
void *data);
|
|
int gp_camera_start_timeout (Camera *camera, unsigned int timeout,
|
|
CameraTimeoutFunc func);
|
|
void gp_camera_stop_timeout (Camera *camera, unsigned int id);
|
|
|
|
/**@}*/
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* __cplusplus */
|
|
|
|
|
|
#endif /* !defined(LIBGPHOTO2_GPHOTO2_CAMERA_H) */
|