libgphoto2 (libgphoto2): libgphoto2/gphoto2-camera.c File Reference

- Main Page
- Data Structures
- Files
- Directories
- Related Pages

- File List
- Globals

# gphoto2-camera.c File Reference

`#include "config.h"`
`#include <gphoto2/gphoto2-camera.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <stdarg.h>`
`#include <stdio.h>`
`#include <ltdl.h>`
`#include <gphoto2/gphoto2-context.h>`
`#include <gphoto2/gphoto2-result.h>`
`#include <gphoto2/gphoto2-library.h>`
`#include <gphoto2/gphoto2-port-log.h>`

## Data Structures
struct | _CameraPrivateCore
## Defines
#define | textdomain(String) (String)
#define | gettext(String) (String)
#define | dgettext(Domain, Message) (Message)
#define | dcgettext(Domain, Message, Type) (Message)
#define | bindtextdomain(Domain, Directory) (Domain)
#define | _(String) (String)
#define | N_(String) (String)
#define | CHECK_NULL(r) {if (!(r)) return (GP_ERROR_BAD_PARAMETERS);}
#define | CAMERA_UNUSED(c, ctx)
#define | CR(c, result, ctx)
#define | CHECK_OPEN(c, ctx)
#define | CHECK_CLOSE(c, ctx)
#define | CRS(c, res, ctx)
#define | CRSL(c, res, ctx, list)
#define | CHECK_RESULT_OPEN_CLOSE(c, result, ctx)
#define | CHECK_INIT(c, ctx)
## Functions
int | gp_camera_exit (Camera *camera, GPContext *context)
int | gp_camera_new (Camera **camera)
int | gp_camera_set_abilities (Camera *camera, CameraAbilities abilities)
int | gp_camera_get_abilities (Camera *camera, CameraAbilities *abilities)
int | gp_camera_get_port_info (Camera *camera, GPPortInfo *info)
int | gp_camera_set_port_info (Camera *camera, GPPortInfo info)
int | gp_camera_set_port_speed (Camera *camera, int speed)
int | gp_camera_get_port_speed (Camera *camera)
int | gp_camera_ref (Camera *camera)
int | gp_camera_unref (Camera *camera)
int | gp_camera_free (Camera *camera)
int | gp_camera_init (Camera *camera, GPContext *context)
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_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_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)
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)
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)

## Detailed Description

Implement Camera object representing a camera attached to the system.

Author:
  Copyright 2000 Scott Fritzinger

  Copyright 2001-2002 Lutz Müller <lutz@users.sf.net>

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.

  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.

  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.

## Define Documentation

#define CAMERA_UNUSED | ( | c,
|  | ctx |  | ) |

Value:

    {                                                                       \
            (c)->pc->used--;                                                \
            if (!(c)->pc->used) {                                           \
                    if ((c)->pc->exit_requested)                            \
                            gp_camera_exit ((c), (ctx));                    \
                    if (!(c)->pc->ref_count)                                \
                            gp_camera_free (c);                             \
            }                                                               \
    }

#define CHECK_CLOSE | ( | c,
|  | ctx |  | ) |

Value:

    {                                                                       \
            int r;                                                          \
                                                                            \
            if ((c)->functions->post_func) {                                \
                    r = (c)->functions->post_func (c,ctx);                  \
                    if (r < 0) {                                            \
                            CAMERA_UNUSED (c,ctx);                          \
                            return (r);                                     \
                    }                                                       \
            }                                                               \
    }

#define CHECK_INIT | ( | c,
|  | ctx |  | ) |

Value:

    {                                                                       \
            if ((c)->pc->used)                                              \
                    return (GP_ERROR_CAMERA_BUSY);                          \
            (c)->pc->used++;                                                \
            if (!(c)->pc->lh)                                               \
                    CR((c), gp_camera_init (c, ctx), ctx);                  \
    }

#define CHECK_OPEN | ( | c,
|  | ctx |  | ) |

Value:

    {                                                                       \
            int r;                                                          \
                                                                            \
            if ((c)->functions->pre_func) {                                 \
                    r = (c)->functions->pre_func (c,ctx);                   \
                    if (r < 0) {                                            \
                            CAMERA_UNUSED (c,ctx);                          \
                            return (r);                                     \
                    }                                                       \
            }                                                               \
    }

#define CHECK_RESULT_OPEN_CLOSE | ( | c,
|  | result,
|  | ctx |  | ) |

Value:

    {                                                                       \
            int r;                                                          \
                                                                            \
            CHECK_OPEN (c,ctx);                                             \
            r = (result);                                                   \
            if (r < 0) {                                                    \
                    CHECK_CLOSE (c,ctx);                                    \
                    gp_log (GP_LOG_DEBUG, "gphoto2-camera", "Operation failed!");\
                    CAMERA_UNUSED (c,ctx);                                  \
                    return (r);                                             \
            }                                                               \
            CHECK_CLOSE (c,ctx);                                            \
    }

