libgphoto2 photo camera library (libgphoto2) API: libgphoto2_port/libgphoto2_port/gphoto2-port.c File Reference

libgphoto2 photo camera library (libgphoto2) API 2.5.28

Data Structures | Macros | Functions
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 "libgphoto2_port/gphoto2-port-info.h"`
`#include "libgphoto2_port/i18n.h"`

## Data Structures
struct | _GPPortPrivateCore
| Internal private libgphoto2_port data. This structure contains private data. More...

## Macros
#define | _DEFAULT_SOURCE
#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

## ◆ FAST_TIMEOUT

#define FAST_TIMEOUT 50

The timeout in milliseconds for fast interrupt reads.

## ◆ LOG_DATA

#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__); \
else \
GP_LOG_DATA (DATA, SIZE, MSG_PRE " %i = 0x%x bytes " MSG_POST, SIZE, SIZE, ##__VA_ARGS__)
GP_LOG_DATA
@ GP_LOG_DATA
Log message is a data hex dump.
Definition: gphoto2-port-log.h:38

## 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_settings_get()

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

Deprecated

References gp_port_get_settings().

## ◆ gp_port_settings_set()

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

Deprecated

References gp_port_set_settings().

## ◆ gp_port_timeout_get()

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

Deprecated

References gp_port_get_timeout().

## ◆ gp_port_timeout_set()

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

Deprecated

References gp_port_set_timeout().

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