/camera/camlib

/** \file pfcam.h
 *
 * This is the replacement for camdll.h. It will provide the API for
 * the property protocol only.
 *
 * This is (yet) work under construction.
 *
 */

#include "pftypes.h"  // Photonfocus data types
#include "api.h"


/*!
 * \mainpage PFLIB SDK Documentation
 * \version 1.0
 * \author Photonfocus AG
 * \date 02/2010
 *
 * \section intro   Introduction
 * 
 * The Photonfocus library 'PFLIB' enables an application programmer
 * to control a Photonfocus Camera's features without direct access to
 * the CameraLink (or other communication layer such as Gigabit Ethernet)
 * interface.
 * The access, in order to work with most of the frame grabbers, is
 * done by a separate COMDLL, which is a low level communication interface
 * to the frame grabber's RS232 emulation. This may be frame grabber specific,
 * and does not depend on the camera type.
 *
 * \note The API has changed from 0.x to 1.x. No 'old' function call
 *       is supported anymore. However, the 1.0 API is much simpler and
 *       flexible to handle.
 *
 * \section api   API Details
 *
 * The API interface uses the standard C convention (CDECL) interface.
 * Support for Visual Basic is not available.
 * The PFLIB is portable among different operating systems such as
 * Microsoft Windows, Linux, QNX, and other Unix versions, however,
 * this is not tested and we cannot give any support for an operating
 * system other than Microsoft Windows.
 *
 * This 1.0 version API was designed as generic as possible for any
 * device type. Therefore, we ask the reader not to be confused about
 * abstract terms as 'devices' and 'properties'. For legacy reasons,
 * the term 'camera' still appears here and there. We apologize for
 * the inconsistence.
 *
 * \subsection props   Property concept
 *
 * The device property concept (so forth 'Property') of the previous 0.x PFLIB
 * API has been refined such that all device properties are basically
 * controlled via pfDevice_GetProperty() and  pfDevice_SetProperty().
 *
 * New in this API is a tree hierarchy, that covers the following property
 * features:
 *
 * \li Properties have more extended types such as structs and arrays and
 *     can contain other Property members
 * \li Max and min values are encoded the same way in a parent/children
 *     hierarchy
 * \li Mode selections can be encoded in this tree concept as well
 *
 * \image html properties.png  "Property hierarchy"
 * \image latex properties.pdf   "Property" width=15cm
 *
 *
 * The architecture also allows to integrate user defined children types
 * to a data type via structs that allow signalling events to a specific GUI
 * element when Property was changed, etc.
 *
 * To keep the API and the library code as compact and efficient as possible,
 * the Property access happens via tokens. The token is obtained by 
 * pfProperty_ParseName() via a given name, which is defined in the name
 * space of a certain parent node. The top root node of a Property
 * hierarchy is always the device node which is obtained by pfDevice_GetRoot().
 *
 * Value passing is done via a runtime data type information capable structure
 * 'PFValue'. This structure contains a data union field and an associated
 * data type. The value is retrieved from the PFValue struct according
 * to the type field. The Property getter and setter functions of the library
 * perform a type check and return an error (#PFERR_PROPERTY_TYPE_MATCH) in
 * case of a mismatch.
 *
 * The following code sequence demonstrates how to set the exposure time
 * of a camera:
 *

\code
int setExposure(int port, float time)
{
	PFValue val;
	int error;
	TOKEN t_exp = pfProperty_ParseName(port, "ExposureTime"));

	if (t_exp == INVALID_TOKEN) return PFERR_PROPERTY_UNKNOWN;

	// Initialize Value:
	val.value.f = time;
	val.type = PF_FLOAT;

	error = pfDevice_SetProperty(port, t_exp, &val);

	return error;
}
\endcode


 *
 *
 * \subsection commonfunc Common function parameters
 *
 * Generally, the first parameter of a function whose name starts with
 * 'pfDevice_' is the current camera device handle. The struct members of
 * the camera object must NEVER be accessed directly, to preserve future
 * binary compatibility.
 *
 * If not documented otherwise, the function's return value is 
 * \li  < 0 on failure
 * \li == 0 on success
 * \li  > 0 a warning
 *
 * Functions which set a value may return #PFWARN_PROPERTY_MODIFIED, meaning
 * that the given parameter was not valid or not according to certain
 * constraints. All 'Event' children of this property should be queried via
 * pfProperty_Select(), because they may have changed.
 * In this case, the user should also read back the value that was passed
 * to pfSetProperty() which was possibly modified 'in place'.
 *
 *
 * \see ErrorHandling
 *
 */