#define CR | ( | c,
|  | result,
|  | ctx |  | ) |

Value:

    {                                                                       \
            int r = (result);                                               \
                                                                            \
            if (r < 0) {                                                    \
                                                                            \
                    /* libgphoto2_port doesn't have a GPContext */          \
                    if (r > -100)                                           \
                            gp_context_error ((ctx), _("An error occurred " \
                                    "in the io-library ('%s'): %s"),        \
                                    gp_port_result_as_string (r),           \
                                    (c) ? gp_port_get_error ((c)->port) :   \
                                          _("No additional information "    \
                                          "available."));                   \
                    if (c)                                                  \
                            CAMERA_UNUSED((c),(ctx));                       \
                    return (r);                                             \
            }                                                               \
    }

#define CRS | ( | c,
|  | res,
|  | ctx |  | ) |

Value:

    {                                                                       \
            int r = (res);                                                  \
                                                                            \
            if (r < 0) {                                                    \
                    CAMERA_UNUSED (c,ctx);                                  \
                    return (r);                                             \
            }                                                               \
    }

#define CRSL | ( | c,
|  | res,
|  | ctx,
|  | list |  | ) |

Value:

    {                                                                       \
            int r = (res);                                                  \
                                                                            \
            if (r < 0) {                                                    \
                    CAMERA_UNUSED (c,ctx);                                  \
                    gp_list_free (list);                                    \
                    return (r);                                             \
            }                                                               \
    }

## Function Documentation

int gp_camera_capture | ( | Camera * | camera,
|  | CameraCaptureType | type,
|  | CameraFilePath * | path,
|  | GPContext * | context |
| ) |  |  |

Captures an image, movie, or sound clip depending on the given `type`.

Parameters:

  | camera | a Camera
  | type | a CameraCaptureType
  | path | a CameraFilePath
  | context | a GPContext

Returns:
  a gphoto2 error code

The resulting file will be stored on the camera. The location gets stored in `path`. The file can then be downloaded using gp_camera_file_get.

int gp_camera_capture_preview | ( | Camera * | camera,
|  | CameraFile * | file,
|  | GPContext * | context |
| ) |  |  |

Captures a preview that won't be stored on the camera but returned in supplied file.

Parameters:

  | camera | a Camera
  | file | a CameraFile
  | context | a GPContext

Returns:
  a gphoto2 error code

For example, you could use gp_capture_preview for taking some sample pictures before calling gp_capture.

int gp_camera_exit | ( | Camera * | camera,
|  | GPContext * | context |
| ) |  |  |

Close connection to camera.

Parameters:

  | camera | a Camera object
  | context | a GPContext object

Returns:
  a gphoto2 error code.

Closes a connection to the camera and therefore gives other application the possibility to access the camera, too.

It is recommended that you call this function when you currently don't need the camera. The camera will get reinitialized by gp_camera_init() automatically if you try to access the camera again.

int gp_camera_file_delete | ( | Camera * | camera,
|  | const char * | folder,
|  | const char * | file,
|  | GPContext * | context |
| ) |  |  |

Deletes the file from `` .

Parameters:

  | camera | a Camera
  | folder | a folder
  | file | the name of a file
  | context | a GPContext

Returns:
  a gphoto2 error code

int gp_camera_file_get | ( | Camera * | camera,
|  | const char * | folder,
|  | const char * | file,
|  | CameraFileType | type,
|  | CameraFile * | camera_file,
|  | GPContext * | context |
| ) |  |  |

Retrieves a file from the Camera.

Parameters:

  | camera | a Camera
  | folder | a folder
  | file | the name of a file
  | type | the CameraFileType
  | camera_file | a CameraFile
  | context | a GPContext

Returns:
  a gphoto2 error code

int gp_camera_file_get_info | ( | Camera * | camera,
|  | const char * | folder,
|  | const char * | file,
|  | CameraFileInfo * | info,
|  | GPContext * | context |
| ) |  |  |

Retrieves information about a file.

Parameters:

  | camera | a Camera
  | folder | a folder
  | file | the name of the file
  | info |
  | context | a GPContext

Returns:
  a gphoto2 error code

int gp_camera_file_set_info | ( | Camera * | camera,
|  | const char * | folder,
|  | const char * | file,
|  | CameraFileInfo | info,
|  | GPContext * | context |
| ) |  |  |

Sets some file properties like name or permissions.

Parameters:

  | camera | a Camera
  | folder | a folder
  | file | the name of a file
  | info | the CameraFileInfo
  | context | a GPContext

