![]() | ![]() | ![]() | The Canon driver reference | ![]() |
---|
#include <usb.h> int canon_usb_camera_init (Camera *camera, GPContext *context); unsigned char* canon_usb_capture_dialogue (Camera *camera, int *return_length, GPContext *context); unsigned char* canon_usb_dialogue (Camera *camera, canonCommandIndex canon_funct, int *return_length, const char *payload, int payload_length); int canon_usb_get_file (Camera *camera, const char *name, unsigned char **data, int *length, GPContext *context); int canon_usb_get_thumbnail (Camera *camera, const char *name, unsigned char **data, int *length, GPContext *context); int canon_usb_get_captured_thumbnail (Camera *camera, const int key, unsigned char **data, int *length, GPContext *context); int canon_usb_get_captured_image (Camera *camera, const int key, unsigned char **data, int *length, GPContext *context); int canon_usb_set_file_attributes (Camera *camera, unsigned short attr_bits, const char *pathname, GPContext *context); int canon_usb_identify (Camera *camera, GPContext *context); int canon_usb_init (Camera *camera, GPContext *context); int canon_usb_lock_keys (Camera *camera, GPContext *context); int canon_usb_long_dialogue (Camera *camera, canonCommandIndex canon_funct, unsigned char **data, int *data_length, int max_data_size, const char *payload, int payload_length, int display_status, GPContext *context); int canon_usb_poll_interrupt_multiple (Camera *camera[], int n_cameras, int camera_flags[], unsigned char *buf, int n_tries, int *which); int canon_usb_put_file (Camera *camera, CameraFile *file, char *destname, char *destpath, GPContext *context); int canon_usb_ready (Camera *camera); int canon_usb_set_file_time (Camera *camera, char *camera_filename, time_t time, GPContext *context); int canon_usb_unlock_keys (Camera *camera, GPContext *context); enum canonCommandIndex; enum canonSubcommandIndex; enum canonTransferMode; #define USB_BULK_READ_SIZE #define USB_BULK_WRITE_SIZE #define MAX_INTERRUPT_TRIES
int canon_usb_camera_init (Camera *camera, GPContext *context);
Initializes the USB camera through a series of read/writes
camera : | camera to initialize |
context : | context for error reporting GP_OK on success. GP_ERROR on any error. |
Returns : | gphoto2 error code |
unsigned char* canon_usb_capture_dialogue (Camera *camera, int *return_length, GPContext *context);
Handles the "capture image" command, where we must read the interrupt pipe before getting the normal command response.
We call canon_usb_dialogue()
for the actual "release shutter"
command, then handle the interrupt pipe here.
camera : | the Camera to work with |
return_length : | number of bytes to read from the camera as response |
context : | context for error reporting |
Returns : | a char * that points to the data read from the camera (or
NULL on failure), and sets what |
unsigned char* canon_usb_dialogue (Camera *camera, canonCommandIndex canon_funct, int *return_length, const char *payload, int payload_length);
USB version of the canon_serial_dialogue function.
We construct a packet with the known command values (cmd{1,2,3}) of the function requested (canon_funct) to the camera. If return_length exists for this function, we read return_length bytes back from the camera and return this camera response to the caller.
Example :
This function gets called with canon_funct = CANON_USB_FUNCTION_SET_TIME payload = already constructed payload with the new time we construct a complete command packet and send this to the camera. The canon_usb_cmdstruct indicates that command CANON_USB_FUNCTION_SET_TIME returns four bytes, so we read those four bytes into our buffer and return a pointer to the buffer to the caller.
This should probably be changed so that the caller supplies a unsigned char ** which can be pointed to our buffer and an int returned with GP_OK or some error code.
camera : | the Camera to work with |
canon_funct : | integer constant that identifies function we are execute |
return_length : | number of bytes to read from the camera as response |
payload : | data we are to send to the camera |
payload_length : | length of payload |
Returns : | a char * that points to the data read from the camera (or
NULL on failure), and sets what |
int canon_usb_get_file (Camera *camera, const char *name, unsigned char **data, int *length, GPContext *context);
Get a file from a USB_connected Canon camera.
camera : | camera to lock keys on |
name : | name of file to fetch |
data : | to receive image data |
length : | to receive length of image data |
context : | context for error reporting |
Returns : | gphoto2 error code, length in |
int canon_usb_get_thumbnail (Camera *camera, const char *name, unsigned char **data, int *length, GPContext *context);
Gets a thumbnail from a USB_connected Canon camera.
camera : | camera to lock keys on |
name : | name of thumbnail to fetch |
data : | to receive image data |
length : | to receive length of image data |
context : | context for error reporting |
Returns : | gphoto2 error code, length in |
int canon_usb_get_captured_thumbnail (Camera *camera, const int key, unsigned char **data, int *length, GPContext *context);
Gets the just-captured thumbnail from a USB-connected Canon
camera. This function must be called after a remote image capture,
before leaving remote capture mode, and needs the image key
returned by canon_usb_capture_dialog()
.
camera : | camera to lock keys on |
key : | index of image to fetch, returned from |
data : | to receive thumbnail data |
length : | to receive length of thumbnail data |
context : | context for error reporting |
Returns : | gphoto2 error code, length in |
int canon_usb_get_captured_image (Camera *camera, const int key, unsigned char **data, int *length, GPContext *context);
Gets the just-captured image from a USB-connected Canon
camera. This function must be called soon after an image capture,
and needs the image key returned by canon_usb_capture_dialogue()
.
camera : | camera to lock keys on |
key : | index of image to fetch, returned from |
data : | to receive image data |
length : | to receive length of image data |
context : | context for error reporting |
Returns : | gphoto2 error code, length in |
int canon_usb_set_file_attributes (Camera *camera, unsigned short attr_bits, const char *pathname, GPContext *context);
Changes the attribute bits in a specified directory entry.
camera : | camera to initialize |
Param2 : | |
pathname : | pathname of file whose attributes are to be changed. |
context : | context for error reporting |
Returns : | gphoto2 error code |
int canon_usb_identify (Camera *camera, GPContext *context);
Identify a supported camera by looking through our list of models.
camera : | camera to identify |
context : | context for error reporting GP_ERROR_MODEL_NOT_FOUND if not found in our list; this is a code inconsistency. GP_OK otherwise |
Returns : | gphoto2 error code |
int canon_usb_init (Camera *camera, GPContext *context);
Initializes the given USB device.
camera : | camera to initialize |
context : | context for error reporting |
Returns : | gphoto2 error code (GP_OK on success). |
int canon_usb_lock_keys (Camera *camera, GPContext *context);
Lock the keys on the camera and turn off the display
camera : | camera to lock keys on |
context : | context for error reporting |
Returns : | gphoto2 error code |
int canon_usb_long_dialogue (Camera *camera, canonCommandIndex canon_funct, unsigned char **data, int *data_length, int max_data_size, const char *payload, int payload_length, int display_status, GPContext *context);
This function is used to invoke camera commands which return L (long) data.
It calls #canon_usb_dialogue()
, if it gets a good response it will malloc()
memory and read the entire returned data into this malloc'd memory and store
a pointer to the malloc'd memory in 'data'.
camera : | the Camera to work with |
canon_funct : | integer constant that identifies function we are execute |
data : | Pointer to pointer to allocated memory holding the data returned from the camera |
data_length : | Pointer to where you want the number of bytes read from the camera |
max_data_size : | Max realistic data size so that we can abort if something goes wrong |
payload : | data we are to send to the camera |
payload_length : | length of payload |
display_status : | Whether you want progress bar for this operation or not |
context : | context for error reporting |
Returns : | gphoto2 error code |
int canon_usb_poll_interrupt_multiple (Camera *camera[], int n_cameras, int camera_flags[], unsigned char *buf, int n_tries, int *which);
Polls the interrupt pipes of several cameras either until one
responds, or for a specified number of tries.
We will return when:
1. a non-zero length is returned,
2. an error code is returned, or
3. the number of read attempts reaches n_tries
.
camera : | Array of Camera's to work with |
n_cameras : | Length of camera |
camera_flags : | array of int's corresponding to entries in camera. Non-zero (true) if that camera is to be polled, zero (false) if that camera is to be ignored. |
buf : | buffer to receive data read from the pipe. |
n_tries : | number of times to try |
which : | returns index of camera that responded |
Returns : | length of read, or zero if n_tries has been exceeded, or gphoto2 error code from read that results in an I/O error. |
int canon_usb_put_file (Camera *camera, CameraFile *file, char *destname, char *destpath, GPContext *context);
Uploads file to USB camera
Bugs:
at the moment, files bigger than 65572-length(filename), while being
correctly uploaded, cause the camera to not accept any more uploads.
Smaller files work fine.
s10sh (http://www.kyuzz.org/antirez/s10sh.html) has the same problem.
The problem only appears when USB deinitialisation and initialisation
is performed between uploads. You can call this function more than
once with big files during one session without encountering the problem
described. <krammquiss.org
>
camera : | camera to lock keys on |
file : | CameraFile object to upload |
destname : | name file should have on camera |
destpath : | pathname for directory to put file |
context : | context for error reporting |
Returns : | gphoto2 error code |
int canon_usb_ready (Camera *camera);
USB part of canon_int_ready
camera : | camera to get ready |
Returns : | gphoto2 error code |
int canon_usb_set_file_time (Camera *camera, char *camera_filename, time_t time, GPContext *context);
Finishes the upload of an image to a Canon camera. Must be called after the last data transfer completes.
camera : | camera to unlock keys on |
camera_filename : | Full pathname to use on camera |
time : | Unix time to store in camera directory |
context : | context for error reporting |
Returns : | gphoto2 error code |
int canon_usb_unlock_keys (Camera *camera, GPContext *context);
Unlocks the keys on cameras that support this
camera : | camera to unlock keys on |
context : | context for error reporting |
Returns : | gphoto2 error code |
typedef enum { CANON_USB_FUNCTION_GET_FILE = 1, CANON_USB_FUNCTION_IDENTIFY_CAMERA, CANON_USB_FUNCTION_GET_TIME, CANON_USB_FUNCTION_SET_TIME, CANON_USB_FUNCTION_MKDIR, CANON_USB_FUNCTION_CAMERA_CHOWN, CANON_USB_FUNCTION_RMDIR, CANON_USB_FUNCTION_DISK_INFO, CANON_USB_FUNCTION_FLASH_DEVICE_IDENT, CANON_USB_FUNCTION_POWER_STATUS, CANON_USB_FUNCTION_GET_DIRENT, CANON_USB_FUNCTION_DELETE_FILE, CANON_USB_FUNCTION_SET_ATTR, CANON_USB_FUNCTION_GET_PIC_ABILITIES, CANON_USB_FUNCTION_GENERIC_LOCK_KEYS, CANON_USB_FUNCTION_EOS_LOCK_KEYS, CANON_USB_FUNCTION_EOS_UNLOCK_KEYS, CANON_USB_FUNCTION_RETRIEVE_CAPTURE, CANON_USB_FUNCTION_RETRIEVE_PREVIEW, CANON_USB_FUNCTION_CONTROL_CAMERA, CANON_USB_FUNCTION_UNKNOWN_FUNCTION, CANON_USB_FUNCTION_EOS_GET_BODY_ID, CANON_USB_FUNCTION_SET_FILE_TIME } canonCommandIndex;
Codes to give to canon_usb_dialogue()
or canon_usb_long_dialogue()
to select which command to issue to the camera. See the protocol
document for details.
CANON_USB_FUNCTION_GET_FILE | Command to download a file from the camera. |
CANON_USB_FUNCTION_IDENTIFY_CAMERA | Command to read the firmware version and strings with the camera type and owner from the camera. |
CANON_USB_FUNCTION_GET_TIME | Command to get the time in Unix time format from the camera. |
CANON_USB_FUNCTION_SET_TIME | Command to set the camera's internal time. |
CANON_USB_FUNCTION_MKDIR | Command to create a directory on the camera storage device. |
CANON_USB_FUNCTION_CAMERA_CHOWN | Change "owner" string on camera |
CANON_USB_FUNCTION_RMDIR | Command to delete a directory from camera storage. |
CANON_USB_FUNCTION_DISK_INFO | Command to get disk information from the camera, given a disk designator (e.g. "D:"). Returns total capacity and free space. |
CANON_USB_FUNCTION_FLASH_DEVICE_IDENT | Command to request the disk specifier (drive letter) for the storage device being used. |
CANON_USB_FUNCTION_POWER_STATUS | Command to query the camera for its power status: battery vs. mains, and whether the battery is low. |
CANON_USB_FUNCTION_GET_DIRENT | Get directory entries |
CANON_USB_FUNCTION_DELETE_FILE | Delete file |
CANON_USB_FUNCTION_SET_ATTR | Command to set the attributes of a file on the camera (e.g. downloaded, protect from delete). |
CANON_USB_FUNCTION_GET_PIC_ABILITIES | Command to "get picture abilities", which seems to be a list of the different sizes and quality of images that are available on this camera. Not implemented (and will cause an error) on the EOS cameras or on newer PowerShot cameras such as S45, G3, G5. |
CANON_USB_FUNCTION_GENERIC_LOCK_KEYS | Command to lock keys (and turn on "PC" indicator) on non-EOS cameras. |
CANON_USB_FUNCTION_EOS_LOCK_KEYS | Lock keys (EOS cameras) |
CANON_USB_FUNCTION_EOS_UNLOCK_KEYS | Unlock keys (EOS cameras) |
CANON_USB_FUNCTION_RETRIEVE_CAPTURE | Command to retrieve the last image captured, depending on the transfer mode set via CANON_USB_FUNCTION_CONTROL_CAMERA with subcommand CANON_USB_CONTROL_SET_TRANSFER_MODE. |
CANON_USB_FUNCTION_RETRIEVE_PREVIEW | Command to retrieve a preview image. |
CANON_USB_FUNCTION_CONTROL_CAMERA | Remote camera control (with many subcodes) |
CANON_USB_FUNCTION_UNKNOWN_FUNCTION | Don't know what this is for; it has been sighted in USB trace logs for an EOS D30, but not for a D60 or for any PowerShot camera. |
CANON_USB_FUNCTION_EOS_GET_BODY_ID | Command to read the body ID (serial number) from an EOS camera. |
CANON_USB_FUNCTION_SET_FILE_TIME | Set file time |
typedef enum { CANON_USB_CONTROL_INIT = 1, CANON_USB_CONTROL_SHUTTER_RELEASE, CANON_USB_CONTROL_SET_PARAMS, CANON_USB_CONTROL_SET_TRANSFER_MODE, CANON_USB_CONTROL_GET_PARAMS, CANON_USB_CONTROL_GET_ZOOM_POS, CANON_USB_CONTROL_SET_ZOOM_POS, CANON_USB_CONTROL_GET_EXT_PARAMS_SIZE, CANON_USB_CONTROL_GET_EXT_PARAMS, CANON_USB_CONTROL_EXIT, CANON_USB_CONTROL_VIEWFINDER_START, CANON_USB_CONTROL_VIEWFINDER_STOP, CANON_USB_CONTROL_GET_AVAILABLE_SHOT, CANON_USB_CONTROL_SET_CUSTOM_FUNC, /* Not yet seen in USB trace */ CANON_USB_CONTROL_GET_CUSTOM_FUNC, CANON_USB_CONTROL_GET_EXT_PARAMS_VER, /* Not yet seen in USB trace */ CANON_USB_CONTROL_SET_EXT_PARAMS, /* Not yet seen in USB trace */ CANON_USB_CONTROL_SELECT_CAM_OUTPUT, /* Not yet seen in USB trace */ CANON_USB_CONTROL_DO_AE_AF_AWB, /* Not yet seen in USB trace */ } canonSubcommandIndex;
CANON_USB_FUNCTION_CONTROL_CAMERA commands are used for a wide range of remote camera control actions. A control_cmdstruct is defined below for the following remote camera control options.
CANON_USB_CONTROL_INIT | Enter camera control mode |
CANON_USB_CONTROL_SHUTTER_RELEASE | Release camera shutter (capture still) |
CANON_USB_CONTROL_SET_PARAMS | Set release parameters (AE mode, beep, etc.) |
CANON_USB_CONTROL_SET_TRANSFER_MODE | Set transfer mode for next image capture. Either the full image, a thumbnail or both may be either stored on the camera, downloaded to the host, or both. |
CANON_USB_CONTROL_GET_PARAMS | Read the same parameters set by
|
CANON_USB_CONTROL_GET_ZOOM_POS | Get the position of the zoom lens |
CANON_USB_CONTROL_SET_ZOOM_POS | Set the position of the zoom lens |
CANON_USB_CONTROL_GET_EXT_PARAMS_SIZE | Get the size of the "extended release parameters". |
CANON_USB_CONTROL_GET_EXT_PARAMS | Get the "extended release parameters". |
CANON_USB_CONTROL_EXIT | Leave camera control mode; opposite of
|
CANON_USB_CONTROL_VIEWFINDER_START | Switch video viewfinder on. |
CANON_USB_CONTROL_VIEWFINDER_STOP | Swictch video viewfinder off. |
CANON_USB_CONTROL_GET_AVAILABLE_SHOT | Get estimated number of images that can be captured in current mode before filling flash card. |
CANON_USB_CONTROL_SET_CUSTOM_FUNC | Not yet seen in USB trace. |
CANON_USB_CONTROL_GET_CUSTOM_FUNC | Read custom functions from an EOS camera |
CANON_USB_CONTROL_GET_EXT_PARAMS_VER | Not yet seen in USB trace. |
CANON_USB_CONTROL_SET_EXT_PARAMS | Not yet seen in USB trace. |
CANON_USB_CONTROL_SELECT_CAM_OUTPUT | Not yet seen in USB trace. |
CANON_USB_CONTROL_DO_AE_AF_AWB | Not yet seen in USB trace. |
typedef enum { REMOTE_CAPTURE_THUMB_TO_PC = 0x0001, REMOTE_CAPTURE_FULL_TO_PC = 0x0002, REMOTE_CAPTURE_THUMB_TO_DRIVE = 0x0004, REMOTE_CAPTURE_FULL_TO_DRIVE = 0x0008 } canonTransferMode;
Hardware codes to control image transfer in a remote capture
operation. These are bits that may be OR'ed together to get
multiple things to happen at once. For example,
REMOTE_CAPTURE_THUMB_TO_PC
|REMOTE_CAPTURE_FULL_TO_DRIVE
is what
D30Capture uses to store the full image on the camera, but provide
an on-screen thumbnail.
REMOTE_CAPTURE_THUMB_TO_PC | Transfer the thumbnail to the host |
REMOTE_CAPTURE_FULL_TO_PC | Transfer the full-size image directly to the host |
REMOTE_CAPTURE_THUMB_TO_DRIVE | Store the thumbnail on the camera storage |
REMOTE_CAPTURE_FULL_TO_DRIVE | Store the full-size image on the camera storage |
#define USB_BULK_READ_SIZE 0x1400
Maximum size to be used for a USB "bulk read" operation
#define USB_BULK_WRITE_SIZE 0x1400
Maximum size to be used for a USB "bulk write" operation
<<< USB communication | Handling Camera Directories >>> |