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
30extern "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 */
44typedef 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
58extern "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 */
68typedef 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 */
79typedef 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 */
90typedef 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 * This functionality is still in development and might change.
102 *
103 */
104typedef enum {
105 GP_EVENT_UNKNOWN, /**< unknown and unhandled event */
106 GP_EVENT_TIMEOUT, /**< timeout, no arguments */
107 GP_EVENT_FILE_ADDED, /**< CameraFilePath* = file path on camfs */
108 GP_EVENT_FOLDER_ADDED, /**< CameraFilePath* = folder on camfs */
109 GP_EVENT_CAPTURE_COMPLETE /**< last capture is complete */
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 */
138typedef int (*CameraExitFunc) (Camera *camera, GPContext *context);
139/**
140 * \brief Get a configuration tree for the camera and its driver
141 *
142 * \param camera the current camera
143 * \param widget pointer to store the toplevel widget of the tree
144 * \param context the active #GPContext
145 *
146 * A camera driver can support configuration of either its own behaviour
147 * or the camera device itself. To allow a flexible driver framework,
148 * the camera driver provides a generic configuration widget tree to the
149 * frontend, which then renders it, allows user input and sends it back
150 * via the #CameraSetConfigFunc function to have the driver configure itself
151 * or the camera.
152 *
153 * If you do not have configuration ability, there is no need to specify this
154 * function.
155 *
156 * \returns a gphoto error code
157 */
158typedef int (*CameraGetConfigFunc) (Camera *camera, CameraWidget **widget,
159 GPContext *context);
160/**
161 * \brief Set the configuration in the camera
162 *
163 * \param camera the current camera
164 * \param widget the configuration widget tree that was changed
165 * \param context the active #GPContext
166 *
167 * This function is called in the driver after the configuration is set.
168 * It is called directly after setting the value and might called multiple
169 * times (or never) after just one #CameraGetConfigFunc.
170 *
171 * \returns a gphoto error code
172 */
173typedef int (*CameraSetConfigFunc) (Camera *camera, CameraWidget *widget,
174 GPContext *context);
175typedef int (*CameraCaptureFunc) (Camera *camera, CameraCaptureType type,
176 CameraFilePath *path, GPContext *context);
177typedef int (*CameraTriggerCaptureFunc) (Camera *camera, GPContext *context);
178typedef int (*CameraCapturePreviewFunc) (Camera *camera, CameraFile *file,
179 GPContext *context);
180typedef int (*CameraSummaryFunc) (Camera *camera, CameraText *text,
181 GPContext *context);
182typedef int (*CameraManualFunc) (Camera *camera, CameraText *text,
183 GPContext *context);
184typedef int (*CameraAboutFunc) (Camera *camera, CameraText *text,
185 GPContext *context);
186typedef int (*CameraWaitForEvent) (Camera *camera, int timeout,
187 CameraEventType *eventtype, void **eventdata,
188 GPContext *context);
189/**@}*/
190
191
192/**
193 * \param camera a \ref Camera object
194 * \param context a \ref GPContext object
195 * \return a gphoto2 error code
196 *
197 * Implement this function in the camera driver if the camera needs to
198 * be initialized before or reset the after each access from
199 * libgphoto2.
200 *
201 * For example, you would probably set the speed to the highest one
202 * right before downloading an image, and reset it to the default speed
203 * afterwards so that other programs will not be affected by this speed
204 * change.
205 */
206typedef int (*CameraPrePostFunc) (Camera *camera, GPContext *context);
207
208/**
209 * \brief Various camera specific functions.
210 *
211 * This structure contains various pointers to functions that apply to
212 * the camera itself, and not the filesystem (which is handled by the
213 * filesystem functions). Set the ones you want to provide, leave the rest
214 * unset.
215 *
216 * This structure should only used by the driver itself, the frontend
217 * should use the gp_camera_xxx wrapper functions for it, who handle
218 * opening and locking around those hooks.
219 */
220typedef struct _CameraFunctions {
221 CameraPrePostFunc pre_func; /**< \brief Function called before each camera operation. */
222 CameraPrePostFunc post_func; /**< \brief Function called after each camera operation. */
223
224 CameraExitFunc exit; /**< \brief Function called on closing the camera. */
225
226 /* Configuration */
227 CameraGetConfigFunc get_config; /**< \brief Called for requesting the configuration widgets. */
228 CameraSetConfigFunc set_config; /**< \brief Called after a configuration was changed */
229
230 /* Capturing */
231 CameraCaptureFunc capture; /**< \brief Remote control the camera to capture */
232 CameraTriggerCaptureFunc trigger_capture;/**< \brief Remote control the camera to trigger capture */
233 CameraCapturePreviewFunc capture_preview;/**< \brief Preview viewfinder content. */
234
235 /* Textual information */
236 CameraSummaryFunc summary; /**< \brief Give a summary about the current camera status, translated. */
237 CameraManualFunc manual; /**< \brief Give a brief manual about any specific items a user has to know, translated. */
238 CameraAboutFunc about; /**< \brief A little About text, including authors and credits. */
239
240 /* Event Interface */
241 CameraWaitForEvent wait_for_event; /**< \brief Wait for a specific event from the camera */
242 /* Reserved space to use in the future without changing the struct size */
243 void *reserved1; /**< \brief reserved for future use */
244 void *reserved2; /**< \brief reserved for future use */
245 void *reserved3; /**< \brief reserved for future use */
246 void *reserved4; /**< \brief reserved for future use */
247 void *reserved5; /**< \brief reserved for future use */
248 void *reserved6; /**< \brief reserved for future use */
249 void *reserved7; /**< \brief reserved for future use */
250 void *reserved8; /**< \brief reserved for future use */
251} CameraFunctions;
252
253typedef struct _CameraPrivateLibrary CameraPrivateLibrary;
254typedef struct _CameraPrivateCore CameraPrivateCore;
255
256struct _Camera {
257
258 /** \name Those should be accessed only by the camera driver.
259 * @{ */
260 GPPort *port;
261 CameraFilesystem *fs;
262 CameraFunctions *functions;
263 /**@}*/
264
265 CameraPrivateLibrary *pl; /**< Private data of camera libraries. */
266 CameraPrivateCore *pc; /**< Private data of the core of gphoto2. */
267};
268
269
270/** Create a new camera device. */
271int gp_camera_new (Camera **camera);
272
273
274/** \name Preparing initialization
275 * @{
276 */
277int gp_camera_set_abilities (Camera *camera, CameraAbilities abilities);
278int gp_camera_get_abilities (Camera *camera, CameraAbilities *abilities);
279int gp_camera_set_port_info (Camera *camera, GPPortInfo info);
280int gp_camera_get_port_info (Camera *camera, GPPortInfo *info);
281
282/**@}*/
283
284
285/**
286 * \name camera speed
287 *
288 * You normally don't use that. If you do, you prevent the camera driver
289 * from selecting the optimal speed.
290 *
291 * @{
292 */
293int gp_camera_set_port_speed (Camera *camera, int speed);
294int gp_camera_get_port_speed (Camera *camera);
295
296/**@}*/
297
298
299/** \name Initialization
300 * @{
301 */
302int gp_camera_autodetect (CameraList *list, GPContext *context);
303int gp_camera_init (Camera *camera, GPContext *context);
304int gp_camera_exit (Camera *camera, GPContext *context);
305
306/**@}*/
307
308
309
310/** \name Operations on cameras
311 * @{
312 */
313int gp_camera_ref (Camera *camera);
314int gp_camera_unref (Camera *camera);
315int gp_camera_free (Camera *camera);
316
317int gp_camera_get_config (Camera *camera, CameraWidget **window,
318 GPContext *context);
319int gp_camera_set_config (Camera *camera, CameraWidget *window,
320 GPContext *context);
321int gp_camera_get_summary (Camera *camera, CameraText *summary,
322 GPContext *context);
323int gp_camera_get_manual (Camera *camera, CameraText *manual,
324 GPContext *context);
325int gp_camera_get_about (Camera *camera, CameraText *about,
326 GPContext *context);
327int gp_camera_capture (Camera *camera, CameraCaptureType type,
328 CameraFilePath *path, GPContext *context);
329int gp_camera_trigger_capture (Camera *camera, GPContext *context);
330int gp_camera_capture_preview (Camera *camera, CameraFile *file,
331 GPContext *context);
332int gp_camera_wait_for_event (Camera *camera, int timeout,
333 CameraEventType *eventtype, void **eventdata,
334 GPContext *context);
335
336int gp_camera_get_storageinfo (Camera *camera, CameraStorageInformation**,
337 int *, GPContext *context);
338
339/**@}*/
340
341
342/** \name Operations on folders
343 * @{
344 */
345int gp_camera_folder_list_files (Camera *camera, const char *folder,
346 CameraList *list, GPContext *context);
347int gp_camera_folder_list_folders (Camera *camera, const char *folder,
348 CameraList *list, GPContext *context);
349int gp_camera_folder_delete_all (Camera *camera, const char *folder,
350 GPContext *context);
351int gp_camera_folder_put_file (Camera *camera,
352 const char *folder, const char *filename,
353 CameraFileType type,
354 CameraFile *file, GPContext *context);
355int gp_camera_folder_make_dir (Camera *camera, const char *folder,
356 const char *name, GPContext *context);
357int gp_camera_folder_remove_dir (Camera *camera, const char *folder,
358 const char *name, GPContext *context);
359/**@}*/
360
361
362/** \name Operations on files
363 * @{
364 */
365int gp_camera_file_get_info (Camera *camera, const char *folder,
366 const char *file, CameraFileInfo *info,
367 GPContext *context);
368int gp_camera_file_set_info (Camera *camera, const char *folder,
369 const char *file, CameraFileInfo info,
370 GPContext *context);
371int gp_camera_file_get (Camera *camera, const char *folder,
372 const char *file, CameraFileType type,
373 CameraFile *camera_file, GPContext *context);
374int gp_camera_file_read (Camera *camera, const char *folder, const char *file,
375 CameraFileType type,
376 uint64_t offset, char *buf, uint64_t *size,
377 GPContext *context);
378int gp_camera_file_delete (Camera *camera, const char *folder,
379 const char *file, GPContext *context);
380/**@}*/
381
382
383/**
384 * \name Some cameras need 'keep-alive-messages'.
385 * @{
386 */
387typedef int (* CameraTimeoutFunc) (Camera *camera,
388 GPContext *context);
389typedef unsigned int (* CameraTimeoutStartFunc) (Camera *camera,
390 unsigned int timeout,
391 CameraTimeoutFunc func,
392 void *data);
393typedef void (* CameraTimeoutStopFunc) (Camera *camera,
394 unsigned int id, void *data);
395void gp_camera_set_timeout_funcs (Camera *camera,
396 CameraTimeoutStartFunc start_func,
397 CameraTimeoutStopFunc stop_func,
398 void *data);
399int gp_camera_start_timeout (Camera *camera, unsigned int timeout,
400 CameraTimeoutFunc func);
401void gp_camera_stop_timeout (Camera *camera, unsigned int id);
402
403/**@}*/
404#ifdef __cplusplus
405}
406#endif /* __cplusplus */
407
408
409#endif /* __GPHOTO2_CAMERA_H__ */
410