linkoptions.h File Reference

Hardware link parsing and storage. More...

#include <shareLib.h>
#include <dbDefs.h>
#include <epicsTypes.h>

Include dependency graph for linkoptions.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	linkOptionEnumType
struct	linkOptionDef

Macros
#define	linkInt32(Struct, Member, Name, Req, Over)   {Name, linkOptionInt32, Req, Over, OFFSET(Struct, Member), sizeof( ((Struct*)0)->Member ), NULL}
#define	linkDouble(Struct, Member, Name, Req, Over)   {Name, linkOptionDouble, Req, Over, OFFSET(Struct, Member), sizeof( ((Struct*)0)->Member ), NULL}
#define	linkString(Struct, Member, Name, Req, Over)   {Name, linkOptionString, Req, Over, OFFSET(Struct, Member), sizeof( ((Struct*)0)->Member ), NULL}
#define	linkEnum(Struct, Member, Name, Req, Over, Enums)   {Name, linkOptionEnum, Req, Over, OFFSET(Struct, Member), sizeof( ((Struct*)0)->Member ), Enums}
#define	linkOptionEnd   {0,linkOptionInvalid,0,0,0,0,NULL}
#define	LINKOPTIONDEBUG   1

Typedefs
typedef enum linkOption	linkOption
typedef struct linkOptionEnumType	linkOptionEnumType
typedef struct linkOptionDef	linkOptionDef

Enumerations
enum	linkOption {   linkOptionInvalid =0, linkOptionInt32, linkOptionDouble, linkOptionString,   linkOptionEnum }

Functions
epicsShareFunc int epicsShareAPI	linkOptionsStore (const linkOptionDef *opts, void *user, const char *str, int options)
	Parse a string a store the result. More...
epicsShareFunc const char *epicsShareAPI	linkOptionsEnumString (const linkOptionEnumType *Enums, int i, const char *def)
	Return the string associated with Enum 'i'. More...

Detailed Description

Hardware link parsing and storage.

Utility to parse a macLib style string ('key=val, key2=val2') and store the results directly into a user supplied struture after appropriate type conversion.

Before calling linkOptionsStore() a linkOptionDef structure must be defined for the user structure.

For example:

typedef struct myStruct { ... other stuff epicsUInt32 ival; double dval; epicsUInt32 ival2; int enumval; char strval[20]; } myStruct;

static const linkOptionEnumType colorEnum[] = { {"Red",1}, {"Green",2}, {"Blue",3}, {NULL,0} };

static const linkOptionDef myStructDef[] = { linkInt32 (myStruct, ival, "Integer" , 0, 0), linkInt32 (myStruct, ival2, "Second" , 1, 0), linkDouble(myStruct, dval, "Double" , 1, 0), linkString(myStruct, strval , "String" , 1, 0), linkEnum (myStruct, enumval, "Color" , 1, 0, colorEnum), linkOptionEnd };

Note: The 4th argument is required (1) or optional (0), the 5th whether later definitions override previous ones (1), or are an error (0).

void someFunc(const char *arg) { myStruct mine;

memset(&mine, 0, sizeof(myStruct)); // set defaults

if (linkOptionsStore(myStructDef, &mine, arg, 0)) goto error;

printf("Second=%d\n",mine->ival2); }

Would parse the string 'Second=17, Color=Green, String=Hello world, Double=4.2' and assign ival2=17, dval=4.2, enumval=2, strval="Hello world". ival is not required and since 'Integer' was not specified would not remain unchanged.

Definition in file linkoptions.h.

Macro Definition Documentation

linkDouble

#define linkDouble	(		Struct,
			Member,
			Name,
			Req,
			Over
	)		{Name, linkOptionDouble, Req, Over, OFFSET(Struct, Member), sizeof( ((Struct*)0)->Member ), NULL}

Definition at line 102 of file linkoptions.h.

linkEnum

#define linkEnum	(		Struct,
			Member,
			Name,
			Req,
			Over,
			Enums
	)		{Name, linkOptionEnum, Req, Over, OFFSET(Struct, Member), sizeof( ((Struct*)0)->Member ), Enums}

Definition at line 108 of file linkoptions.h.

linkInt32

#define linkInt32	(		Struct,
			Member,
			Name,
			Req,
			Over
	)		{Name, linkOptionInt32, Req, Over, OFFSET(Struct, Member), sizeof( ((Struct*)0)->Member ), NULL}

Definition at line 99 of file linkoptions.h.

LINKOPTIONDEBUG

#define LINKOPTIONDEBUG   1

Definition at line 114 of file linkoptions.h.

linkOptionEnd

