/** \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 #include #include #include #include #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) */