libgphoto2 photo camera library (libgphoto2) API 2.5.30

Data Structures | Macros | Typedefs | Enumerations | Functions
gphoto2-port.h File Reference
`#include <gphoto2/gphoto2-port-info-list.h>`
`#include <gphoto2/gphoto2-port-portability.h>`

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

## ◆ PIN_CTS

#define PIN_CTS GP_PIN_CTS

Deprecated:
  internal define

## Typedef Documentation

## ◆ gp_port

typedef GPPort gp_port

Deprecated:
  internal typedef

## ◆ gp_port_settings

typedef GPPortSettings gp_port_settings

Deprecated:
  internal typedef

## ◆ GPLevel

typedef enum _GPLevel GPLevel

Level to pull specific lines.

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

## ◆ GPPin

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.

## ◆ GPPort

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.

## ◆ GPPortSerialParity

typedef enum _GPPortSerialParity GPPortSerialParity

Serial parity.

Parity of the serial port.

## ◆ GPPortSettings

typedef union _GPPortSettings GPPortSettings

Union of port settings.

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

## Enumeration Type Documentation

## ◆ anonymous enum

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.

## ◆ _GPLevel

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)

## ◆ _GPPin

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.

## ◆ _GPPortSerialParity

enum _GPPortSerialParity

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

## ◆ gp_port_check_int()

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

Check for intterupt.

Parameters

  port | a GPPort
  data | a pointer to an allocated buffer
  size | the 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(), and GP_LOG_DATA.

## ◆ gp_port_check_int_fast()

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

Check for interrupt without wait.

Parameters

  port | a GPPort
  data | a pointer to an allocated buffer
  size | the 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 gp_log(), and GP_LOG_DATA.

## ◆ gp_port_close()

int gp_port_close | ( | GPPort * | port | ) |

Close a port.

Parameters

  port | a GPPort

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

Returns
  a gphoto2 error code

Referenced by gp_camera_exit(), and gp_port_free().

## ◆ gp_port_flush()

int gp_port_flush | ( | GPPort * | port,
|  | int | direction
| ) |  |

Flush data on serial port.

Parameters

  port | a GPPort
  direction | the direction of the flush

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

Returns
  a gphoto2 error code

## ◆ gp_port_free()

int gp_port_free | ( | GPPort * | port | ) |

Free the port structure.

Parameters

  port | a GPPort

Closes the port and frees the memory.

Returns
  a gphoto2 error code

References gp_port_close(), _GPPortPrivateCore::ops, and _GPPort::pc.

Referenced by gp_camera_free(), and gp_port_new().

## ◆ gp_port_get_error()

const char * gp_port_get_error | ( | GPPort * | port | ) |

Get verbose port error message.

Parameters

  port | a 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.

## ◆ gp_port_get_info()

int gp_port_get_info | ( | GPPort * | port,
|  | GPPortInfo * | info
| ) |  |

Retreives information about the port.

Retrieves the informations set by gp_port_set_info().

Parameters

  port | a GPPort
  info | GPPortInfo

Returns
  a gphoto2 error code

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

## ◆ gp_port_get_pin()

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

Get setting of specific serial PIN.

Parameters

  port | a GPPort
  pin | the serial pin to be retrieved
  level | the setting of the pin

Returns
  a gphoto2 error code

## ◆ gp_port_get_settings()

int gp_port_get_settings | ( | GPPort * | port,
|  | GPPortSettings * | settings
| ) |  |

Get the current port settings.

Parameters

  port | a GPPort
  settings | pointer 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_port_settings_get().

## ◆ gp_port_get_timeout()

int gp_port_get_timeout | ( | GPPort * | port,
|  | int * | timeout
| ) |  |

Get the current port timeout.

Parameters

  port | a GPPort
  timeout | pointer 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().

## ◆ gp_port_new()

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

  port | Pointer the GPPort* pointer

Returns
  a gphoto2 error code

References GP_ERROR_NO_MEMORY, GP_OK, and gp_port_free().

## ◆ gp_port_open()

int gp_port_open | ( | GPPort * | port | ) |

Open a port.

Parameters

  port | a 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

Referenced by gp_camera_exit().

## ◆ gp_port_read()

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

Read data from port.

Parameters

  port | a GPPort
  data | a pointer to an allocated buffer
  size | the 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(), and GP_LOG_DATA.

## ◆ gp_port_reset()

int gp_port_reset | ( | GPPort * | port | ) |

Reset a port.

Parameters

  port | a GPPort

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

Returns
  a gphoto2 error code

## ◆ gp_port_seek()

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

Seek on a port (for usb disk direct ports)

Parameters

  port | a GPPort
  offset | offset to seek to
  whence | the underlying lseek call whence parameter

