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 dependency graph for gphoto2-port.c:

Defines
#define	_(String)   (String)
#define	N_(String)   (String)
#define	CHECK_RESULT(result)   {int r=(result); if (r<0) return (r);}
#define	CHECK_NULL(m)   {if (!(m)) return (GP_ERROR_BAD_PARAMETERS);}
#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	FAST_TIMEOUT   50
Functions
int	gp_port_new (GPPort **port)
	Create new GPPort.
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_free (GPPort *port)
	Free the port structure.
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_set_timeout (GPPort *port, int timeout)
	Set timeout of port.
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.
int	gp_port_set_settings (GPPort *port, GPPortSettings settings)
	Set port settings.
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.
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 Müller <lutz@users.sf.net>

Copyright 1999 Scott Fritzinger <scottf@unr.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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

---

Define Documentation

#define FAST_TIMEOUT   50

The timeout in milliseconds for fast interrupt reads.

---

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_settings_get	(	GPPort *	,
		GPPortSettings *
	)

Deprecated

int gp_port_settings_set	(	GPPort *	,
		GPPortSettings
	)

Deprecated

int gp_port_timeout_get	(	GPPort *	,
		int *
	)

Deprecated

int gp_port_timeout_set	(	GPPort *	,
		int
	)

Deprecated

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.

---