libgphoto2 photo camera library (libgphoto2) API  2.5.10.1
gphoto2-port.c File Reference
#include "config.h"
#include <stdarg.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <ltdl.h>
#include <gphoto2/gphoto2-port-result.h>
#include <gphoto2/gphoto2-port-library.h>
#include <gphoto2/gphoto2-port-log.h>
#include "gphoto2-port-info.h"
Include dependency graph for gphoto2-port.c:

Data Structures

struct  _GPPortPrivateCore
 Internal private libgphoto2_port data. This structure contains private data. More...
 

Macros

#define _BSD_SOURCE
 
#define _(String)   (String)
 
#define N_(String)   (String)
 
#define ngettext(String1, String2, Count)   ((Count==1)?String1:String2)
 
#define CHECK_RESULT(result)   {int r=(result); if (r<0) return (r);}
 
#define CHECK_SUPP(p, t, o)   {if (!(o)) {gp_port_set_error ((p), _("The operation '%s' is not supported by this device"), (t)); return (GP_ERROR_NOT_SUPPORTED);}}
 
#define CHECK_INIT(p)   {if (!(p)->pc->ops) {gp_port_set_error ((p), _("The port has not yet been initialized")); return (GP_ERROR_BAD_PARAMETERS);}}
 
#define LOG_DATA(DATA, SIZE, EXPECTED, MSG_PRE, MSG_POST, ...)
 
#define FAST_TIMEOUT   50
 

Functions

int gp_port_new (GPPort **port)
 Create new GPPort. More...
 
int gp_port_set_info (GPPort *port, GPPortInfo info)
 Configure a port. More...
 
int gp_port_get_info (GPPort *port, GPPortInfo *info)
 Retreives information about the port. More...
 
int gp_port_open (GPPort *port)
 Open a port. More...
 
int gp_port_close (GPPort *port)
 Close a port. More...
 
int gp_port_reset (GPPort *port)
 Reset a port. More...
 
int gp_port_free (GPPort *port)
 Free the port structure. More...
 
int gp_port_write (GPPort *port, const char *data, int size)
 Writes a specified amount of data to a port. More...
 
int gp_port_read (GPPort *port, char *data, int size)
 Read data from port. More...
 
int gp_port_check_int (GPPort *port, char *data, int size)
 Check for intterupt. More...
 
int gp_port_check_int_fast (GPPort *port, char *data, int size)
 Check for interrupt without wait. More...
 
int gp_port_set_timeout (GPPort *port, int timeout)
 Set timeout of port. More...
 
int gp_port_timeout_set (GPPort *, int)
 
int gp_port_timeout_get (GPPort *, int *)
 
int gp_port_get_timeout (GPPort *port, int *timeout)
 Get the current port timeout. More...
 
int gp_port_set_settings (GPPort *port, GPPortSettings settings)
 Set port settings. More...
 
int gp_port_settings_get (GPPort *, GPPortSettings *)
 
int gp_port_settings_set (GPPort *, GPPortSettings)
 
int gp_port_get_settings (GPPort *port, GPPortSettings *settings)
 Get the current port settings. More...
 
int gp_port_get_pin (GPPort *port, GPPin pin, GPLevel *level)
 Get setting of specific serial PIN. More...
 
int gp_port_set_pin (GPPort *port, GPPin pin, GPLevel level)
 Set specified serial PIN to value. More...
 
int gp_port_send_break (GPPort *port, int duration)
 Send a break over a serial port. More...
 
int gp_port_flush (GPPort *port, int direction)
 Flush data on serial port. More...
 
int gp_port_usb_find_device (GPPort *port, int idvendor, int idproduct)
 Find USB device by vendor/product. More...
 
int gp_port_usb_find_device_by_class (GPPort *port, int mainclass, int subclass, int protocol)
 Find USB device by interface class. More...
 
int gp_port_usb_clear_halt (GPPort *port, int ep)
 Clear USB endpoint HALT condition. More...
 
int gp_port_usb_msg_write (GPPort *port, int request, int value, int index, char *bytes, int size)
 Send a USB control message with output data. More...
 
