Interface to the reference INDI C API device implementation on the Device Driver side. More...

#include "indiapi.h"
#include "lilxml.h"

Typedefs
typedef void(	IE_CBF )(int readfiledes, void *userpointer)
	Signature of a callback.
typedef void(	IE_TCF )(void *userpointer)
	Signature of a timeout caller.
typedef void(	IE_WPF )(void *userpointer)
	Signature of a work procedure function.

Enumerations
enum	BLOBHandling { B_NEVER = 0, B_ALSO, B_ONLY }
	How drivers handle BLOBs incoming from snooping drivers. More...

Functions
void	IDDefText (const ITextVectorProperty t, const char msg,...)
	Tell client to create a text vector property.
void	IDDefNumber (const INumberVectorProperty n, const char msg,...)
	Tell client to create a number number property.
void	IDDefSwitch (const ISwitchVectorProperty s, const char msg,...)
	Tell client to create a switch vector property.
void	IDDefLight (const ILightVectorProperty l, const char msg,...)
	Tell client to create a light vector property.
void	IDDefBLOB (const IBLOBVectorProperty b, const char msg,...)
	Tell client to create a BLOB vector property.
void	IDSetText (const ITextVectorProperty t, const char msg,...)
	Tell client to update an existing text vector property.
void	IDSetNumber (const INumberVectorProperty n, const char msg,...)
	Tell client to update an existing number vector property.
void	IDSetSwitch (const ISwitchVectorProperty s, const char msg,...)
	Tell client to update an existing switch vector property.
void	IDSetLight (const ILightVectorProperty l, const char msg,...)
	Tell client to update an existing light vector property.
void	IDSetBLOB (const IBLOBVectorProperty b, const char msg,...)
	Tell client to update an existing BLOB vector property.
void	IDMessage (const char dev, const char msg,...)
	Function Drivers call to send log messages to Clients.
void	IDDelete (const char dev, const char name, const char *msg,...)
	Function Drivers call to inform Clients a Property is no longer available, or the entire device is gone if name is NULL.
void	IDLog (const char *msg,...)
	Function Drivers call to log a message locally.
void	IDSnoopDevice (const char snooped_device, const char snooped_property)
	Function a Driver calls to snoop on another Device. Snooped messages will then arrive via ISSnoopDevice.
void	IDSnoopBLOBs (const char *snooped_device, BLOBHandling bh)
	Function a Driver calls to control whether they will receive BLOBs from snooped devices.
int	IEAddCallback (int readfiledes, IE_CBF fp, void userpointer)
	Register a new callback, fp, to be called with userpointer as argument when readfiledes is ready.
void	IERmCallback (int callbackid)
	Remove a callback function.
int	IEAddTimer (int millisecs, IE_TCF fp, void userpointer)
	Register a new timer function, fp, to be called with ud as argument after ms.
void	IERmTimer (int timerid)
	Remove the timer with the given timerid, as returned from IEAddTimer.
int	IEAddWorkProc (IE_WPF fp, void userpointer)
	Add a new work procedure, fp, to be called with ud when nothing else to do.
void	IERmWorkProc (int workprocid)
	Remove a work procedure.
IText *	IUFindText (const ITextVectorProperty tvp, const char name)
	Find an IText member in a vector text property.
INumber *	IUFindNumber (const INumberVectorProperty nvp, const char name)
	Find an INumber member in a number text property.
ISwitch *	IUFindSwitch (const ISwitchVectorProperty svp, const char name)
	Find an ISwitch member in a vector switch property.
ILight *	IUFindLight (const ILightVectorProperty lvp, const char name)
	Find an ILight member in a vector Light property.
IBLOB *	IUFindBLOB (const IBLOBVectorProperty bvp, const char name)
	Find an IBLOB member in a vector BLOB property.
ISwitch *	IUFindOnSwitch (const ISwitchVectorProperty *sp)
	Returns the first ON switch it finds in the vector switch property.
int	IUFindOnSwitchIndex (const ISwitchVectorProperty *sp)
	Returns the index of first ON switch it finds in the vector switch property.
void	IUResetSwitch (ISwitchVectorProperty *svp)
	Reset all switches in a switch vector property to OFF.
int	IUUpdateSwitch (ISwitchVectorProperty svp, ISState states, char *names[], int n)
	Update all switches in a switch vector property.
int	IUUpdateNumber (INumberVectorProperty nvp, double values[], char names[], int n)
	Update all numbers in a number vector property.
int	IUUpdateText (ITextVectorProperty tvp, char texts[], char *names[], int n)
	Update all text members in a text vector property.
int	IUUpdateBLOB (IBLOBVectorProperty bvp, int sizes[], int blobsizes[], char blobs[], char formats[], char names[], int n)
	Update all BLOB members in a BLOB vector property.
