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	_GPPortSettingsDisk
	Port settings for the local disk (directories) port. More...
union	_GPPortSettings
	Union of port settings. More...
struct	_GPPort
	The GPhoto port structure. More...
Defines
#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.
typedef _GPPortSettingsSerial	GPPortSettingsSerial
	Port settings for serial ports.
typedef _GPPortSettingsUSB	GPPortSettingsUSB
	Port settings for USB ports.
typedef _GPPortSettingsDisk	GPPortSettingsDisk
	Port settings for the local disk (directories) port.
typedef _GPPortSettings	GPPortSettings
	Union of port settings.
typedef _GPPortPrivateLibrary	GPPortPrivateLibrary
typedef _GPPortPrivateCore	GPPortPrivateCore
typedef _GPPort	GPPort
	The GPhoto port structure.
typedef enum _GPPin	GPPin
	Serial pins.
typedef enum _GPLevel	GPLevel
	Level to pull specific lines.
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.
int	gp_port_free (GPPort *port)
	Free the port structure.
int	gp_port_set_info (GPPort *port, GPPortInfo info)
	Configure a port.
int	gp_port_get_info (GPPort *port, GPPortInfo *info)
	Retreives information about the port.
int	gp_port_open (GPPort *port)
	Open a port.
int	gp_port_close (GPPort *port)
	Close a port.
int	gp_port_write (GPPort *port, const char *data, int size)
	Writes a specified amount of data to a port.
int	gp_port_read (GPPort *port, char *data, int size)
	Read data from port.
int	gp_port_check_int (GPPort *port, char *data, int size)
	Check for intterupt.
int	gp_port_check_int_fast (GPPort *port, char *data, int size)
	Check for interrupt without wait.
int	gp_port_get_timeout (GPPort *port, int *timeout)
	Get the current port timeout.
int	gp_port_set_timeout (GPPort *port, int timeout)
	Set timeout of port.
int	gp_port_set_settings (GPPort *port, GPPortSettings settings)
	Set port settings.
int	gp_port_get_settings (GPPort *port, GPPortSettings *settings)
	Get the current port settings.
int	gp_port_get_pin (GPPort *port, GPPin pin, GPLevel *level)
	Get setting of specific serial PIN.
int	gp_port_set_pin (GPPort *port, GPPin pin, GPLevel level)
	Set specified serial PIN to value.
int	gp_port_send_break (GPPort *port, int duration)
	Send a break over a serial port.
int	gp_port_flush (GPPort *port, int direction)
	Flush data on serial port.
int	gp_port_usb_find_device (GPPort *port, int idvendor, int idproduct)
	Find USB device by vendor/product.
int	gp_port_usb_find_device_by_class (GPPort *port, int mainclass, int subclass, int protocol)
	Find USB device by interface class.
int	gp_port_usb_clear_halt (GPPort *port, int ep)
	Clear USB endpoint HALT condition.
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.
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.
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.
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.
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.
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.
int	gp_port_set_error (GPPort *port, const char *format,...)
	Set verbose port error message.
const char *	gp_port_get_error (GPPort *port)
	Get verbose port error message.

---

Detailed Description

Author:

Copyright 2001 Lutz Mueller <lutz@users.sf.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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

---

Define Documentation

#define PIN_CTS   GP_PIN_CTS

Deprecated:

internal define

---

Typedef Documentation

typedef GPPort gp_port

Deprecated:

internal typedef

typedef GPPortSettings gp_port_settings

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.

typedef enum _GPPortSerialParity GPPortSerialParity

Serial parity.

Parity of the serial port.

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

---