#define linkOptionEnd   {0,linkOptionInvalid,0,0,0,0,NULL}

Definition at line 111 of file linkoptions.h.

linkString

#define linkString	(		Struct,
			Member,
			Name,
			Req,
			Over
	)		{Name, linkOptionString, Req, Over, OFFSET(Struct, Member), sizeof( ((Struct*)0)->Member ), NULL}

Definition at line 105 of file linkoptions.h.

Typedef Documentation

linkOption

typedef enum linkOption linkOption

linkOptionDef

typedef struct linkOptionDef linkOptionDef

linkOptionEnumType

typedef struct linkOptionEnumType linkOptionEnumType

Enumeration Type Documentation

linkOption

enum linkOption

Enumerator
linkOptionInvalid
linkOptionInt32
linkOptionDouble
linkOptionString
linkOptionEnum

Definition at line 76 of file linkoptions.h.

                        {
    linkOptionInvalid=0,
    linkOptionInt32,
    linkOptionDouble,
    linkOptionString,
    linkOptionEnum
} linkOption;

Function Documentation

linkOptionsEnumString()

epicsShareFunc const char* epicsShareAPI linkOptionsEnumString	(	const linkOptionEnumType *	Enums,
		int	i,
		const char *	def
	)

Return the string associated with Enum 'i'.

Parameters

Enums	A null-terminated array of string/integer pairs
i	An Enum index
def	String to be returned in 'i' isn't a valid Enum index.

Returns

A constant string

Definition at line 226 of file linkoptions.c.

{
    for(; emap && emap->name; emap++) {
        if ( i == emap->value ) {
            return emap->name;
        }
    }
    return def;
}

linkOptionsStore()

epicsShareFunc int epicsShareAPI linkOptionsStore	(	const linkOptionDef *	opts,
		void *	user,
		const char *	str,
		int	options
	)

Parse a string a store the result.

Takes the string 'str', parses it according to 'opts', then sorts the result in 'user'.

Parameters

opts	A null-terminated array of options.
user	Pointer to a structure whos member offsets are given in 'opts'
str	The string to parse
options	Some modifiers for the parsing process or 0. The only option is LINKOPTIONDEBUG.

Returns

0 Ok

-1 Fail ('user' may be partially modified)

Definition at line 135 of file linkoptions.c.

{
    MAC_HANDLE handle; /* only .debug is used */

    int status=0;
    size_t i;
    epicsUInt32 *found;
    const linkOptionDef *cur;
    char **pairs=NULL, **arg;

    for(i=0, cur=opts; cur && cur->name; i++, cur++) {}

    /* Bit array to find missing required keys */
    found=calloc( (i/32)+1, sizeof(epicsUInt32) );
    if (!found) {
        fprintf(stderr,"store_options: calloc failed\n");
        status=-1;
        goto errbitarray;
    }

    memset((void*)&handle, 0, sizeof(handle));

    if (options&LINKOPTIONDEBUG)
        handle.debug=0xff;

    /* Parses 'str' and stores the result in the array pairs.
     * The length of pairs is twice the number of pairs found.
     * Each even element is a key, each odd element is a value.
     *
     * Pair N is (pairs[2*N], pairs[2*N+1])
     *
     * After the last pair is a (NULL, NULL)
     */
    if (macParseDefns(&handle, str, &pairs)<0) {
        status=-1;
        goto errparse;
    }

    for (arg=pairs; arg && arg[0]; arg+=2) {
        int match=0;

        if (options&LINKOPTIONDEBUG)
            printf("key %s\n",arg[0]);

        for (i=0, cur=opts; !match && cur && cur->name; i++, cur++) {

            if (options&LINKOPTIONDEBUG)
                fprintf(stderr,"For option: %s\n",cur->name);

            if( strcmp(arg[0], cur->name)!=0 )
                continue;
            match=1;

            if (found[i/32]&(1<<(i%32)) && !cur->overwrite) {
                fprintf(stderr,"Option %s was already given\n",cur->name);
                status=-1;
                goto errsemantix;
            }

            found[i/32] |= 1<<(i%32);

            status=store_value(cur, user, arg[1], options);
            if (status)
                goto errsemantix;
        }

        if(!match) {
            printf("Warning: ignoring unknown INP/OUT option %s=\n", arg[0]);
        }
    }

    for (i=0, cur=opts; cur && cur->name; i++, cur++) {

        if ( !(found[i/32]&(1<<(i%32))) && cur->required ) {
            fprintf(stderr,"Missing required option %s\n",cur->name);
            status=-1;
            goto errsemantix;
        }
    }

errsemantix:
    free((void*)pairs);
errparse:
    free(found);
errbitarray:
    return status;
}