int gp_port_usb_msg_read (GPPort *port, int request, int value, int index, char *bytes, int size)
 Send a USB control message with input data. More...
 
int gp_port_usb_msg_interface_write (GPPort *port, int request, int value, int index, char *bytes, int size)
 Send a USB interface control message with output data. More...
 
int gp_port_usb_msg_interface_read (GPPort *port, int request, int value, int index, char *bytes, int size)
 Send a USB interface control message with input data. More...
 
int gp_port_usb_msg_class_write (GPPort *port, int request, int value, int index, char *bytes, int size)
 Send a USB class control message with output data. More...
 
int gp_port_usb_msg_class_read (GPPort *port, int request, int value, int index, char *bytes, int size)
 Send a USB class control message with input data. More...
 
int gp_port_seek (GPPort *port, int offset, int whence)
 Seek on a port (for usb disk direct ports) More...
 
int gp_port_send_scsi_cmd (GPPort *port, int to_dev, char *cmd, int cmd_size, char *sense, int sense_size, char *data, int data_size)
 Send a SCSI command to a port (for usb scsi ports) More...
 
int gp_port_set_error (GPPort *port, const char *format,...)
 Set verbose port error message. More...
 
const char * gp_port_get_error (GPPort *port)
 Get verbose port error message. More...
 

Detailed Description

Author
Copyright 2001 Lutz Mueller lutz@.nosp@m.user.nosp@m.s.sf..nosp@m.net
Copyright 1999 Scott Fritzinger scott.nosp@m.f@un.nosp@m.r.edu
License
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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Macro Definition Documentation

#define FAST_TIMEOUT   50

The timeout in milliseconds for fast interrupt reads.

Referenced by gp_port_check_int_fast().

