Eina value custom type example

For this example we'll be creating our own custom type of eina value. Eina value can already store struct timeval(man gettimeofday for more information) but it has no type to store struct timezone, so that's what this example will do.

Note
  Struct timezone is actually obsolete, so using it in real world programs is probably not a good idea, but this is an example so, bear with us.

To create our own custom eina value type we need to define functions to do the following operations on it:

- Setup
- Flush
- Copy
- Compare
- Set
- Get
- Conversion

Most of this functions are very simple, so let's look at them, starting with setup which only clear the memory so that we can be certain we won't be using stale data:

//Compile with:
//gcc eina_value_03.c -o eina_value_03 `pkg-config --cflags --libs eina`
#include <Eina.h>
#include <sys/time.h>
static Eina_Bool
_tz_setup(const Eina_Value_Type *type, void *mem)
{
memset(mem, 0, type->value_size);
return EINA_TRUE;
}
Eina.h
Eina Utility library.
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition: eina_types.h:539
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition: eina_types.h:527
_Eina_Value_Type
API to access values.
Definition: eina_value.h:3678

Now the flush function, which is even simpler, it does nothing, that's because there is nothing we need to do, all the necessary steps are taken by eina value itself:

static Eina_Bool
_tz_flush(const Eina_Value_Type *type EINA_UNUSED, void *mem EINA_UNUSED)
{
return EINA_TRUE;
}
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition: eina_types.h:339

Our next function, copy, is a bit more interesting, but not much, it just casts our void pointers to struct timezone pointers and does the copy:

static Eina_Bool
_tz_copy(const Eina_Value_Type *type EINA_UNUSED, const void *src, void * dst)
{
struct timezone *tzsrc = (struct timezone *)src;
struct timezone *tzdst = dst;
*tzdst = *tzsrc;
return EINA_TRUE;
}

Note
  By now you might be wondering why our functions receive void pointers instead of pointers to struct timezone, and this is a good point. The reason for this is that eina value doesn't know anything about our type so it must use a generic void pointer, casting that pointer into a proper value is the job of the implementer of the new type.

Next we have the comparison function, which compares the `tz_minuteswest` field of struct timezone, we don't compare `tz_dsttime` because that field is not used in linux:

static int
_tz_compare(const Eina_Value_Type *type EINA_UNUSED, const void *a, const void *b)
{
struct timezone tza = *(struct timezone*)a;
struct timezone tzb = *(struct timezone*)b;
if (tza.tz_minuteswest < tzb.tz_minuteswest)
return -1;
else if (tza.tz_minuteswest > tzb.tz_minuteswest)
return 1;
return 0;
}

Next we have setting, this however requires not one but rather two functions, the reason for this is because to be able to receive arguments of any type eina value uses variadic functions, so we need a function to get the argument from a va_list and another to actually to the setting.

Lets first look at the pset function which sets the received value to a pointer:

static Eina_Bool
_tz_pset(const Eina_Value_Type *type EINA_UNUSED, void *mem, const void *ptr)
{
*(struct timezone*)mem = *(struct timezone*)ptr;
return EINA_TRUE;
}

Next we have the vset function which get the argument from the va_list and passes it to the pset function:

static Eina_Bool
_tz_vset(const Eina_Value_Type *type, void *mem, va_list args)
{
const struct timezone tz = va_arg(args, struct timezone);
return _tz_pset(type, mem, &tz);
}

And now the function to get the value, a very simple copying of the value to the given pointer:

static Eina_Bool
_tz_pget(const Eina_Value_Type *type, const void *mem, void *ptr)
{
memcpy(ptr, mem, type->value_size);
return EINA_TRUE;
}

And finally our conversion function, this is our longest and most interesting one. For numeric type we simply assign the value of `tz_minuteswest` to the new type and call a set function using it:

static Eina_Bool
_tz_convert_to(const Eina_Value_Type *type EINA_UNUSED, const Eina_Value_Type *convert, const void *type_mem, void *convert_mem)
{
struct timezone v = *(struct timezone*)type_mem;
if (convert == EINA_VALUE_TYPE_UCHAR)
{
unsigned char other_mem = v.tz_minuteswest;
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
else if (convert == EINA_VALUE_TYPE_USHORT)
{
unsigned short other_mem = v.tz_minuteswest;
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
else if (convert == EINA_VALUE_TYPE_UINT)
{
unsigned int other_mem = v.tz_minuteswest;
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
else if ((convert == EINA_VALUE_TYPE_ULONG) || (convert == EINA_VALUE_TYPE_TIMESTAMP))
{
unsigned long other_mem = v.tz_minuteswest;
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
else if (convert == EINA_VALUE_TYPE_UINT64)
{
uint64_t other_mem = v.tz_minuteswest;
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
else if (convert == EINA_VALUE_TYPE_CHAR)
{
char other_mem = v.tz_minuteswest;
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
else if (convert == EINA_VALUE_TYPE_SHORT)
{
short other_mem = v.tz_minuteswest;
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
else if (convert == EINA_VALUE_TYPE_INT)
{
int other_mem = v.tz_minuteswest;
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
else if (convert == EINA_VALUE_TYPE_LONG)
{
long other_mem = v.tz_minuteswest;
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
else if (convert == EINA_VALUE_TYPE_INT64)
{
int64_t other_mem = v.tz_minuteswest;
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
else if (convert == EINA_VALUE_TYPE_FLOAT)
return eina_value_type_pset(convert, convert_mem, &v.tz_minuteswest);
else if (convert == EINA_VALUE_TYPE_DOUBLE)
EINA_VALUE_TYPE_CHAR
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_CHAR
manages char type.
Definition: eina_value.c:5600
EINA_VALUE_TYPE_INT64
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_INT64
manages integer of 64 bits type.
Definition: eina_value.c:5604
EINA_VALUE_TYPE_INT
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_INT
manages int type.
Definition: eina_value.c:5602
EINA_VALUE_TYPE_UINT
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_UINT
manages unsigned int type.
Definition: eina_value.c:5596
EINA_VALUE_TYPE_TIMESTAMP
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_TIMESTAMP
manages unsigned long type used for timestamps.
Definition: eina_value.c:5598
EINA_VALUE_TYPE_USHORT
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_USHORT
manages unsigned short type.
Definition: eina_value.c:5595
EINA_VALUE_TYPE_UCHAR
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_UCHAR
manages unsigned char type.
Definition: eina_value.c:5593
EINA_VALUE_TYPE_SHORT
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_SHORT
manages short type.
Definition: eina_value.c:5601
EINA_VALUE_TYPE_DOUBLE
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_DOUBLE
manages double type.
Definition: eina_value.c:5606
EINA_VALUE_TYPE_FLOAT
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_FLOAT
manages float type.
Definition: eina_value.c:5605
EINA_VALUE_TYPE_ULONG
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_ULONG
manages unsigned long type.
Definition: eina_value.c:5597
EINA_VALUE_TYPE_UINT64
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_UINT64
manages unsigned integer of 64 bits type.
Definition: eina_value.c:5599
EINA_VALUE_TYPE_LONG
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_LONG
manages long type.
Definition: eina_value.c:5603
eina_value_type_pset
static Eina_Bool eina_value_type_pset(const Eina_Value_Type *type, void *mem, const void *ptr)
Sets memory using type descriptor and pointer.
return eina_value_type_pset(convert, convert_mem, &v.tz_minuteswest);

Note
  It would be a good idea to add checks for over and underflow for these types and return EINA_FALSE in those cases, we omit this here for brevity.

For string types we use `snprintf()` to format our `tz_minuteswest` field and put it in a string(again `tz_dsttime` is ignored because it's not used):

else if (convert == EINA_VALUE_TYPE_STRINGSHARE ||
convert == EINA_VALUE_TYPE_STRING)
{
const char *other_mem;
char buf[64];
snprintf(buf, sizeof(buf), "%d", v.tz_minuteswest);
other_mem = buf; /* required due &buf == buf */
return eina_value_type_pset(convert, convert_mem, &other_mem);
}
EINA_VALUE_TYPE_STRING
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_STRING
manages string type.
Definition: eina_value.c:5608
EINA_VALUE_TYPE_STRINGSHARE
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_STRINGSHARE
manages stringshared string type.
Definition: eina_value.c:5607

Finally we handle any other types by returning an error in that case:

return EINA_FALSE;
}
EINA_FALSE
#define EINA_FALSE
boolean value FALSE (numerical value 0)
Definition: eina_types.h:533

Now that we have all the functions, we can populate an `Eina_Value_Type` to later use it with `eina_value_setup()`:

static Eina_Value_Type TZ_TYPE = {
EINA_VALUE_TYPE_VERSION,
sizeof(struct timezone),
"struct timezone",
_tz_setup,
_tz_flush,
_tz_copy,
_tz_compare,
_tz_convert_to,
NULL, //No convert from
_tz_vset,
_tz_pset,
_tz_pget
};
EINA_VALUE_TYPE_VERSION
#define EINA_VALUE_TYPE_VERSION
Current API version, used to validate type.
Definition: eina_value.h:3669

We can now finally use our new TZ_TYPE with eina value, so lets conclude our example by practicing that by setting its value and printing it:

int main(int argc EINA_UNUSED, char **argv EINA_UNUSED)
{
Eina_Value vtv, vtz;
struct timeval tv;
struct timezone tz;
char *s;
eina_init();
eina_value_setup(&vtv, EINA_VALUE_TYPE_TIMEVAL);
eina_value_setup(&vtz, &TZ_TYPE);
gettimeofday(&tv, &tz);
eina_value_set(&vtv, tv);
eina_value_set(&vtz, tz);
s = eina_value_to_string(&vtv);
printf("time: %s\n", s);
free(s);
s = eina_value_to_string(&vtz);
printf("timezone: %s\n", s);
free(s);
eina_value_free(&vtz);
eina_value_free(&vtv);
eina_shutdown();
}
eina_shutdown
EINA_API int eina_shutdown(void)
Shuts down the Eina library.
Definition: eina_main.c:379
eina_init
EINA_API int eina_init(void)
Initializes the Eina library.
Definition: eina_main.c:291
EINA_VALUE_TYPE_TIMEVAL
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_TIMEVAL
manages 'struct timeval' type
Definition: eina_value.c:5612
eina_value_free
EINA_API void eina_value_free(Eina_Value *value)
Frees value and its data.
Definition: eina_value.c:5645
eina_value_to_string
EINA_API char * eina_value_to_string(const Eina_Value *value)
Converts value to string.
Definition: eina_value.c:5719
eina_value_set
static Eina_Bool eina_value_set(Eina_Value *value,...)
Sets the generic value.
eina_value_setup
static Eina_Bool eina_value_setup(Eina_Value *value, const Eina_Value_Type *type)
Initializes generic value storage.
_Eina_Value
defines the contents of a value
Definition: eina_value.h:662

For the full source code see eina_value_03.c.