Name
ds_api - The Data Source module API, how it works, how to write a module Synopsis
First, include "ds.h" to get the ds_entry struct. Then you just need to provide these following functions to the outside world. Probing
When trying to find what the correct module for a particular file is, Neluder traverses the list of collected modules (modules found) and calls q_open() with a char * and a void ** pointer. The former argument contains the file to open (this can be anything, it is up to the module), and you can allocate *state to point to a user-defined struct. That is, a pointer to a private data area you might need. That struct may hold anything you need. It could, for example, contain the FILE * pointer to the opened file. In fact, it really should hold the pointer there, since the module may be opened again by another application and using static variables is allround bad. Functions
q_open() shall open the file or whatever it thinks of fn. Check whether the module supports the file to be read. If it is not supported, simply return 0. (Do not forget to close the file and free the state struct.) Return negative values to indicate errno. Neluder will then probe the next module. Return any positive value (1 is very suited!) for success. It is assumed that when calling q_read() for the first time, that it will get the first user from the file, so do necessary initializations. ds_entry is the structure which contains the necessary components for Neluder. Here are the fields your module must know. (There are some more, uninteresting ones.)
Birthdate is used to distinguish between two users which have the same real name. The .sgroup field is only used internally when printing the password list for new users. While reading, the module shall return 1 for each successful q_read() call, 0 to signalize EOF and negative values indicate errno (i.e. return -EIO). The ds_entry structs allocated within the module must be free()-able -- strdup() may be useful. The data put into the struct also needs to be local encoding (ISO-8859-1 mostly). Please convert if necessary (use iconv() for example). After all contents have been read, Neluder calls q_close() to shut the Data Source down. Module info
Beautify the module by using the macros MODULE_NAME(string) and MODLUE_DESC(string). This is not mandatory but that text (or "(null)" if you did not specify them) will be shown within Neluder. The one mandatory macro is MODULE_TYPE:
otherwise the module is not tagged as a Data Source one and thus will not be recognized by Neluder. Example
neluder-src/ds_xml.c contains the section "The XML data source as an example".
|