Logo Search packages:      
Sourcecode: libgphoto2 version File versions  Download package

gphoto2-camera.h

Go to the documentation of this file.
/** \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., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#ifndef __GPHOTO2_CAMERA_H__
#define __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.
 */
00044 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.
 */
00068 typedef struct {
00069       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.
 */
00079 typedef struct {
00080       char name [128];  /**< \brief Name of the captured file. */
00081       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.
 */
00090 typedef enum {
00091       GP_CAPTURE_IMAGE, /**< \brief Capture an image. */
00092       GP_CAPTURE_MOVIE, /**< \brief Capture a movie. */
00093       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.
 * This functionality is still in development and might change.
 *
 */
00104 typedef enum {
00105       GP_EVENT_UNKNOWN, /**< unknown and unhandled event */
00106       GP_EVENT_TIMEOUT, /**< timeout, no arguments */
00107       GP_EVENT_FILE_ADDED,    /**< CameraFilePath* = file path on camfs */
00108       GP_EVENT_FOLDER_ADDED,  /**< CameraFilePath* = folder on camfs */
00109       GP_EVENT_CAPTURE_COMPLETE     /**< last capture is complete */
} 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 
 */
00138 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
 */
00158 typedef int (*CameraGetConfigFunc) (Camera *camera, CameraWidget **widget,
                            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
 */
00173 typedef int (*CameraSetConfigFunc) (Camera *camera, CameraWidget  *widget,
                            GPContext *context);
typedef int (*CameraCaptureFunc)   (Camera *camera, CameraCaptureType type,
                            CameraFilePath *path, 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.
 */
00205 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.
 */
00219 typedef struct _CameraFunctions {
00220       CameraPrePostFunc pre_func;   /**< \brief Function called before each camera operation. */
00221       CameraPrePostFunc post_func;  /**< \brief Function called after each camera operation. */

00223       CameraExitFunc exit;          /**< \brief Function called on closing the camera. */

      /* Configuration */
00226       CameraGetConfigFunc       get_config;     /**< \brief Called for requesting the configuration widgets. */
00227       CameraSetConfigFunc       set_config;     /**< \brief Called after a configuration was changed */

      /* Capturing */
00230       CameraCaptureFunc        capture;   /**< \brief Remote control the camera to capture */
00231       CameraCapturePreviewFunc capture_preview;/**< \brief Preview viewfinder content. */

      /* Textual information */
00234       CameraSummaryFunc summary;          /**< \brief Give a summary about the current camera status, translated. */
00235       CameraManualFunc  manual;           /**< \brief Give a brief manual about any specific items a user has to know, translated. */
00236       CameraAboutFunc   about;            /**< \brief A little About text, including authors and credits. */

      /* Event Interface */
00239       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 */
00242       void *reserved1;              /**< \brief reserved for future use */
00243       void *reserved2;              /**< \brief reserved for future use */
00244       void *reserved3;              /**< \brief reserved for future use */
00245       void *reserved4;              /**< \brief reserved for future use */
00246       void *reserved5;              /**< \brief reserved for future use */
00247       void *reserved6;              /**< \brief reserved for future use */
00248       void *reserved7;              /**< \brief reserved for future use */
} CameraFunctions;

/* Those are DEPRECATED */
typedef GPPort     CameraPort;
typedef GPPortInfo CameraPortInfo;

typedef struct _CameraPrivateLibrary  CameraPrivateLibrary;
typedef struct _CameraPrivateCore     CameraPrivateCore;

00258 struct _Camera {

      /** \name Those should be accessed only by the camera driver.
       * @{ */
      GPPort           *port;
      CameraFilesystem *fs;
      CameraFunctions  *functions;
      /**@}*/

00267       CameraPrivateLibrary  *pl; /**< Private data of camera libraries.    */
00268       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_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_set_config       (Camera *camera, CameraWidget  *window,
                          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_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,
                           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_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 /* __GPHOTO2_CAMERA_H__ */

Generated by  Doxygen 1.6.0   Back to index