Seeks to a specific offset on the usb disk

Returns
  a gphoto2 error code

## ◆ gp_port_send_break()

int gp_port_send_break | ( | GPPort * | port,
|  | int | duration
| ) |  |

Send a break over a serial port.

Parameters

  port | a GPPort
  duration | duration of break in milliseconds

Sends a break with the specified duration in milliseconds.

Returns
  a gphoto2 error code

## ◆ gp_port_send_scsi_cmd()

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

  port | a GPPort
  to_dev | data 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.
  cmd | buffer holding the command to send
  cmd_size | sizeof cmd buffer
  sense | buffer for returning scsi sense information
  sense_size | sizeof sense buffer
  data | buffer 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.

## ◆ gp_port_set_error()

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

Set verbose port error message.

Parameters

  port | a GPPort
  format | printf 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, and _GPPort::pc.

## ◆ gp_port_set_info()

int gp_port_set_info | ( | GPPort * | port,
|  | GPPortInfo | info
| ) |  |

Configure a port.

Makes a port functional by passing in the necessary path information (from the serial:/dev/ttyS0 or similar variables). After calling this function, you can access the port using for example gp_port_open().

Parameters

  port | a GPPort
  info | the GPPortInfo to set

Returns
  a gphoto2 error code

## ◆ gp_port_set_pin()

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

Set specified serial PIN to value.

Parameters

  port | a GPPort
  pin | the serial pin to be retrieved
  level | the setting of the pin

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

Returns
  a gphoto2 error code

## ◆ gp_port_set_settings()

int gp_port_set_settings | ( | GPPort * | port,
|  | GPPortSettings | settings
| ) |  |

Set port settings.

Parameters

  port | a GPPort
  settings | the 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

Referenced by gp_port_settings_set().

## ◆ gp_port_set_timeout()

int gp_port_set_timeout | ( | GPPort * | port,
|  | int | timeout
| ) |  |

Set timeout of port.

Parameters

  port | a GPPort
  timeout | the 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, and _GPPort::timeout.

Referenced by gp_port_timeout_set().

## ◆ gp_port_usb_clear_halt()

int gp_port_usb_clear_halt | ( | GPPort * | port,
|  | int | ep
| ) |  |

Clear USB endpoint HALT condition.

Parameters

  port | a GPPort
  ep | endpoint to clear HALT

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

Returns
  a gphoto2 error code

## ◆ gp_port_usb_find_device()

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

Find USB device by vendor/product.

Parameters

  port | a GPPort
  idvendor | USB vendor id
  idproduct | USB product id

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

Returns
  a gphoto2 error code

## ◆ gp_port_usb_find_device_by_class()

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

Find USB device by interface class.

Parameters

  port | a GPPort
  mainclass | the USB interface class
  subclass | the USB interface subclass
  protocol | the USB interface protocol

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

Returns
  a gphoto2 error code

## ◆ gp_port_usb_msg_class_read()

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

  port | a GPPort
  request | control request code
  value | control value
  index | control index
  bytes | pointer to data
  size | size of the data

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

Returns
  a gphoto2 error code

References gp_log(), and GP_LOG_DATA.

## ◆ gp_port_usb_msg_class_write()

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

  port | a GPPort
  request | control request code
  value | control value
  index | control index
  bytes | pointer to data
  size | size of the data

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

Returns
  a gphoto2 error code

References GP_LOG_DATA.

## ◆ gp_port_usb_msg_interface_read()

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

  port | a GPPort
  request | control request code
  value | control value
  index | control index
  bytes | pointer to data
  size | size of the data

Sends a specific USB control command and read associated data.

Returns
  a gphoto2 error code

References gp_log(), and GP_LOG_DATA.

## ◆ gp_port_usb_msg_interface_write()

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

  port | a GPPort
  request | control request code
  value | control value
  index | control index
  bytes | pointer to data
  size | size of the data

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

Returns
  a gphoto2 error code

References GP_LOG_DATA.

## ◆ gp_port_usb_msg_read()

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

  port | a GPPort
  request | control request code
  value | control value
  index | control index
  bytes | pointer to data
  size | size of the data

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

Returns
  a gphoto2 error code

References gp_log(), and GP_LOG_DATA.

## ◆ gp_port_usb_msg_write()

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

  port | a GPPort
  request | control request code
  value | control value
  index | control index
  bytes | pointer to data
  size | size of the data

Sends a specific USB control command and write associated data.

Returns
  a gphoto2 error code

References GP_LOG_DATA.

## ◆ gp_port_write()

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

Writes a specified amount of data to a port.

Parameters

  port | a GPPort
  data | the data to write to the port
  size | the 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(), and GP_LOG_DATA.