// This trick is used for easy function wrapping..
#ifndef APIFUNC
#define APIFUNC(retval, name, parms)           \
	CAMDLL_API retval APIDECL pf##name parms;
#endif


/**
 * \defgroup PortAccess Port Access, Device Initialization
 *
 * This module contains the initialization routines for the
 * camera ports
 */

/**
 * \example example.c
 *
 * This example works with a HURRICANE-40 camera. 
 * For other cameras, check propertylist first and change code.\n
 * Propertylist: Start PFRemote1.0, press F1 for help, menu Camera Properties, select camera
 *
 */
 
/**
 * \example main.c
 *
 * A simple command line program to query and set properties.
 * 
 * \b Usage
 * \verbatim
   <programname>\endverbatim
 *                       Lists all top level properties of the device
 *
 * \verbatim
   <programname> <property_name> \endverbatim
 *
 *                       Query specified Property with name 'property'.
 *                       Children are displayed as well as its value,
 *                       if applicable.
 *
 * \verbatim
   <programname> <property> <value> \endverbatim
 *
 *                       Set specified Property with name 'property'
 *                       to value 'value'. Illegal values are caught.
 *
 *
 *
 */

/**
 * \addtogroup PortAccess
 * \{
 */

 
/** 
 *
 *  Init of all camera ports. This has to be called as first
 *
 * \param numOfPorts	Number of available camera ports
 * 
 * \return		0: successful\n
 * 			< 0: error
 *
 */
APIFUNC(int, PortInit, (int *numOfPorts))

	
/** 
 *
 *  Get information about a port (manufacturer, name, etc)
 *
 * \param port		Port number of the camera
 *
 * \param manu		Name of the manufacturer of this port
 *
 * \param mBytes	Lenght of (manu+1)
 *
 * \param name		Name of the manufacturer of this port
 *
 * \param nBytes	Lenght of (name+1)
 *
 * \param version	Version of CLALLSERIAL (0 if no ClAllSerial port)\n
 *			1 : CL_DLL_VERSION_NO_VERSION	Not a CL dll\n
 *			2 : CL_DLL_VERSION_1_0		Oct 2000 compliant\n
 *			3 : CL_DLL_VERSION_1_1  	Oct 2001 compliant\n

 * \param type		Type of this port\n
 * 			0 : ClAllSerial port\n
 * 			1 : port with clser.dll at pfremote directory\n
 *			2 : USB port\n
 *			3 : RS-232 port\n
 * 
 * \return		0: successful\n
 * 			< 0: error
 *
 */
APIFUNC(int, PortInfo, (int port, char *manu, int *mBytes, char *name, int *nBytes, int *version, int *type))


/**
 * Check if required baud rate is possible. The camera port must be opened, before checking the required baud rate
 * 
 * \param port		Port number of the camera
 *
 * \param baudrate	Baud rate to check (eg. 57600)
 *                       
 * \return		1: baud rate suporrted\n
 * 			0: baud rate not supported\n
 * 			< 0: error.
 */
APIFUNC(int, IsBaudRateSupported, (int port, int baudrate))

	
/**
 * Get current baud rate
 * 
 * \param port		Port number of the camera
 *
 * \param baudrate	Baud rate
 *                       
 * \return		0: successful\n
 * 			< 0: error.\n
 */