Returns:
  a gphoto2 error code

int gp_camera_folder_delete_all | ( | Camera * | camera,
|  | const char * | folder,
|  | GPContext * | context |
| ) |  |  |

Deletes all files in a given `folder`.

Parameters:

  | camera | a Camera
  | folder | a folder
  | context | a GPContext

Returns:
  a gphoto2 error code

int gp_camera_folder_list_files | ( | Camera * | camera,
|  | const char * | folder,
|  | CameraList * | list,
|  | GPContext * | context |
| ) |  |  |

Lists the files in supplied `folder`.

Parameters:

  | camera | a Camera
  | folder | a folder
  | list | a CameraList
  | context | a GPContext

Returns:
  a gphoto2 error code

int gp_camera_folder_list_folders | ( | Camera * | camera,
|  | const char * | folder,
|  | CameraList * | list,
|  | GPContext * | context |
| ) |  |  |

Lists the folders in supplied `folder`.

Parameters:

  | camera | a Camera
  | folder | a folder
  | list | a CameraList
  | context | a GPContext

Returns:
  a gphoto2 error code

int gp_camera_folder_make_dir | ( | Camera * | camera,
|  | const char * | folder,
|  | const char * | name,
|  | GPContext * | context |
| ) |  |  |

Creates a new directory called `name` in the given `folder`.

Parameters:

  | camera | a Camera
  | folder | the location where to create the new directory
  | name | the name of the directory to be created
  | context | a GPContext

Returns:
  a gphoto2 error code

int gp_camera_folder_put_file | ( | Camera * | camera,
|  | const char * | folder,
|  | CameraFile * | file,
|  | GPContext * | context |
| ) |  |  |

Uploads a file into given `folder`.

Parameters:

  | camera | a Camera
  | folder | a folder
  | file | a CameraFile
  | context | a GPContext

Returns:
  a gphoto2 error code

int gp_camera_folder_remove_dir | ( | Camera * | camera,
|  | const char * | folder,
|  | const char * | name,
|  | GPContext * | context |
| ) |  |  |

Removes an (empty) directory called `name` from the given `folder`.

Parameters:

  | camera | a Camera
  | folder | the folder from which to remove the directory
  | name | the name of the directory to be removed
  | context | a GPContext

Returns:
  a gphoto2 error code

int gp_camera_free | ( | Camera * | camera | ) |

Free the `camera`.

Parameters:

  | camera | a Camera

Returns:
  a gphoto2 error code

Deprecated:
  This function should never be used. Please use gp_camera_unref instead.

int gp_camera_get_abilities | ( | Camera * | camera,
|  | CameraAbilities * | abilities |
| ) |  |  |

Retrieve the `abilities` of the `camera`.

Parameters:

  | camera | a Camera
  | abilities |

Returns:
  a gphoto2 error code

int gp_camera_get_about | ( | Camera * | camera,
|  | CameraText * | about,
|  | GPContext * | context |
| ) |  |  |

Retrieves information about the camera driver.

Parameters:

  | camera | a Camera
  | about | a CameraText
  | context | a GPContext

Returns:
  a gphoto2 error code

Typically, this information contains name and address of the author, acknowledgements, etc.

int gp_camera_get_config | ( | Camera * | camera,
|  | CameraWidget ** | window,
|  | GPContext * | context |
| ) |  |  |

Retrieve a configuration `window` for the `camera`.

Parameters:

  | camera | a Camera
  | window | a CameraWidget
  | context | a GPContext

Returns:
  gphoto2 error code

This `window` can be used for construction of a configuration dialog.

int gp_camera_get_manual | ( | Camera * | camera,
|  | CameraText * | manual,
|  | GPContext * | context |
| ) |  |  |

Retrieves the `manual` for given `camera`.

Parameters:

  | camera | a Camera
  | manual | a CameraText
  | context | a GPContext

Returns:
  a gphoto2 error code

This manual typically contains information about using the camera.

int gp_camera_get_port_speed | ( | Camera * | camera | ) |

Retrieve the current speed.

Parameters:

  | camera | a Camera

Returns:
  The current speed or a gphoto2 error code

int gp_camera_get_summary | ( | Camera * | camera,
|  | CameraText * | summary,
|  | GPContext * | context |
| ) |  |  |

Retrieves a camera summary.

Parameters:

  | camera | a Camera
  | summary | a CameraText
  | context | a GPContext

Returns:
  a gphoto2 error code

This summary typically contains information like manufacturer, pictures taken, or generally information that is not configurable.

int gp_camera_init | ( | Camera * | camera,
|  | GPContext * | context |
| ) |  |  |

Initiate a connection to the `camera`.

Parameters:

  | camera | a Camera
  | context | a GPContext

