Instrument Neutral Distributed Interface INDI  0.9.8
Typedefs | Enumerations | Functions
indidevapi.h File Reference

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

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

Go to the source code of this file.

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. More...
 
void IDDefNumber (const INumberVectorProperty *n, const char *msg,...)
 Tell client to create a number number property. More...
 
void IDDefSwitch (const ISwitchVectorProperty *s, const char *msg,...)
 Tell client to create a switch vector property. More...
 
void IDDefLight (const ILightVectorProperty *l, const char *msg,...)
 Tell client to create a light vector property. More...
 
void IDDefBLOB (const IBLOBVectorProperty *b, const char *msg,...)
 Tell client to create a BLOB vector property. More...
 
void IDSetText (const ITextVectorProperty *t, const char *msg,...)
 Tell client to update an existing text vector property. More...
 
void IDSetNumber (const INumberVectorProperty *n, const char *msg,...)
 Tell client to update an existing number vector property. More...
 
void IDSetSwitch (const ISwitchVectorProperty *s, const char *msg,...)
 Tell client to update an existing switch vector property. More...
 
void IDSetLight (const ILightVectorProperty *l, const char *msg,...)
 Tell client to update an existing light vector property. More...
 
void IDSetBLOB (const IBLOBVectorProperty *b, const char *msg,...)
 Tell client to update an existing BLOB vector property. More...
 
void IDMessage (const char *dev, const char *msg,...)
 Function Drivers call to send log messages to Clients. More...
 
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. More...
 
void IDLog (const char *msg,...)
 Function Drivers call to log a message locally. More...
 
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. More...
 
void IDSnoopBLOBs (const char *snooped_device, BLOBHandling bh)
 Function a Driver calls to control whether they will receive BLOBs from snooped devices. More...
 
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. More...
 
void IERmCallback (int callbackid)
 Remove a callback function. More...
 
int IEAddTimer (int millisecs, IE_TCF *fp, void *userpointer)
 Register a new timer function, fp, to be called with ud as argument after ms. More...
 
void IERmTimer (int timerid)
 Remove the timer with the given timerid, as returned from IEAddTimer. More...
 
int IEAddWorkProc (IE_WPF *fp, void *userpointer)
 Add a new work procedure, fp, to be called with ud when nothing else to do. More...
 
void IERmWorkProc (int workprocid)
 Remove a work procedure. More...
 
ITextIUFindText (const ITextVectorProperty *tvp, const char *name)
 Find an IText member in a vector text property. More...
 
INumberIUFindNumber (const INumberVectorProperty *nvp, const char *name)
 Find an INumber member in a number text property. More...
 
ISwitchIUFindSwitch (const ISwitchVectorProperty *svp, const char *name)
 Find an ISwitch member in a vector switch property. More...
 
ILightIUFindLight (const ILightVectorProperty *lvp, const char *name)
 Find an ILight member in a vector Light property. More...
 
IBLOBIUFindBLOB (const IBLOBVectorProperty *bvp, const char *name)
 Find an IBLOB member in a vector BLOB property. More...
 
ISwitchIUFindOnSwitch (const ISwitchVectorProperty *sp)
 Returns the first ON switch it finds in the vector switch property. More...
 
int IUFindIndex (const char *needle, char **hay, unsigned int n)
 Returns the index of the string in a string array. More...
 
int IUFindOnSwitchIndex (const ISwitchVectorProperty *sp)
 Returns the index of first ON switch it finds in the vector switch property. More...
 
void IUResetSwitch (ISwitchVectorProperty *svp)
 Reset all switches in a switch vector property to OFF. More...
 
int IUUpdateSwitch (ISwitchVectorProperty *svp, ISState *states, char *names[], int n)
 Update all switches in a switch vector property. More...
 
int IUUpdateNumber (INumberVectorProperty *nvp, double values[], char *names[], int n)
 Update all numbers in a number vector property. More...
 
int IUUpdateText (ITextVectorProperty *tvp, char *texts[], char *names[], int n)
 Update all text members in a text vector property. More...
 
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. More...
 
int IUSaveBLOB (IBLOB *bp, int size, int blobsize, char *blob, char *format)
 Function to save blob metadata in the corresponding blob. More...
 
void IUUpdateMinMax (const INumberVectorProperty *nvp)
 Function to update the min and max elements of a number in the client. More...
 
void IUSaveText (IText *tp, const char *newtext)
 Function to reliably save new text in a IText. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
int IUSnoopNumber (XMLEle *root, INumberVectorProperty *nvp)
 Update a snooped number vector property from the given XML root element. More...
 
int IUSnoopText (XMLEle *root, ITextVectorProperty *tvp)
 Update a snooped text vector property from the given XML root element. More...
 
int IUSnoopLight (XMLEle *root, ILightVectorProperty *lvp)
 Update a snooped light vector property from the given XML root element. More...
 
int IUSnoopSwitch (XMLEle *root, ISwitchVectorProperty *svp)
 Update a snooped switch vector property from the given XML root element. More...
 
int IUSnoopBLOB (XMLEle *root, IBLOBVectorProperty *bvp)
 Update a snooped BLOB vector property from the given XML root element. More...
 
void ISGetProperties (const char *dev)
 Get Device Properties. More...
 
void ISNewText (const char *dev, const char *name, char *texts[], char *names[], int n)
 Update the value of an existing text vector property. More...
 
void ISNewNumber (const char *dev, const char *name, double *doubles, char *names[], int n)
 Update the value of an existing number vector property. More...
 
void ISNewSwitch (const char *dev, const char *name, ISState *states, char *names[], int n)
 Update the value of an existing switch vector property. More...
 
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. More...
 
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. More...
 
int crackDN (XMLEle *root, char **dev, char **name, char msg[])
 Extract dev and name attributes from an XML element. More...
 
int crackIPState (const char *str, IPState *ip)
 Extract property state (Idle, OK, Busy, Alert) from the supplied string. More...
 
int crackISState (const char *str, ISState *ip)
 Extract switch state (On or Off) from the supplied string. More...
 
int crackIPerm (const char *str, IPerm *ip)
 Extract property permission state (RW, RO, WO) from the supplied string. More...
 
int crackISRule (const char *str, ISRule *ip)
 Extract switch rule (OneOfMany, OnlyOne..etc) from the supplied string. More...
 
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:

  1. 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.

  2. 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
rootThe XML element to be parsed.
devpointer to an allocated buffer to save the extracted element device name attribute. The buffer size must be at least MAXINDIDEVICE bytes.
namepointer to an allocated buffer to save the extracted elemented name attribute. The buffer size must be at least MAXINDINAME bytes.
msgpointer 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
strA string representation of the permission state.
ipPointer 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
strA string representation of the state.
ipPointer 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
strA string representation of the switch rule.
ipPointer 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
strA string representation of the switch state.
ipPointer 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.
Examples:
simpleskeleton.cpp.

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.