APIFUNC(int, GetBaudRate, (int port, int *baudrate))


/**
 * Set baud rate. The camera port must be opened, before setting the baud rate
 * 
 * \param port		Port number of the camera
 *
 * \param baudrate	Baud rate to set (eg. 57600)
 *                       
 * \return		0: successful\n
 * 			< 0: error.\n
 */
APIFUNC(int, SetBaudRate, (int port, int baudrate))


/**
 * Open Device
 * 
 * \param port		Port number of the camera
 *                       
 * \return		0: successful\n
 * 			< 0: error\n
 *                      A value > 0 means, the device was opened, but
 *                      some non blocking failure was detected (bad
 *                      device identity, etc.). In this case, some int index
 *                      device features may not be accessible, but the
 *                      it can be normally fixed via an update.
 */
APIFUNC(int, DeviceOpen, (int port))	

	
/**
 * Close device communication.
 * This should be called at the end of an application,
 * when the device is no longer accessed.
 *
 * \param port		Port number of the camera
 *
 * \return		0: success\n
 * 			< 0: error\n
 */
APIFUNC(int, DeviceClose, (int port))

/* \} */


////////////////////////////////////////////////////////////////////////////
// Prototyping NEW API (1.0)
////////////////////////////////////////////////////////////////////////////

// DLL top level stuff

APIFUNC(const char *, DeviceGetDllVersion, (int port, int *major, int *minor))	

////////////////////////////////////////////////////////////////////////////
// PROPERTY API

/**
 * \defgroup PropControl Generic Device property control
 *
 * This contains the function set necessary to control arbitrary
 * device properties.
 * 
 */

/**
 * \addtogroup PropControl
 * \{
 */

	
/**
 * Get root namespace descriptor token of current device
 *
 * This function always returns a valid token.

 * \param port	Port number of the camera 
 * 
 * \return      The root descriptor token
 *
 **/
APIFUNC(TOKEN, Device_GetRoot, (int port))


/**
 * Select a property in the property and feature hierarchy.
 *
 * This function is used to query a property inside the property hierarchy
 * which is organized in a tree. A property can have children and has always
 * a parent, except if it is the root node.
 *
 * Quick overview: To select the first child of a node, use:
 *
 * \code
     child = pfProperty_Select(port, node, node); \endcode
 *
 * To select the next children of that node:
 *
 * \code
     next = pfProperty_Select(port, node, child); \endcode
 *
 * \param port		Port number of the camera 
 * \param parent	The parent node to be queried 
 * \param prev		The node whose following (next) node shall be selected
 *                  	If the parent node is specified, its first children is
 *                  	selected.
 *
 * \return          	The next or children token, if existing, INVALID_TOKEN
 *                  	otherwise.
 **/
APIFUNC(TOKEN, Property_Select, (int port, TOKEN parent, TOKEN prev))

	
/**
 * Get a property handle (TOKEN) by name.
 *
 * \param port		Port number of the camera * 
 * \param propname	Pointer to a string containing the property name
 * 
 * \return          	The TOKEN of the property. If not existing, INVALID_TOKEN.
 *
 **/	
APIFUNC(TOKEN, Property_ParseName, (int port, const char *propname))
	

/**
 * Get the name of a property by token
 *
 * \param port		Port number of the camera
 * \param p	        The token of the property whose name is to be
 *	                queried
 *
 * \return          	Pointer to the constant property string
 * 
 **/
APIFUNC(const char *, Property_GetName, (int port, TOKEN p))


/**
 * Get the property data type by token
 *
 * \param port		Port number of the camera
 * \param p          	The property token whose type are to be queried
 *
 * \return           	The type of the property 
 *
 **/
APIFUNC(PropertyType, Property_GetType, (int port, TOKEN p))

	
/**
 * Get the property flags by token
 *
 * \param port		Port number of the camera
 * \param p          	The property token whose flags are to be queried
 *
 * \return           	The property flags
 *
 **/
APIFUNC(unsigned long, Property_GetFlags, (int port, TOKEN p))