Returns:
  a gphoto2 error code

Before calling this function, the `camera` should be set up using gp_camera_set_port_path or gp_camera_set_port_name and gp_camera_set_abilities. If that has been omitted, gphoto2 tries to autodetect any cameras and chooses the first one if any cameras are found. It is generally a good idea to call gp_camera_exit after transactions have been completed in order to give other applications the chance to access the camera, too.

int gp_camera_new | ( | Camera ** | camera | ) |

Allocates the memory for a Camera.

Parameters:

  | camera | the Camera object to initialize.

Returns:
  a gphoto2 error code

int gp_camera_ref | ( | Camera * | camera | ) |

Increment the reference count of a `camera`.

Parameters:

  | camera | a Camera

Returns:
  a gphoto2 error code

int gp_camera_set_abilities | ( | Camera * | camera,
|  | CameraAbilities | abilities |
| ) |  |  |

Sets the camera abilities.

Parameters:

  | camera | a Camera
  | abilities | the CameraAbilities to be set

Returns:
  a gphoto2 error code

You need to call this function before calling gp_camera_init the first time unless you want gphoto2 to autodetect cameras and choose the first detected one. By setting the `abilities`, you tell gphoto2 what model the `camera` is and what camera driver should be used for accessing the `camera`. You can get `abilities` by calling gp_abilities_list_get_abilities.

int gp_camera_set_config | ( | Camera * | camera,
|  | CameraWidget * | window,
|  | GPContext * | context |
| ) |  |  |

Sets the configuration.

Parameters:

  | camera | a Camera
  | window | a CameraWidget
  | context | a GPContext

Returns:
  a gphoto2 error code

Typically, a `window` is retrieved using gp_camera_get_config and passed to this function in order to adjust the settings on the camera.

int gp_camera_set_port_speed | ( | Camera * | camera,
|  | int | speed |
| ) |  |  |

Set the camera speed.

Parameters:

  | camera | a Camera
  | speed | the speed

Returns:
  a gphoto2 error code

This function is typically used prior first initialization using gp_camera_init for debugging purposes. Normally, a camera driver will try to figure out the current speed of the camera and set the speed to the optimal one automatically. Note that this function only works with serial ports. In other words, you have to set the camera's port to a serial one (using gp_camera_set_port_path or gp_camera_set_port_name) prior calling this function.

void gp_camera_set_timeout_funcs | ( | Camera * | camera,
|  | CameraTimeoutStartFunc | start_func,
|  | CameraTimeoutStopFunc | stop_func,
|  | void * | data |
| ) |  |  |

Parameters:

  | camera | a Camera
  | start_func |
  | stop_func |
  | data |

Returns:
  a gphoto2 error code

If your frontend has something like idle loops, it is recommended you use gp_camera_set_timeout_funcs in order to give the camera driver the possibility to keep up the connection to the camera.

int gp_camera_start_timeout | ( | Camera * | camera,
|  | unsigned int | timeout,
|  | CameraTimeoutFunc | func |
| ) |  |  |

Parameters:

  | camera | a Camera
  | timeout | number of seconds that should pass between each call to `func`
  | func | the function that should be called each `timeout` seconds

Returns:
  The id of the background process or a gphoto2 error code

This function should be called by the camera driver during camera_init() if the camera needs to be sent messages periodically in order to prevent it from shutting down.

void gp_camera_stop_timeout | ( | Camera * | camera,
|  | unsigned int | id |
| ) |  |  |

Stop periodic calls to keepalive function.

Parameters:

  | camera | a Camera
  | id | the id of the background process previously returned by gp_camera_start_timeout

Call this function in the camera driver if you want to stop a periodic call to a function that has been started using gp_camera_start_timeout.

int gp_camera_unref | ( | Camera * | camera | ) |

Decrements the reference count of a Camera.

Parameters:

  | camera | a Camera

Returns:
  a gphoto2 error code

If the reference count reaches 0, the `camera` will be freed automatically.

int gp_camera_wait_for_event | ( | Camera * | camera,
|  | int | timeout,
|  | CameraEventType * | eventtype,
|  | void ** | eventdata,
|  | GPContext * | context |
| ) |  |  |

Wait for an event from the camera.

Parameters:

  | camera | a Camera
  | timeout | amount of time to wait in 1/1000 seconds
  | eventtype | received CameraEventType [out]
  | eventdata | received event specific data [out]
  | context | a GPContext

Returns:
  gphoto2 error code

This function blocks and waits for an event to come from the camera. If timeout occurs before an event is received then *eventtype==GP_EVENT_TIMEOUT and eventdata is left unchanged. If an event is received then eventtype is set to the type of event, and eventdata is set to event specific data. See the CameraEventType enum to see which eventtype's match to which types of eventdata.