chfPlugin.h
Channel filter simplified plugins.
Utility layer to allow an easier (reduced) interface for channel filter plugins.
Parsing the configuration arguments of a channel filter plugin is done according to an argument description table provided by the plugin. The parser stores the results directly into a user supplied structure after appropriate type conversion.
To specify the arguments, a chfPluginArgDef table must be defined for the user structure. This table has to be specified when the plugin registers.
The plugin is responsible to register an init function using epicsExportRegistrar() and the accompanying registrar() directive in the dbd, and call chfPluginRegister() from within the init function.
For example:
typedef struct myStruct { … other stuff char mode; epicsInt32 ival; double dval; epicsInt32 ival2; int enumval; char strval[20]; char boolval; } myStruct;
static const chfPluginEnumType colorEnum[] = { {“Red”,1}, {“Green”,2}, {“Blue”,3}, {NULL,0} };
static const chfPluginDef myStructDef[] = { chfTagInt32(myStruct, ival, “Integer” , ival2, 3, 0, 0), chfInt32 (myStruct, ival2, “Second” , 1, 0), chfDouble (myStruct, dval, “Double” , 1, 0), chfString (myStruct, strval , “String” , 1, 0), chfEnum (myStruct, enumval, “Color” , 1, 0, colorEnum), chfBoolean (myStruct, boolval, “Bool” , 1, 0), chfPluginEnd };
Note: The 4th argument specifies the parameter to be required (1) or optional (0), the 5th whether converting to the required type is allowed (1), or type mismatches are an error (0). Note: The “Tag” version has two additional arguments. the 4th arg specifies the tag field (integer type) inside the structure to be set, the 5th arg specifies the value to set the tag field to. Arguments 6 and 7 specify “required” and “conversion” as described above.
Defines
-
chfInt32(Struct, Member, Name, Req, Conv)
-
chfBoolean(Struct, Member, Name, Req, Conv)
-
chfDouble(Struct, Member, Name, Req, Conv)
-
chfString(Struct, Member, Name, Req, Conv)
-
chfEnum(Struct, Member, Name, Req, Conv, Enums)
-
chfTagInt32(Struct, Member, Name, Tag, Choice, Req, Conv)
-
chfTagBoolean(Struct, Member, Name, Tag, Choice, Req, Conv)
-
chfTagDouble(Struct, Member, Name, Tag, Choice, Req, Conv)
-
chfTagString(Struct, Member, Name, Tag, Choice, Req, Conv)
-
chfTagEnum(Struct, Member, Name, Tag, Choice, Req, Conv, Enums)
-
chfPluginArgEnd
-
CHFPLUGINDEBUG
Enums
Functions
-
const char *chfPluginEnumString(const chfPluginEnumType *Enums, int i, const char *def)
Return the string associated with Enum index ‘i’.
- Parameters:
Enums – A null-terminated array of string/integer pairs.
i – An Enum index.
def – String to be returned when ‘i’ isn’t a valid Enum index.
- Returns:
The string associated with ‘i’.
-
int chfPluginRegister(const char *key, const chfPluginIf *pif, const chfPluginArgDef *opts)
Register a plugin.
- Parameters:
key – The plugin name key that clients will use.
pif – Pointer to the plugin’s interface.
opts – Pointer to the configuration argument description table.
-
struct chfPluginIf
- #include <chfPlugin.h>
Channel filter simplified plugin interface.
The routines in this structure must be implemented by each filter plugin.
Public Members
-
void *(*allocPvt)(void)
Allocate private resources.
Called before parsing starts. The plugin should allocate its per-instance structures, returning a pointer to them or NULL requesting an abort of the operation.
allocPvt may be set to NULL, if no resource allocation is needed.
- Return:
Pointer to private structure, NULL if operation is to be aborted.
-
void (*freePvt)(void *pvt)
Free private resources.
Called as part of abort or shutdown. The plugin should release any resources allocated for this filter; no further calls through this interface will be made.
freePvt may be set to NULL, if no resources need to be released.
- Param pvt:
Pointer to private structure.
-
void (*parse_error)(void *pvt)
A parsing error occurred.
Called after parsing failed with an error.
- Param pvt:
Pointer to private structure.
-
int (*parse_ok)(void *pvt)
Configuration has been parsed successfully.
Called after parsing has finished ok. The plugin may check the validity of the parsed data, returning -1 to request an abort of the operation.
- Param pvt:
Pointer to private structure.
- Return:
0 for success, -1 if operation is to be aborted.
-
long (*channel_open)(dbChannel *chan, void *pvt)
Open channel.
Called as part of the channel connection setup.
- Param chan:
dbChannel for which the connection is being made.
- Param pvt:
Pointer to private structure.
- Return:
0 for success, -1 if operation is to be aborted.
-
void (*channelRegisterPre)(dbChannel *chan, void *pvt, chPostEventFunc **cb_out, void **arg_out, db_field_log *probe)
Register callbacks for pre-event-queue operation.
Called as part of the channel connection setup.
This function is called to establish the stack of plugins that an event is passed through between the database and the event queue.
The plugin must set pe_out to point to its own post-event callback in order to be called when a data update is sent from the database towards the event queue.
The plugin may find out the type of data it will receive by looking at ‘probe’. If the plugin will change the data type and/or size, it must update ‘probe’ accordingly.
- Param chan:
dbChannel for which the connection is being made.
- Param pvt:
Pointer to private structure.
- Param cb_out:
Pointer to this plugin’s post-event callback (NULL to bypass this plugin).
- Param arg_out:
Argument that must be supplied when calling this plugin’s post-event callback.
-
void (*channelRegisterPost)(dbChannel *chan, void *pvt, chPostEventFunc **cb_out, void **arg_out, db_field_log *probe)
Register callbacks for post-event-queue operation.
Called as part of the channel connection setup.
This function is called to establish the stack of plugins that an event is passed through between the event queue and the final user (CA server or database access).
The plugin must set pe_out to point to its own post-event callback in order to be called when a data update is sent from the event queue towards the final user.
The plugin may find out the type of data it will receive by looking at ‘probe’. If the plugin will change the data type and/or size, it must update ‘probe’ accordingly.
- Param chan:
dbChannel for which the connection is being made.
- Param pvt:
Pointer to private structure.
- Param cb_out:
Pointer to this plugin’s post-event callback (NULL to bypass this plugin).
- Param arg_out:
Argument that must be supplied when calling this plugin’s post-event callback.
-
void (*channel_report)(dbChannel *chan, void *pvt, int level, const unsigned short indent)
Channel report request.
Called as part of show… routines.
- Param chan:
dbChannel for which the report is requested.
- Param pvt:
Pointer to private structure.
- Param level:
Interest level.
- Param indent:
Number of spaces to print before each output line.
-
void *(*allocPvt)(void)
-
struct chfPluginEnumType
-
struct chfPluginArgDef
Public Members
-
const char *name
-
chfPluginArg optType
-
unsigned int required
-
unsigned int convert
-
unsigned int tagged
-
epicsUInt32 tagOffset
-
epicsUInt32 choice
-
epicsUInt32 dataOffset
-
epicsUInt32 size
-
const chfPluginEnumType *enums
-
const char *name