Description
libvxeds is the library for External Data Sources
(EDS). It converts data sources of various input types to the internal
vxeds_entry
structure used by libvxmdsync.
Structures
#include <vitalnix/libvxeds/libvxeds.h>
struct vxeds_entry {
char *username;
char *first_name;
char *surname;
char *full_name; // concatenation of first_name + surname
char *pvgrp; // private group descriptor
char *uuid; // external unique user identifier
};
Function overview
#include <libvxeds/libvxeds.h>
int vxeds_open(const char *id, const char *fmt, void **state);
int vxeds_read(void *state, struct vxeds_entry *entry);
void vxeds_close(void *state);
const char *vxeds_derivefromname(const char *filename);
vxeds_open
Open the data source identified by id
. This is
mostly a filename, but the exact interpretation depends on fmt
.
fmt
must denote the type of the data source. state
must be a pointer to a valid local variable (see example below) which is then
later to be passed on subsequent vxeds_read()
calls. Returns an
AEE code; the following extra errors can happen:
-EINVAL |
No handler registered for the format given by
fmt |
-ENOMEM |
Out of memory |
vxeds_read
Reads the next entry from the data source and returns it in
normalized form in entry
. The members of the struct
vxeds_entry
are allocated (if a string), so they must be freed
afterwards, preferably using the simple vxeds_free_entry()
. (Note:
The username is constructed within libvxmdsync.)
Returns zero on EOF, positive non-zero on success, or negative
non-zero for error. Most common is -EINVAL
if the parser has
detected an incosistency in the data source. A parsing module is free to try to
continue to read the data source after an inconsistency, or return zero on the
call following the one that returned -EINVAL
. In other words, the
return codes of repeated calls to vxeds_read()
can look as
follows:
- with recovery --
1 1 1 -EINVAL 1 1 1 0
- stop after incosistency --
1 1 1 -EINVAL 0
vxeds_close
Close the data source associated with state
.
vxeds_derivefromname
Tries to figure out the filetype from the filename and returns
a pointer to a string which could be passed as fmt
to
vxeds_open()
.
vxeds_free_entry
Frees all members of a struct vxeds_entry
.
Examples
struct vxeds_entry e;
void *eds_state;
int ret;
if((ret = vxeds_open("20060101.xml", "xml", &eds_state)) <= 0)
abort();
while((ret = vxeds_read(eds_state, &e) > 0) {
do_something(&e);
vxeds_free_entry(&e);
}
vxeds_close(eds_state);