libgphoto2 photo camera library (libgphoto2) API  2.5.10.1
gphoto2-port.h File Reference
#include <gphoto2/gphoto2-port-info-list.h>
#include <gphoto2/gphoto2-port-portability.h>
Include dependency graph for gphoto2-port.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  _GPPortSettingsSerial
 Port settings for serial ports. More...
 
struct  _GPPortSettingsUSB
 Port settings for USB ports. More...
 
struct  _GPPortSettingsUsbDiskDirect
 Port settings for USB mass storage direct IO ports. More...
 
struct  _GPPortSettingsUsbScsi
 Port settings for USB Mass Storage raw SCSI ports. More...
 
union  _GPPortSettings
 Union of port settings. More...
 
struct  _GPPort
 The GPhoto port structure. More...
 

Macros

#define TRUE   (0==0)
 
#define FALSE   (1==0)
 
#define GP_PORT_MAX_BUF_LEN   4096
 Maximum length of receive buffer.
 
#define PIN_CTS   GP_PIN_CTS
 

Typedefs

typedef enum _GPPortSerialParity GPPortSerialParity
 Serial parity. More...
 
typedef struct _GPPortSettingsSerial GPPortSettingsSerial
 Port settings for serial ports.
 
typedef struct _GPPortSettingsUSB GPPortSettingsUSB
 Port settings for USB ports.
 
typedef struct _GPPortSettingsUsbDiskDirect GPPortSettingsUsbDiskDirect
 Port settings for USB mass storage direct IO ports.
 
typedef struct _GPPortSettingsUsbScsi GPPortSettingsUsbScsi
 Port settings for USB Mass Storage raw SCSI ports.
 
typedef union _GPPortSettings GPPortSettings
 Union of port settings. More...
 
typedef struct _GPPortPrivateLibrary GPPortPrivateLibrary
 
typedef struct _GPPortPrivateCore GPPortPrivateCore
 
typedef struct _GPPort GPPort
 The GPhoto port structure. More...
 
typedef enum _GPPin GPPin
 Serial pins. More...
 
typedef enum _GPLevel GPLevel
 Level to pull specific lines. More...
 
typedef GPPort gp_port
 
typedef GPPortSettings gp_port_settings
 

Enumerations

enum  _GPPortSerialParity { GP_PORT_SERIAL_PARITY_OFF = 0, GP_PORT_SERIAL_PARITY_EVEN, GP_PORT_SERIAL_PARITY_ODD }
 Serial parity. More...
 
enum  { GP_PORT_USB_ENDPOINT_IN, GP_PORT_USB_ENDPOINT_OUT, GP_PORT_USB_ENDPOINT_INT }
 
enum  _GPPin {
  GP_PIN_RTS, GP_PIN_DTR, GP_PIN_CTS, GP_PIN_DSR,
  GP_PIN_CD, GP_PIN_RING
}
 Serial pins. More...
 
enum  _GPLevel { GP_LEVEL_LOW = 0, GP_LEVEL_HIGH = 1 }
 Level to pull specific lines. More...
 

Functions

int gp_port_new (GPPort **port)
 Create new GPPort. More...
 
int gp_port_free (GPPort *port)
 Free the port structure. 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_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_get_timeout (GPPort *port, int *timeout)
 Get the current port timeout. More...
 
int gp_port_set_timeout (GPPort *port, int timeout)
 Set timeout of port. More...
 
int gp_port_set_settings (GPPort *port, GPPortSettings settings)
 Set port settings. More...
 
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
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 PIN_CTS   GP_PIN_CTS
Deprecated:
internal define

Typedef Documentation

typedef GPPort gp_port
Deprecated:
internal typedef
Deprecated:
internal typedef
typedef enum _GPLevel GPLevel

Level to pull specific lines.

The level on which to pull some of the serial lines.

typedef enum _GPPin GPPin

Serial pins.

A number of serial pins to trigger and pull. This is necessary for some devices that have more than just the regular 3 or 4 wires.

typedef struct _GPPort GPPort

The GPhoto port structure.

This structure tracks the physical connection of the device. It can correspond the various methods of lowlevel access, serial usb and others and abstracts them as much as possible.

Frontends should consider this structure opaque and only use accessor functions.

Camera drivers should only access the type and pl members directly, and use accessor functions for the rest.

Serial parity.

Parity of the serial port.

Union of port settings.

This contains a shared union of possible settings for ports needing them.

Enumeration Type Documentation

anonymous enum
Enumerator
GP_PORT_USB_ENDPOINT_IN 

USB bulk IN ep.

GP_PORT_USB_ENDPOINT_OUT 

USB bulk OUT ep.

GP_PORT_USB_ENDPOINT_INT 

USB Interrupt ep.

enum _GPLevel

Level to pull specific lines.

The level on which to pull some of the serial lines.

Enumerator
GP_LEVEL_LOW 

Pull to low (0V)

GP_LEVEL_HIGH 

Pull to high (nV)

enum _GPPin

Serial pins.

A number of serial pins to trigger and pull. This is necessary for some devices that have more than just the regular 3 or 4 wires.

Enumerator
GP_PIN_RTS 

RTS line.

GP_PIN_DTR 

DTR line.

GP_PIN_CTS 

CTS line.

GP_PIN_DSR 

DSR line.

GP_PIN_CD 

Carrier Detect line.

GP_PIN_RING 

RING (Modem) line.

Serial parity.

Parity of the serial port.

Enumerator
GP_PORT_SERIAL_PARITY_OFF 

Parity is off (disabled)

GP_PORT_SERIAL_PARITY_EVEN 

Parity is even.

GP_PORT_SERIAL_PARITY_ODD 

Parity is odd.

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