1 /** \file 2 * 3 * \brief Implement Camera object representing a camera attached to the system. 4 * 5 * \author Copyright 2000 Scott Fritzinger 6 * 7 * \note 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2 of the License, or (at your option) any later version. 12 * 13 * \note 14 * This library is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * Lesser General Public License for more details. 18 * 19 * \note 20 * You should have received a copy of the GNU Lesser General Public 21 * License along with this library; if not, write to the 22 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 23 * Boston, MA 02110-1301 USA 24 */ 25 26 #ifndef __GPHOTO2_CAMERA_H__ 27 #define __GPHOTO2_CAMERA_H__ 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif /* __cplusplus */ 32 33 /** 34 * \brief Object representing a camera attached to the system. 35 * 36 * A Camera object represents a specific instance of a (physical of 37 * virtual) camera attached to the system. 38 * 39 * The abilities of this type of camera are stored in a CameraAbility 40 * object. 41 * 42 * The details of the Camera object are internal. 43 */ 44 typedef struct _Camera Camera; 45 #ifdef __cplusplus 46 } 47 #endif /* __cplusplus */ 48 49 50 #include <gphoto2/gphoto2-abilities-list.h> 51 #include <gphoto2/gphoto2-port.h> 52 53 #include <gphoto2/gphoto2-widget.h> 54 #include <gphoto2/gphoto2-filesys.h> 55 #include <gphoto2/gphoto2-result.h> 56 57 #ifdef __cplusplus 58 extern "C" { 59 #endif /* __cplusplus */ 60 61 /** 62 * \brief CameraText structure used in various functions. 63 * 64 * A text structure containing translated text returned 65 * by various functions (about, manual, summary). You should 66 * not assume a size. 67 */ 68 typedef struct { 69 char text [32 * 1024]; /**< \brief Character string containing the translated text. */ 70 } CameraText; 71 72 /** 73 * \brief A structure created by the capture operation. 74 * 75 * A structure containing the folder and filename of an object 76 * after a successful capture and is passed as reference to the 77 * gp_camera_capture() function. 78 */ 79 typedef struct { 80 char name [128]; /**< \brief Name of the captured file. */ 81 char folder [1024]; /**< \brief Name of the folder of the captured file. */ 82 } CameraFilePath; 83 84 /** 85 * \brief Type of the capture to do. 86 * 87 * Specifies the type of capture the user wants to do with the 88 * gp_camera_capture() function. 89 */ 90 typedef enum { 91 GP_CAPTURE_IMAGE, /**< \brief Capture an image. */ 92 GP_CAPTURE_MOVIE, /**< \brief Capture a movie. */ 93 GP_CAPTURE_SOUND /**< \brief Capture audio. */ 94 } CameraCaptureType; 95 96 /** 97 * \brief Specify what event we received from the camera. 98 * 99 * Used by gp_camera_wait_for_event() to specify what 100 * event happened on the camera. 101 * 102 */ 103 typedef enum { 104 GP_EVENT_UNKNOWN, /**< unknown and unhandled event. argument is a char* or NULL */ 105 GP_EVENT_TIMEOUT, /**< timeout, no arguments */ 106 GP_EVENT_FILE_ADDED, /**< CameraFilePath* = file path on camfs */ 107 GP_EVENT_FOLDER_ADDED, /**< CameraFilePath* = folder on camfs */ 108 GP_EVENT_CAPTURE_COMPLETE, /**< last capture is complete */ 109 GP_EVENT_FILE_CHANGED /**< CameraFilePath* = file path on camfs */ 110 } CameraEventType; 111 112 /** 113 * \name Camera object member functions 114 * 115 * These functions must be implemented by a camlib and the camlib's 116 * camera_init() function will add them to a Camera object. 117 * 118 * @{ 119 */ 120 /** 121 * \brief The camera exit function 122 * 123 * \param camera the current camera 124 * \param context a #GPContext 125 * 126 * This functions is called in the camera driver for closing the camera 127 * connection. It should do the necessary cleanups of the internal camera 128 * state, free allocated private structures and similar. 129 * 130 * The driver does not need to close the #GPPort, this is done by libgphoto2 131 * itself. 132 * 133 * Implement this function if you need to any of this stuff, otherwise leave 134 * it out. 135 * 136 * \returns a gphoto error code 137 */ 138 typedef int (*CameraExitFunc) (Camera *camera, GPContext *context); 139 140 /** 141 * \brief Get a configuration tree for the camera and its driver 142 * 143 * \param camera the current camera 144 * \param widget pointer to store the toplevel widget of the tree 145 * \param context the active #GPContext 146 * 147 * A camera driver can support configuration of either its own behaviour 148 * or the camera device itself. To allow a flexible driver framework, 149 * the camera driver provides a generic configuration widget tree to the 150 * frontend, which then renders it, allows user input and sends it back 151 * via the #CameraSetConfigFunc function to have the driver configure itself 152 * or the camera. 153 * 154 * If you do not have configuration ability, there is no need to specify this 155 * function. 156 * 157 * \returns a gphoto error code 158 */ 159 typedef int (*CameraGetConfigFunc) (Camera *camera, CameraWidget **widget, 160 GPContext *context); 161 /** 162 * \brief Get a configuration widget for a specific configuration 163 * 164 * \param camera the current camera 165 * \param name the name of the widget 166 * \param widget pointer to store the toplevel widget of the tree 167 * \param context the active #GPContext 168 * 169 * A camera driver can support configuration of either its own behaviour 170 * or the camera device itself. To allow a flexible driver framework, 171 * the camera driver provides a generic configuration widget tree to the 172 * frontend, which then renders it, allows user input and sends it back 173 * via the #CameraSetConfigFunc function to have the driver configure itself 174 * or the camera. 175 * 176 * This specific function retrieves one specific named entry, and not the full 177 * tree to allow for querying specific settings faster. 178 * 179 * If you do not have configuration ability, there is no need to specify this 180 * function. 181 * 182 * \returns a gphoto error code 183 */ 184 typedef int (*CameraGetSingleConfigFunc) (Camera *camera, const char *name, CameraWidget **widget, 185 GPContext *context); 186 /** 187 * \brief List all configuration widgets for a specific configuration 188 * 189 * \param camera the current camera 190 * \param list the list of widgets available 191 * \param context the active #GPContext 192 * 193 * A camera driver can support configuration of either its own behaviour 194 * or the camera device itself. To allow a flexible driver framework, 195 * the camera driver provides a generic configuration widget tree to the 196 * frontend, which then renders it, allows user input and sends it back 197 * via the #CameraSetConfigFunc function to have the driver configure itself 198 * or the camera. 199 * 200 * This specific function retrieves all the available configuration values in a flat list. 201 * 202 * This is different than the GetConfigFunc, which returns a configuration tree. 203 * 204 * If you do not have configuration ability, there is no need to specify this 205 * function. 206 * 207 * \returns a gphoto error code 208 */ 209 typedef int (*CameraListConfigFunc) (Camera *camera, CameraList *list, GPContext *context); 210 /** 211 * \brief Set the configuration in the camera 212 * 213 * \param camera the current camera 214 * \param widget the configuration widget tree that was changed 215 * \param context the active #GPContext 216 * 217 * This function is called in the driver after the configuration is set. 218 * It is called directly after setting the value and might called multiple 219 * times (or never) after just one #CameraGetConfigFunc. 220 * 221 * \returns a gphoto error code 222 */ 223 typedef int (*CameraSetConfigFunc) (Camera *camera, CameraWidget *widget, 224 GPContext *context); 225 /** 226 * \brief Set a single configuration variable in the camera 227 * 228 * \param camera the current camera 229 * \param name the widget to set 230 * \param widget the configuration widget tree that was changed 231 * \param context the active #GPContext 232 * 233 * This function is called in the driver after the configuration value is set. 234 * 235 * \returns a gphoto error code 236 */ 237 typedef int (*CameraSetSingleConfigFunc) (Camera *camera, const char *name, CameraWidget *widget, 238 GPContext *context); 239 240 typedef int (*CameraCaptureFunc) (Camera *camera, CameraCaptureType type, 241 CameraFilePath *path, GPContext *context); 242 typedef int (*CameraTriggerCaptureFunc) (Camera *camera, GPContext *context); 243 typedef int (*CameraCapturePreviewFunc) (Camera *camera, CameraFile *file, 244 GPContext *context); 245 typedef int (*CameraSummaryFunc) (Camera *camera, CameraText *text, 246 GPContext *context); 247 typedef int (*CameraManualFunc) (Camera *camera, CameraText *text, 248 GPContext *context); 249 typedef int (*CameraAboutFunc) (Camera *camera, CameraText *text, 250 GPContext *context); 251 typedef int (*CameraWaitForEvent) (Camera *camera, int timeout, 252 CameraEventType *eventtype, void **eventdata, 253 GPContext *context); 254 /**@}*/ 255 256 257 /** 258 * \param camera a \ref Camera object 259 * \param context a \ref GPContext object 260 * \return a gphoto2 error code 261 * 262 * Implement this function in the camera driver if the camera needs to 263 * be initialized before or reset the after each access from 264 * libgphoto2. 265 * 266 * For example, you would probably set the speed to the highest one 267 * right before downloading an image, and reset it to the default speed 268 * afterwards so that other programs will not be affected by this speed 269 * change. 270 */ 271 typedef int (*CameraPrePostFunc) (Camera *camera, GPContext *context); 272 273 /** 274 * \brief Various camera specific functions. 275 * 276 * This structure contains various pointers to functions that apply to 277 * the camera itself, and not the filesystem (which is handled by the 278 * filesystem functions). Set the ones you want to provide, leave the rest 279 * unset. 280 * 281 * This structure should only used by the driver itself, the frontend 282 * should use the gp_camera_xxx wrapper functions for it, who handle 283 * opening and locking around those hooks. 284 */ 285 typedef struct _CameraFunctions { 286 CameraPrePostFunc pre_func; /**< \brief Function called before each camera operation. */ 287 CameraPrePostFunc post_func; /**< \brief Function called after each camera operation. */ 288 289 CameraExitFunc exit; /**< \brief Function called on closing the camera. */ 290 291 /* Configuration */ 292 CameraGetConfigFunc get_config; /**< \brief Called for requesting the configuration widgets. */ 293 CameraSetConfigFunc set_config; /**< \brief Called after a configuration was changed */ 294 295 CameraListConfigFunc list_config; /**< \brief Called for listing the available configuration widgets. */ 296 CameraGetSingleConfigFunc get_single_config; /**< \brief Called for requesteing a single widget. */ 297 CameraSetSingleConfigFunc set_single_config; /**< \brief Called for setting a single configuration widget. */ 298 299 /* Capturing */ 300 CameraCaptureFunc capture; /**< \brief Remote control the camera to capture */ 301 CameraTriggerCaptureFunc trigger_capture;/**< \brief Remote control the camera to trigger capture */ 302 CameraCapturePreviewFunc capture_preview;/**< \brief Preview viewfinder content. */ 303 304 /* Textual information */ 305 CameraSummaryFunc summary; /**< \brief Give a summary about the current camera status, translated. */ 306 CameraManualFunc manual; /**< \brief Give a brief manual about any specific items a user has to know, translated. */ 307 CameraAboutFunc about; /**< \brief A little About text, including authors and credits. */ 308 309 /* Event Interface */ 310 CameraWaitForEvent wait_for_event; /**< \brief Wait for a specific event from the camera */ 311 /* Reserved space to use in the future without changing the struct size */ 312 void *reserved1; /**< \brief reserved for future use */ 313 void *reserved2; /**< \brief reserved for future use */ 314 void *reserved3; /**< \brief reserved for future use */ 315 void *reserved4; /**< \brief reserved for future use */ 316 void *reserved5; /**< \brief reserved for future use */ 317 void *reserved6; /**< \brief reserved for future use */ 318 void *reserved7; /**< \brief reserved for future use */ 319 void *reserved8; /**< \brief reserved for future use */ 320 } CameraFunctions; 321 322 typedef struct _CameraPrivateLibrary CameraPrivateLibrary; 323 typedef struct _CameraPrivateCore CameraPrivateCore; 324 325 struct _Camera { 326 327 /** \name Those should be accessed only by the camera driver. 328 * @{ */ 329 GPPort *port; 330 CameraFilesystem *fs; 331 CameraFunctions *functions; 332 /**@}*/ 333 334 CameraPrivateLibrary *pl; /**< Private data of camera libraries. */ 335 CameraPrivateCore *pc; /**< Private data of the core of gphoto2. */ 336 }; 337 338 339 /** Create a new camera device. */ 340 int gp_camera_new (Camera **camera); 341 342 343 /** \name Preparing initialization 344 * @{ 345 */ 346 int gp_camera_set_abilities (Camera *camera, CameraAbilities abilities); 347 int gp_camera_get_abilities (Camera *camera, CameraAbilities *abilities); 348 int gp_camera_set_port_info (Camera *camera, GPPortInfo info); 349 int gp_camera_get_port_info (Camera *camera, GPPortInfo *info); 350 351 /**@}*/ 352 353 354 /** 355 * \name camera speed 356 * 357 * You normally don't use that. If you do, you prevent the camera driver 358 * from selecting the optimal speed. 359 * 360 * @{ 361 */ 362 int gp_camera_set_port_speed (Camera *camera, int speed); 363 int gp_camera_get_port_speed (Camera *camera); 364 365 /**@}*/ 366 367 368 /** \name Initialization 369 * @{ 370 */ 371 int gp_camera_autodetect (CameraList *list, GPContext *context); 372 int gp_camera_init (Camera *camera, GPContext *context); 373 int gp_camera_exit (Camera *camera, GPContext *context); 374 375 /**@}*/ 376 377 378 379 /** \name Operations on cameras 380 * @{ 381 */ 382 int gp_camera_ref (Camera *camera); 383 int gp_camera_unref (Camera *camera); 384 int gp_camera_free (Camera *camera); 385 386 int gp_camera_get_config (Camera *camera, CameraWidget **window, 387 GPContext *context); 388 int gp_camera_list_config (Camera *camera, CameraList *list, 389 GPContext *context); 390 int gp_camera_get_single_config (Camera *camera, const char *name, CameraWidget **widget, 391 GPContext *context); 392 int gp_camera_set_config (Camera *camera, CameraWidget *window, 393 GPContext *context); 394 int gp_camera_set_single_config (Camera *camera, const char *name, CameraWidget *widget, 395 GPContext *context); 396 int gp_camera_get_summary (Camera *camera, CameraText *summary, 397 GPContext *context); 398 int gp_camera_get_manual (Camera *camera, CameraText *manual, 399 GPContext *context); 400 int gp_camera_get_about (Camera *camera, CameraText *about, 401 GPContext *context); 402 int gp_camera_capture (Camera *camera, CameraCaptureType type, 403 CameraFilePath *path, GPContext *context); 404 int gp_camera_trigger_capture (Camera *camera, GPContext *context); 405 int gp_camera_capture_preview (Camera *camera, CameraFile *file, 406 GPContext *context); 407 int gp_camera_wait_for_event (Camera *camera, int timeout, 408 CameraEventType *eventtype, void **eventdata, 409 GPContext *context); 410 411 int gp_camera_get_storageinfo (Camera *camera, CameraStorageInformation**, 412 int *, GPContext *context); 413 414 /**@}*/ 415 416 417 /** \name Operations on folders 418 * @{ 419 */ 420 int gp_camera_folder_list_files (Camera *camera, const char *folder, 421 CameraList *list, GPContext *context); 422 int gp_camera_folder_list_folders (Camera *camera, const char *folder, 423 CameraList *list, GPContext *context); 424 int gp_camera_folder_delete_all (Camera *camera, const char *folder, 425 GPContext *context); 426 int gp_camera_folder_put_file (Camera *camera, 427 const char *folder, const char *filename, 428 CameraFileType type, 429 CameraFile *file, GPContext *context); 430 int gp_camera_folder_make_dir (Camera *camera, const char *folder, 431 const char *name, GPContext *context); 432 int gp_camera_folder_remove_dir (Camera *camera, const char *folder, 433 const char *name, GPContext *context); 434 /**@}*/ 435 436 437 /** \name Operations on files 438 * @{ 439 */ 440 int gp_camera_file_get_info (Camera *camera, const char *folder, 441 const char *file, CameraFileInfo *info, 442 GPContext *context); 443 int gp_camera_file_set_info (Camera *camera, const char *folder, 444 const char *file, CameraFileInfo info, 445 GPContext *context); 446 int gp_camera_file_get (Camera *camera, const char *folder, 447 const char *file, CameraFileType type, 448 CameraFile *camera_file, GPContext *context); 449 int gp_camera_file_read (Camera *camera, const char *folder, const char *file, 450 CameraFileType type, 451 uint64_t offset, char *buf, uint64_t *size, 452 GPContext *context); 453 int gp_camera_file_delete (Camera *camera, const char *folder, 454 const char *file, GPContext *context); 455 /**@}*/ 456 457 458 /** 459 * \name Some cameras need 'keep-alive-messages'. 460 * @{ 461 */ 462 typedef int (* CameraTimeoutFunc) (Camera *camera, 463 GPContext *context); 464 typedef unsigned int (* CameraTimeoutStartFunc) (Camera *camera, 465 unsigned int timeout, 466 CameraTimeoutFunc func, 467 void *data); 468 typedef void (* CameraTimeoutStopFunc) (Camera *camera, 469 unsigned int id, void *data); 470 void gp_camera_set_timeout_funcs (Camera *camera, 471 CameraTimeoutStartFunc start_func, 472 CameraTimeoutStopFunc stop_func, 473 void *data); 474 int gp_camera_start_timeout (Camera *camera, unsigned int timeout, 475 CameraTimeoutFunc func); 476 void gp_camera_stop_timeout (Camera *camera, unsigned int id); 477 478 /**@}*/ 479 #ifdef __cplusplus 480 } 481 #endif /* __cplusplus */ 482 483 484 #endif /* __GPHOTO2_CAMERA_H__ */ 485