#define LOG_DATA (   DATA,
  SIZE,
  EXPECTED,
  MSG_PRE,
  MSG_POST,
  ... 
)
Value:
if (SIZE != EXPECTED) \
GP_LOG_DATA (DATA, SIZE, MSG_PRE " %i = 0x%x out of %i bytes " MSG_POST, SIZE, SIZE, EXPECTED, ##__VA_ARGS__); \
GP_LOG_DATA (DATA, SIZE, MSG_PRE " %i = 0x%x bytes " MSG_POST, SIZE, SIZE, ##__VA_ARGS__)
Log message is a data hex dump.
Definition: gphoto2-port-log.h:34

Function Documentation

int gp_port_check_int ( GPPort port,
char *  data,
int  size 
)

Check for intterupt.

Parameters
porta GPPort
dataa pointer to an allocated buffer
sizethe number of bytes that should be read

Reads a specified number of bytes from the interrupt endpoint into the supplied buffer. Function waits port->timeout miliseconds for data on interrupt endpoint.

Returns
a gphoto2 error code

References gp_log(), GP_LOG_DATA, _GPPortPrivateCore::ops, _GPPort::pc, and _GPPort::timeout.

int gp_port_check_int_fast ( GPPort port,
char *  data,
int  size 
)

Check for interrupt without wait.

Parameters
porta GPPort
dataa pointer to an allocated buffer
sizethe number of bytes that should be read

Reads a specified number of bytes from the inerrupt endpoint into the supplied buffer. Function waits 50 miliseconds for data on interrupt endpoint.

Returns
a gphoto2 error code

References FAST_TIMEOUT, gp_log(), GP_LOG_DATA, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_close ( GPPort port)

Close a port.

Parameters
porta GPPort

Closes a port temporarily. It can afterwards be reopened using gp_port_open.

Returns
a gphoto2 error code

References GP_OK, _GPPortPrivateCore::ops, and _GPPort::pc.

Referenced by gp_camera_exit(), gp_camera_init(), and gp_port_free().

int gp_port_flush ( GPPort port,
int  direction 
)

Flush data on serial port.

Parameters
porta GPPort
directionthe direction of the flush

Flushes the serial output or input (depending on direction) of the serial port.

Returns
a gphoto2 error code

References GP_OK, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_free ( GPPort port)

Free the port structure.

Parameters
porta GPPort

Closes the port and frees the memory.

Returns
a gphoto2 error code

References GP_OK, gp_port_close(), _GPPortPrivateCore::info, _GPPortPrivateCore::lh, _GPPortInfo::library_filename, _GPPortInfo::name, _GPPortPrivateCore::ops, _GPPortInfo::path, and _GPPort::pc.

Referenced by gp_abilities_list_detect(), gp_camera_free(), and gp_port_new().

const char* gp_port_get_error ( GPPort port)

Get verbose port error message.

Parameters
porta GPPort

Retrieves an error message from a port. If you want to make sure that you get correct error messages, you need to call gp_port_set_error with an error message of NULL each time before calling another port-related function of which you want to check the return value.

Returns
a translated error message

References _GPPortPrivateCore::error, and _GPPort::pc.

int gp_port_get_info ( GPPort port,
GPPortInfo info 
)

Retreives information about the port.

Retrieves the informations set by gp_port_set_info().

Parameters
porta GPPort
infoGPPortInfo
Returns
a gphoto2 error code

References GP_OK, _GPPortPrivateCore::info, and _GPPort::pc.

Referenced by gp_camera_get_abilities(), and gp_camera_init().

int gp_port_get_pin ( GPPort port,
GPPin  pin,
GPLevel level 
)

Get setting of specific serial PIN.

Parameters
porta GPPort
pinthe serial pin to be retrieved
levelthe setting of the pin
Returns
a gphoto2 error code

References GP_LEVEL_HIGH, GP_LEVEL_LOW, GP_OK, GP_PIN_CD, GP_PIN_CTS, GP_PIN_DSR, GP_PIN_DTR, GP_PIN_RING, GP_PIN_RTS, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_get_settings ( GPPort port,
GPPortSettings settings 
)

Get the current port settings.

Parameters
porta GPPort
settingspointer to the retrieved settings

Retreives the current settings of a port.

Returns
a gphoto2 error code

References GP_OK, and _GPPort::settings.

Referenced by gp_camera_set_port_speed(), and gp_port_settings_get().

int gp_port_get_timeout ( GPPort port,
int *  timeout 
)

Get the current port timeout.

Parameters
porta GPPort
timeoutpointer to timeout

Retreives the current timeout of the port.

Returns
a gphoto2 error code

References GP_OK, and _GPPort::timeout.

Referenced by gp_port_timeout_get().

int gp_port_new ( GPPort **  port)

Create new GPPort.

Allocate and initialize the memory for a new GPPort.

After you called this function, you probably want to call gp_port_set_info in order to make the newly created port functional.

Parameters
portPointer the GPPort* pointer
Returns
a gphoto2 error code

References GP_ERROR_NO_MEMORY, GP_OK, gp_port_free(), _GPPortPrivateCore::ops, and _GPPort::pc.

Referenced by gp_abilities_list_detect(), and gp_camera_new().

int gp_port_open ( GPPort port)

Open a port.

Parameters
porta GPPort

Opens a port which should have been created with gp_port_new and configured with gp_port_set_info and gp_port_set_settings

Returns
a gphoto2 error code

References GP_OK, GP_PORT_SERIAL, GP_PORT_USB, _GPPortPrivateCore::ops, _GPPort::pc, and _GPPort::type.

Referenced by gp_camera_exit(), and gp_camera_init().

int gp_port_read ( GPPort port,
char *  data,
int  size 
)

Read data from port.

Parameters
porta GPPort
dataa pointer to an allocated buffer
sizethe number of bytes that should be read

Reads a specified number of bytes from the port into the supplied buffer. It returns the number of bytes read or a negative error code.

Returns
a gphoto2 error code or the amount of data read

References gp_log(), GP_LOG_DATA, gp_port_result_as_string(), _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_reset ( GPPort port)

Reset a port.

Parameters
porta GPPort

Resets a port. Device will likely reconnect and appear under a new id.

Returns
a gphoto2 error code

References GP_OK, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_seek ( GPPort port,
int  offset,
int  whence 
)

Seek on a port (for usb disk direct ports)

Parameters
porta GPPort
offsetoffset to seek to
whencethe underlying lseek call whence parameter

Seeks to a specific offset on the usb disk

Returns
a gphoto2 error code

References _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_send_break ( GPPort port,
int  duration 
)

Send a break over a serial port.

Parameters
porta GPPort
durationduration of break in milliseconds

Sends a break with the specified duration in milliseconds.

Returns
a gphoto2 error code

References GP_OK, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_send_scsi_cmd ( GPPort port,
int  to_dev,
char *  cmd,
int  cmd_size,
char *  sense,
int  sense_size,
char *  data,
int  data_size 
)

Send a SCSI command to a port (for usb scsi ports)

Parameters
porta GPPort
to_devdata direction, set to 1 for a scsi cmd which sends data to the device, set to 0 for cmds which read data from the dev.
cmdbuffer holding the command to send
cmd_sizesizeof cmd buffer
sensebuffer for returning scsi sense information
sense_sizesizeof sense buffer
databuffer containing informatino to write to the device (to_dev is 1), or to store data read from the device (to_dev 0).

Send a SCSI command to a usb scsi port attached device.

Returns
a gphoto2 error code

References GP_LOG_DATA, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_set_error ( GPPort port,
const char *  format,
  ... 
)

Set verbose port error message.

Parameters
porta GPPort
formatprintf style format string
...variable arguments depending on format string

Sets an error message that can later be retrieved using gp_port_get_error.

Returns
a gphoto2 error code

References _GPPortPrivateCore::error, GP_OK, and _GPPort::pc.

Referenced by gp_abilities_list_detect().

int gp_port_set_pin ( GPPort port,
GPPin  pin,
GPLevel  level 
)

Set specified serial PIN to value.

Parameters
porta GPPort
pinthe serial pin to be retrieved
levelthe setting of the pin

Pulls the specified pin of a serial port to the specified level.

Returns
a gphoto2 error code

References GP_OK, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_set_settings ( GPPort port,
GPPortSettings  settings 
)

Set port settings.

Parameters
porta GPPort
settingsthe GPPortSettings to be set

Adjusts the settings of a port. You should always call gp_port_get_settings, adjust the values depending on the type of the port, and then call gp_port_set_settings.

Returns
a gphoto2 error code

References GP_OK, gp_port_settings_get(), _GPPortPrivateCore::ops, _GPPort::pc, and _GPPort::settings_pending.

Referenced by gp_camera_set_port_speed(), gp_port_set_info(), and gp_port_settings_set().

int gp_port_set_timeout ( GPPort port,
int  timeout 
)

Set timeout of port.

Parameters
porta GPPort
timeoutthe timeout

Sets the timeout of a port. gp_port_read will wait timeout milliseconds for data. If no data will be received in that period, GP_ERROR_TIMEOUT will be returned.

Returns
a gphoto2 error code

References GP_OK, gp_port_timeout_set(), and _GPPort::timeout.

Referenced by gp_port_set_info(), and gp_port_timeout_set().

int gp_port_settings_get ( GPPort port,
GPPortSettings settings 
)

Deprecated

References gp_port_get_settings(), and gp_port_settings_set().

Referenced by gp_port_set_settings().

int gp_port_settings_set ( GPPort port,
GPPortSettings  settings 
)

Deprecated

References gp_port_set_settings().

Referenced by gp_port_settings_get().

int gp_port_timeout_get ( GPPort port,
int *  timeout 
)

Deprecated

References gp_port_get_timeout().

Referenced by gp_port_timeout_set().

int gp_port_timeout_set ( GPPort port,
int  timeout 
)

Deprecated

References gp_port_set_timeout(), and gp_port_timeout_get().

Referenced by gp_port_set_timeout().

int gp_port_usb_clear_halt ( GPPort port,
int  ep 
)

Clear USB endpoint HALT condition.

Parameters
porta GPPort
ependpoint to clear HALT

Clears the HALT (stall?) endpoint condition of the specified endpoint.

Returns
a gphoto2 error code

References GP_OK, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_usb_find_device ( GPPort port,
int  idvendor,
int  idproduct 
)

Find USB device by vendor/product.

Parameters
porta GPPort
idvendorUSB vendor id
idproductUSB product id

Find the USB device with the specified vendor:product id pair.

Returns
a gphoto2 error code

References GP_OK, _GPPortPrivateCore::ops, and _GPPort::pc.

Referenced by gp_abilities_list_load(), and gp_camera_init().

int gp_port_usb_find_device_by_class ( GPPort port,
int  mainclass,
int  subclass,
int  protocol 
)

Find USB device by interface class.

Parameters
porta GPPort
mainclassthe USB interface class
subclassthe USB interface subclass
protocolthe USB interface protocol

Find the USB device with the specified vendor:product id pair.

Returns
a gphoto2 error code

References GP_OK, _GPPortPrivateCore::ops, and _GPPort::pc.

Referenced by gp_abilities_list_load(), and gp_camera_init().

int gp_port_usb_msg_class_read ( GPPort port,
int  request,
int  value,
int  index,
char *  bytes,
int  size 
)

Send a USB class control message with input data.

Parameters
porta GPPort
requestcontrol request code
valuecontrol value
indexcontrol index
bytespointer to data
sizesize of the data

Sends a specific USB class control command and read associated data.

Returns
a gphoto2 error code

References gp_log(), GP_LOG_DATA, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_usb_msg_class_write ( GPPort port,
int  request,
int  value,
int  index,
char *  bytes,
int  size 
)

Send a USB class control message with output data.

Parameters
porta GPPort
requestcontrol request code
valuecontrol value
indexcontrol index
bytespointer to data
sizesize of the data

Sends a specific USB class control command and write associated data.

Returns
a gphoto2 error code

References GP_LOG_DATA, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_usb_msg_interface_read ( GPPort port,
int  request,
int  value,
int  index,
char *  bytes,
int  size 
)

Send a USB interface control message with input data.

Parameters
porta GPPort
requestcontrol request code
valuecontrol value
indexcontrol index
bytespointer to data
sizesize of the data

Sends a specific USB control command and read associated data.

Returns
a gphoto2 error code

References gp_log(), GP_LOG_DATA, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_usb_msg_interface_write ( GPPort port,
int  request,
int  value,
int  index,
char *  bytes,
int  size 
)

Send a USB interface control message with output data.

Parameters
porta GPPort
requestcontrol request code
valuecontrol value
indexcontrol index
bytespointer to data
sizesize of the data

Sends a specific USB interface control command and write associated data.

Returns
a gphoto2 error code

References GP_LOG_DATA, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_usb_msg_read ( GPPort port,
int  request,
int  value,
int  index,
char *  bytes,
int  size 
)

Send a USB control message with input data.

Parameters
porta GPPort
requestcontrol request code
valuecontrol value
indexcontrol index
bytespointer to data
sizesize of the data

Sends a specific USB interface control command and read associated data.

Returns
a gphoto2 error code

References gp_log(), GP_LOG_DATA, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_usb_msg_write ( GPPort port,
int  request,
int  value,
int  index,
char *  bytes,
int  size 
)

Send a USB control message with output data.

Parameters
porta GPPort
requestcontrol request code
valuecontrol value
indexcontrol index
bytespointer to data
sizesize of the data

Sends a specific USB control command and write associated data.

Returns
a gphoto2 error code

References GP_LOG_DATA, _GPPortPrivateCore::ops, and _GPPort::pc.

int gp_port_write ( GPPort port,
const char *  data,
int  size 
)

Writes a specified amount of data to a port.

Parameters
porta GPPort
datathe data to write to the port
sizethe number of bytes to write to the port

Writes data to the port. On non-serial ports the amount of data written is returned (and not just GP_OK).

Returns
a negative gphoto2 error code or the amount of data written.

References gp_log(), GP_LOG_DATA, gp_port_result_as_string(), _GPPortPrivateCore::ops, and _GPPort::pc.