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 | * This functionality is still in development and might change. |
102 | * |
103 | */ |
104 | typedef 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 | */ |
138 | typedef 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 | */ |
158 | typedef 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 | */ |
173 | typedef int (*CameraSetConfigFunc) (Camera *camera, CameraWidget *widget, |
174 | GPContext *context); |
175 | typedef int (*CameraCaptureFunc) (Camera *camera, CameraCaptureType type, |
176 | CameraFilePath *path, GPContext *context); |
177 | typedef int (*CameraTriggerCaptureFunc) (Camera *camera, GPContext *context); |
178 | typedef int (*CameraCapturePreviewFunc) (Camera *camera, CameraFile *file, |
179 | GPContext *context); |
180 | typedef int (*CameraSummaryFunc) (Camera *camera, CameraText *text, |
181 | GPContext *context); |
182 | typedef int (*CameraManualFunc) (Camera *camera, CameraText *text, |
183 | GPContext *context); |
184 | typedef int (*CameraAboutFunc) (Camera *camera, CameraText *text, |
185 | GPContext *context); |
186 | typedef 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 | */ |
206 | typedef 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 | */ |
220 | typedef 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 | |
253 | typedef struct _CameraPrivateLibrary CameraPrivateLibrary; |
254 | typedef struct _CameraPrivateCore CameraPrivateCore; |
255 | |
256 | struct _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. */ |
271 | int gp_camera_new (Camera **camera); |
272 | |
273 | |
274 | /** \name Preparing initialization |
275 | * @{ |
276 | */ |
277 | int gp_camera_set_abilities (Camera *camera, CameraAbilities abilities); |
278 | int gp_camera_get_abilities (Camera *camera, CameraAbilities *abilities); |
279 | int gp_camera_set_port_info (Camera *camera, GPPortInfo info); |
280 | int 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 | */ |
293 | int gp_camera_set_port_speed (Camera *camera, int speed); |
294 | int gp_camera_get_port_speed (Camera *camera); |
295 | |
296 | /**@}*/ |
297 | |
298 | |
299 | /** \name Initialization |
300 | * @{ |
301 | */ |
302 | int gp_camera_autodetect (CameraList *list, GPContext *context); |
303 | int gp_camera_init (Camera *camera, GPContext *context); |
304 | int gp_camera_exit (Camera *camera, GPContext *context); |
305 | |
306 | /**@}*/ |
307 | |
308 | |
309 | |
310 | /** \name Operations on cameras |
311 | * @{ |
312 | */ |
313 | int gp_camera_ref (Camera *camera); |
314 | int gp_camera_unref (Camera *camera); |
315 | int gp_camera_free (Camera *camera); |
316 | |
317 | int gp_camera_get_config (Camera *camera, CameraWidget **window, |
318 | GPContext *context); |
319 | int gp_camera_set_config (Camera *camera, CameraWidget *window, |
320 | GPContext *context); |
321 | int gp_camera_get_summary (Camera *camera, CameraText *summary, |
322 | GPContext *context); |
323 | int gp_camera_get_manual (Camera *camera, CameraText *manual, |
324 | GPContext *context); |
325 | int gp_camera_get_about (Camera *camera, CameraText *about, |
326 | GPContext *context); |
327 | int gp_camera_capture (Camera *camera, CameraCaptureType type, |
328 | CameraFilePath *path, GPContext *context); |
329 | int gp_camera_trigger_capture (Camera *camera, GPContext *context); |
330 | int gp_camera_capture_preview (Camera *camera, CameraFile *file, |
331 | GPContext *context); |
332 | int gp_camera_wait_for_event (Camera *camera, int timeout, |
333 | CameraEventType *eventtype, void **eventdata, |
334 | GPContext *context); |
335 | |
336 | int gp_camera_get_storageinfo (Camera *camera, CameraStorageInformation**, |
337 | int *, GPContext *context); |
338 | |
339 | /**@}*/ |
340 | |
341 | |
342 | /** \name Operations on folders |
343 | * @{ |
344 | */ |
345 | int gp_camera_folder_list_files (Camera *camera, const char *folder, |
346 | CameraList *list, GPContext *context); |
347 | int gp_camera_folder_list_folders (Camera *camera, const char *folder, |
348 | CameraList *list, GPContext *context); |
349 | int gp_camera_folder_delete_all (Camera *camera, const char *folder, |
350 | GPContext *context); |
351 | int gp_camera_folder_put_file (Camera *camera, |
352 | const char *folder, const char *filename, |
353 | CameraFileType type, |
354 | CameraFile *file, GPContext *context); |
355 | int gp_camera_folder_make_dir (Camera *camera, const char *folder, |
356 | const char *name, GPContext *context); |
357 | int 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 | */ |
365 | int gp_camera_file_get_info (Camera *camera, const char *folder, |
366 | const char *file, CameraFileInfo *info, |
367 | GPContext *context); |
368 | int gp_camera_file_set_info (Camera *camera, const char *folder, |
369 | const char *file, CameraFileInfo info, |
370 | GPContext *context); |
371 | int gp_camera_file_get (Camera *camera, const char *folder, |
372 | const char *file, CameraFileType type, |
373 | CameraFile *camera_file, GPContext *context); |
374 | int 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); |
378 | int 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 | */ |
387 | typedef int (* CameraTimeoutFunc) (Camera *camera, |
388 | GPContext *context); |
389 | typedef unsigned int (* CameraTimeoutStartFunc) (Camera *camera, |
390 | unsigned int timeout, |
391 | CameraTimeoutFunc func, |
392 | void *data); |
393 | typedef void (* CameraTimeoutStopFunc) (Camera *camera, |
394 | unsigned int id, void *data); |
395 | void gp_camera_set_timeout_funcs (Camera *camera, |
396 | CameraTimeoutStartFunc start_func, |
397 | CameraTimeoutStopFunc stop_func, |
398 | void *data); |
399 | int gp_camera_start_timeout (Camera *camera, unsigned int timeout, |
400 | CameraTimeoutFunc func); |
401 | void 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 | |