/**
 * Get the value of a property.
 *
 * By default, a property value is owned by the caller, i.e. in case of
 * a dynamic string property, the caller is responsible for allocating the
 * proper memory and initializing the PFValue pointer field.
 * In case of a static string property, the string is owned by the
 * library, so the PFValue does not need to be initialized. See also
 * PFValue documentation.
 *
 * \param port		Port number of the camera
 * \param p          	The property token whose value is to be requested
 * \param value      	Pointer to a PFValue which contains the property value
 *                  	after successful return of this function. Note that
 *                  	in case of a non static string property, the property
 *                  	value must be initialized first.
 *
 * \return           	A standard return code
 *
 **/
APIFUNC(int, Device_GetProperty, (int port, TOKEN p, PFValue *value))

	
/**
 * Get the value of a property by string
 *
 *
 * \param port		Port number of the camera
 * \param p          	The property token whose value is to be requested
 * \param outs       	Pointer to a string which contains the property value
 *                   	string conversion after successful return of this function.
 *                   	The caller must reserve a string of the length of the
 *                   	expected value string.
 * \param len        	Length of the string that was reserved by caller
 *
 * \note             	This function only applies to simple datatypes, resp.
 *                   	only displays debugging information about some
 *                   	complex data types.
 *
 * \return          	The standard return code
 *
 **/
APIFUNC(int, Device_GetProperty_String, (int port, TOKEN p, char *outs, int len))	


/**
 * Set the value of a property.
 *
 * \param port		Port number of the camera
 * \param p          	The property token whose value is to be requested
 * \param value      	Pointer to a PFValue containing the value to be set.
 *
 * \return           	The standard return code
 *
 **/
APIFUNC(int, Device_SetProperty, (int port, TOKEN p, PFValue *value))

	
/**
 * Set the value of a property by string.
 *
 * This function parses a string and tries to match it to the
 * specified property. 
 *
 * \param port		Port number of the camera
 * \param p          	The property token whose value is to be set
 * \param string     	Pointer to a string containing the value to be set.
 *
 * \return           	The standard return code
 *
 **/
APIFUNC(int, Device_SetProperty_String, (int port, TOKEN p, const char *string))	


/* \} */

////////////////////////////////////////////////////////////////////////////
/* Non exposed low level burst read/write commands */
APIFUNC(int, Write, (int port, unsigned short addr, const unsigned char *buf, unsigned int size))
APIFUNC(int, Read, (int port, unsigned short addr, unsigned char *buf, int size))

/**
 * \defgroup Misc Auxiliary and miscellaneous functions/macros
 *
 * Auxiliary functions for handling & reporting errors.
 *
 */

/**
 * \defgroup ErrorHandling Error Handling
 *
 * Auxiliary functions for handling & reporting errors.
 *
 */

/**
 * \ingroup ErrorHandling
 * 
 **/

/**
 * Verbose error string query of an error code.
 *
 * \param error          The error code returned by a function.
 *
 * \return               Pointer to a constant string containing the error
 *                       message to the specified error code.
 *
 **/
APIFUNC(const char *, GetErrorString, (int error))


/**
 * \defgroup Aux Auxiliary functions
 *
 *
 */

/** \ingroup Aux
 *
 */

APIFUNC(int, Value_ToString, (PFValue *val, char *outs, int len))

	
/** \ingroup Aux
 * Sets camera feedback function
 *
 * The feedback function must return a value = 0, if the caller should
 * proceed. For example, a GUI based feedback routine may allow the user
 * to cancel the procedure by hitting the ESC key.
 * If the procedure was cancelled, the caller returns #PFERR_CANCEL.
 *
 * \param func pointer to a feedback function of type FeedbackFuncP
 *             If equal 0, the default dummy routine (no feedback) is set.
 * \return     the previous feedback function pointer
 */
APIFUNC(FeedbackFuncP, SetFeedback, (int port, FeedbackFuncP func))