int	IUSaveBLOB (IBLOB bp, int size, int blobsize, char blob, char *format)
	Function to save blob metadata in the corresponding blob.
void	IUUpdateMinMax (const INumberVectorProperty *nvp)
	Function to update the min and max elements of a number in the client.
void	IUSaveText (IText tp, const char newtext)
	Function to reliably save new text in a IText.
void	IUFillSwitch (ISwitch sp, const char name, const char *label, ISState s)
	Assign attributes for a switch property. The switch's auxiliary elements will be set to NULL.
void	IUFillLight (ILight lp, const char name, const char *label, IPState s)
	Assign attributes for a light property. The light's auxiliary elements will be set to NULL.
void	IUFillNumber (INumber np, const char name, const char label, const char format, double min, double max, double step, double value)
	Assign attributes for a number property. The number's auxiliary elements will be set to NULL.
void	IUFillText (IText tp, const char name, const char label, const char initialText)
	Assign attributes for a text property. The text's auxiliary elements will be set to NULL.
void	IUFillBLOB (IBLOB bp, const char name, const char label, const char format)
	Assign attributes for a BLOB property. The BLOB's data and auxiliary elements will be set to NULL.
void	IUFillSwitchVector (ISwitchVectorProperty svp, ISwitch sp, int nsp, const char dev, const char name, const char label, const char group, IPerm p, ISRule r, double timeout, IPState s)
	Assign attributes for a switch vector property. The vector's auxiliary elements will be set to NULL.
void	IUFillLightVector (ILightVectorProperty lvp, ILight lp, int nlp, const char dev, const char name, const char label, const char group, IPState s)
	Assign attributes for a light vector property. The vector's auxiliary elements will be set to NULL.
void	IUFillNumberVector (INumberVectorProperty nvp, INumber np, int nnp, const char dev, const char name, const char label, const char group, IPerm p, double timeout, IPState s)
	Assign attributes for a number vector property. The vector's auxiliary elements will be set to NULL.
void	IUFillTextVector (ITextVectorProperty tvp, IText tp, int ntp, const char dev, const char name, const char label, const char group, IPerm p, double timeout, IPState s)
	Assign attributes for a text vector property. The vector's auxiliary elements will be set to NULL.
void	IUFillBLOBVector (IBLOBVectorProperty bvp, IBLOB bp, int nbp, const char dev, const char name, const char label, const char group, IPerm p, double timeout, IPState s)
	Assign attributes for a BLOB vector property. The vector's auxiliary elements will be set to NULL.
int	IUSnoopNumber (XMLEle root, INumberVectorProperty nvp)
	Update a snooped number vector property from the given XML root element.
int	IUSnoopText (XMLEle root, ITextVectorProperty tvp)
	Update a snooped text vector property from the given XML root element.
int	IUSnoopLight (XMLEle root, ILightVectorProperty lvp)
	Update a snooped light vector property from the given XML root element.
int	IUSnoopSwitch (XMLEle root, ISwitchVectorProperty svp)
	Update a snooped switch vector property from the given XML root element.
int	IUSnoopBLOB (XMLEle root, IBLOBVectorProperty bvp)
	Update a snooped BLOB vector property from the given XML root element.
void	ISGetProperties (const char *dev)
	Get Device Properties.
void	ISNewText (const char dev, const char name, char texts[], char names[], int n)
	Update the value of an existing text vector property.
void	ISNewNumber (const char dev, const char name, double doubles, char names[], int n)
	Update the value of an existing number vector property.
void	ISNewSwitch (const char dev, const char name, ISState states, char names[], int n)
	Update the value of an existing switch vector property.
void	ISNewBLOB (const char dev, const char name, int sizes[], int blobsizes[], char blobs[], char formats[], char *names[], int n)
	Update data of an existing blob vector property.
void	ISSnoopDevice (XMLEle *root)
	Function defined by Drivers that is called when another Driver it is snooping (by having previously called IDSnoopDevice()) sent any INDI message.
int	crackDN (XMLEle root, char dev, char *name, char msg[])
	Extract dev and name attributes from an XML element.
int	crackIPState (const char str, IPState ip)
	Extract property state (Idle, OK, Busy, Alert) from the supplied string.
int	crackISState (const char str, ISState ip)
	Extract switch state (On or Off) from the supplied string.
int	crackIPerm (const char str, IPerm ip)
	Extract property permission state (RW, RO, WO) from the supplied string.
int	crackISRule (const char str, ISRule ip)
	Extract switch rule (OneOfMany, OnlyOne..etc) from the supplied string.
const char *	pstateStr (IPState s)
const char *	sstateStr (ISState s)
const char *	ruleStr (ISRule r)
const char *	permStr (IPerm p)

Detailed Description

Interface to the reference INDI C API device implementation on the Device Driver side.

