gphoto2-camera.h File Reference

Implement Camera object representing a camera attached to the system. More...

#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>

Include dependency graph for gphoto2-camera.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  CameraText
 CameraText structure used in various functions. More...
struct  CameraFilePath
 A structure created by the capture operation. More...
struct  _CameraFunctions
 Various camera specific functions. More...
struct  _Camera

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)

Typedefs

typedef _Camera Camera
 Object representing a camera attached to the system.
typedef int(*) CameraPrePostFunc (Camera *camera, GPContext *context)
typedef _CameraFunctions CameraFunctions
 Various camera specific functions.
typedef GPPort CameraPort
typedef GPPortInfo CameraPortInfo
typedef _CameraPrivateLibrary CameraPrivateLibrary
typedef _CameraPrivateCore CameraPrivateCore
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.

typedef int(*) CameraExitFunc (Camera *camera, GPContext *context)
 The camera exit function.
typedef int(*) CameraGetConfigFunc (Camera *camera, CameraWidget **widget, GPContext *context)
 Get a configuration tree for the camera and its driver.
typedef int(*) CameraSetConfigFunc (Camera *camera, CameraWidget *widget, GPContext *context)
 Set the configuration in the camera.
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)

Enumerations

enum  CameraCaptureType { GP_CAPTURE_IMAGE, GP_CAPTURE_MOVIE, GP_CAPTURE_SOUND }
 Type of the capture to do. More...
enum  CameraEventType { GP_EVENT_UNKNOWN, GP_EVENT_TIMEOUT, GP_EVENT_FILE_ADDED, GP_EVENT_FOLDER_ADDED }
 Specify what event we received from the camera. More...

Functions

int gp_camera_new (Camera **camera)
Preparing initialization
int gp_camera_set_abilities (Camera *camera, CameraAbilities abilities)
 Sets the camera 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)
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)
Initialization
int gp_camera_init (Camera *camera, GPContext *context)
int gp_camera_exit (Camera *camera, GPContext *context)
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)
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)
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)


Detailed Description

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.

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.


Typedef Documentation

typedef struct _Camera Camera

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.

typedef int(*) CameraExitFunc(Camera *camera, GPContext *context)

The camera exit function.

Parameters:
camera the current camera
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

typedef struct _CameraFunctions CameraFunctions

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.

typedef int(*) CameraGetConfigFunc(Camera *camera, CameraWidget **widget, GPContext *context)

Get a configuration tree for the camera and its driver.

Parameters:
camera the current camera
widget pointer to store the toplevel widget of the tree
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

typedef int(*) CameraPrePostFunc(Camera *camera, GPContext *context)

Parameters:
camera a Camera object
context a GPContext object
Returns:
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.

typedef int(*) CameraSetConfigFunc(Camera *camera, CameraWidget *widget, GPContext *context)

Set the configuration in the camera.

Parameters:
camera the current camera
widget the configuration widget tree that was changed
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


Enumeration Type Documentation

enum CameraCaptureType

Type of the capture to do.

Specifies the type of capture the user wants to do with the gp_camera_capture() function.

Enumerator:
GP_CAPTURE_IMAGE  Capture an image.
GP_CAPTURE_MOVIE  Capture a movie.
GP_CAPTURE_SOUND  Capture audio.

enum CameraEventType

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.

Enumerator:
GP_EVENT_UNKNOWN  unknown and unhandled event
GP_EVENT_TIMEOUT  timeout, no arguments
GP_EVENT_FILE_ADDED  CameraFilePath* = file path on camfs
GP_EVENT_FOLDER_ADDED  CameraFilePath* = folder on camfs


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 folder.

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_storageinfo ( Camera camera,
CameraStorageInformation **  sifs,
int *  nrofsifs,
GPContext context 
)

Gets information on the camera attached storage.

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_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.


Generated on Sun Jul 22 19:29:32 2007 for libgphoto2 photo camera library (libgphoto2) by  doxygen 1.5.0