Author: Elwood C. Downey; Jasem Mutlaq

This file is divided into two main sections:

Functions the INDI device driver framework defines which the Driver may call:
- IDxxx functions to send messages to an INDI client.
- IExxx functions to implement the event driven model.
- IUxxx functions to perform handy utility functions.
Functions the INDI device driver framework calls which the Driver must define:
- ISxxx to respond to messages from a Client.

These functions are the interface to the INDI C-language Device Driver reference implementation library. Any driver that uses this interface is expected to #include "indidevapi.h" and to link with indidrivermain.o and eventloop.o. Indidevapi.h further includes indiapi.h. The former contains the prototypes for the functions documented here, although many functions take arguments defined in the latter.

These functions make it much easier to write a compliant INDI driver than starting from scratch, and also serve as a concrete example of the interactions an INDI driver, in any language, is expected to accommodate.

The reference driver framework and the optimizations made within the reference indiserver both assume and require that one driver program implements exactly one logical INDI device.

The functions in this framework fall into two broad categories. Some are functions that a driver must define because they are called by the reference framework; these functions begin with IS. The remaining functions are library utilities a driver may use to do important operations.

A major point to realize is that an INDI driver built with this framework does not contain the C main() function. As soon as a driver begins executing, it listens on stdin for INDI messages. Only when a valid and appropriate message is received will it then call the driver via one of the IS functions. The driver is then expected to respond promptly by calling one of the ID library functions. It may also use any of the IU utility functions as desired to make processing a message easier.

Rather separate from these IS, ID and IU functions are a collection of functions that utilize the notion of a callback. In a callback design, the driver registers a function with the framework to be called under certain circumstances. When said circumstances occur, the framework will call the callback function. The driver never calls these callbacks directly. These callback functions begin with IE. They can arrange for a callback function to be called under three kinds of circumstances: when a given file descriptor may be read without blocking (because either data is available or EOF has been encountered), when a given time interval has elapsed, or when the framework has nothing urgent to do. The callback functions for each circumstance must be written according to a well defined prototype since, after all, the framework must know how to call the callback correctlty.

Definition in file indidevapi.h.

Function Documentation

int crackDN	(	XMLEle *	root,
		char **	dev,
		char **	name,
		char	msg[]
	)

Extract dev and name attributes from an XML element.

Parameters

root	The XML element to be parsed.
dev	pointer to an allocated buffer to save the extracted element device name attribute. The buffer size must be at least MAXINDIDEVICE bytes.
name	pointer to an allocated buffer to save the extracted elemented name attribute. The buffer size must be at least MAXINDINAME bytes.
msg	pointer to an allocated char buffer to store error messages. The minimum buffer size is MAXRBUF.

Returns: 0 if successful, -1 if error is encountered and msg is set.

Definition at line 1057 of file indicom.c.

int crackIPerm	(	const char *	str,
		IPerm *	ip
	)

Extract property permission state (RW, RO, WO) from the supplied string.

Parameters

str	A string representation of the permission state.
ip	Pointer to IPerm structure to store the extracted permission state.

Returns: 0 if successful, -1 if error is encountered.

Definition at line 987 of file indicom.c.

int crackIPState	(	const char *	str,
		IPState *	ip
	)

Extract property state (Idle, OK, Busy, Alert) from the supplied string.

Parameters

str	A string representation of the state.
ip	Pointer to IPState structure to store the extracted property state.

Returns: 0 if successful, -1 if error is encountered.

Definition at line 964 of file indicom.c.

int crackISRule	(	const char *	str,
		ISRule *	ip
	)

Extract switch rule (OneOfMany, OnlyOne..etc) from the supplied string.

Parameters

str	A string representation of the switch rule.
ip	Pointer to ISRule structure to store the extracted switch rule.

Returns: 0 if successful, -1 if error is encountered.

Definition at line 996 of file indicom.c.

int crackISState	(	const char *	str,
		ISState *	ip
	)

Extract switch state (On or Off) from the supplied string.

Parameters

str	A string representation of the switch state.
ip	Pointer to ISState structure to store the extracted switch state.

Returns: 0 if successful, -1 if error is encountered.

Definition at line 978 of file indicom.c.

const char* permStr ( IPerm p )

Returns: Returns a string representation of the supplied permission value.

Definition at line 1034 of file indicom.c.

const char* pstateStr ( IPState s )

Returns: Returns a string representation of the supplied property state.

Definition at line 947 of file indicom.c.

const char* ruleStr ( ISRule r )

Returns: Returns a string representation of the supplied switch rule.

Definition at line 1020 of file indicom.c.

const char* sstateStr ( ISState s )

Returns: Returns a string representation of the supplied switch status.

Definition at line 1007 of file indicom.c.

Typedefs

Enumerations

Functions

Detailed Description

Function Documentation