.\" Copyright (c) 2006 Fredrik Lindberg
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Id: libbirdb.3 57 2006-02-23 14:15:13Z fli $
.\"
.Dd February 22, 2006
.Dt LIBBIRDB 3 
.Os
.Sh NAME
.Nm birdb_init ,
.Nm birdb_close , 
.Nm birdb_addmod ,
.Nm birdb_delmod ,
.Nm birdb_findmod ,
.Nm birdb_getmodlistmod ,
.Nm birdb_freemodlistmod ,
.Nm birdb_cfgparse ,
.Nm birdb_freerec ,
.Nm birdb_backend_getname ,
.Nm birdb_backend_getdesc ,
.Nm birdb_backend_open ,
.Nm birdb_backend_close ,
.Nm birdb_backend_get ,
.Nm birdb_backend_freegetres ,
.Nm birdb_backend_ins ,
.Nm birdb_backend_del ,
.Nm birdb_backend_seqgetfirst ,
.Nm birdb_backend_seqgetnext ,
.Nm birdb_backend_seqfree
.Nd "BioAPI BIR database library"
.Sh LIBRARY
BioAPI BIR database library
.Pq libbirdb, -lbirdb
.Sh SYNOPSIS
.In bioapi.h
.In birdb.h
.Pp
.Ft birdb *
.Fn birdb_init "void"
.Ft void 
.Fn birdb_close "birdb *bdb"
.Ft struct birdb_mod *
.Fn birdb_addmod "birdb *bdb" "const char *path"
.Ft void 
.Fn birdb_delmod "birdb *bdb" "struct birdb_mod *bm"
.Ft struct birdb_mod ** 
.Fn birdb_getmodlist "birdb *bdb" "int *elms"
.Ft void
.Fn birdb_freemodlist "struct birdb_mod **bm"
.Ft int
.Fn birdb_cfgparse "birdb *bdb" "const char *path"
.Ft const char *
.Fn birdb_backend_getname "struct birdb_mod *bm"
.Ft const char *
.Fn birdb_backend_getdesc "struct birdb_mod *bm"
.Ft void *
.Fn birdb_backend_open "struct birdb_mod *bm" "const char *bspid" "int argc" "char *argv[]"
.Ft void
.Fn birdb_backend_close "struct birdb_mod *bm" "void *beh"
.Ft struct birdb_rec **
.Fn birdb_backend_get "struct birdb_mod *bm" "void *beh" "struct birdb_rec *rec"
.Ft void
.Fn birdb_backend_freegetres "struct birdb_mod *bm" "void *beh" "struct birdb_rec **rec"
.Ft int
.Fn birdb_backend_ins "struct birdb_mod *bm" "void *beh" "struct birdb_rec *rec"
.Ft int
.Fn birdb_backend_del "struct birdb_mod *bm" "void *beh" "struct birdb_rec *rec"
.Ft struct birdb_rec *
.Fn birdb_backend_seqgetfirst "struct birdb_mod *bm" "void *beh"
.Ft struct birdb_rec *
.Fn birdb_backend_seqgetnext "struct birdb_mod *bm" "void *beh" "struct birdb_rec *rec"
.Ft void
.Fn birdb_backend_seqfree "struct birdb_mod *bm" "void *beh" "struct birdb_rec *rec"
.Ft void
.Fn birdb_freerec "struct birdb_rec *rec"
.Sh DESCRIPTION
The BIR DB library provides module indepentant storage of BioAPI BIRs.
An API provides routines for loading/unloading and for access to backend
modules while the long-term storage of BIRs are left to the modules.
.Ss Initializing the library 
The first call must be to
.Vt birdb_init
which will return an opaque
.Vt birdb
handle which has to be used with any further calls.
This handle must be passed to 
.Vt birdb_close
when it is no longer needed.
.Ss Backend modules 
Backend modules are referenced through a pointer to a
.Vt struct birdb_mod
object.
.Pp
Loading backend modules are done with
.Vt birdb_addmod
which takes the path to the shared object as argument.
It will return a pointer to the loaded object or NULL on failure.
You do not need to save this pointer, an internal list keeps
track of loaded modules.
.Pp
A loaded module can be unloaded with
.Vt birdb_delmod
which requires a pointer to the module which is supposed to be
unloaded. 
.Pp
The special call
.Vt birdb_cfgparse
parses an birdb configuration file.
This call might load any number of backend modules and it will return
the number of loaded modules will be returned, on failure a negative
value is returned.
.Pp
The routine
.Vt bidb_getmodlist
returns an array of pointers to
.Vt struct birdb_mod
objects.
The argument
.Vt elms
is a pointer to an integer which will be set to the number of loaded
modules.
The array returned must be freed with
.Vt birdb_freemodlist
when it is no longer used.
.Ss Working with a backend 
Routines that requires interaction with a specific backend module
are prefixed with
.Vt birdb_backend.
Each backend module has a unique identifier and a human-readable description
string.
.Vt birdb_backend_getname
returns the unique identifier.
.Vt birdb_backend_getdesc
returns an descriptive string of what the module does.
.Pp
Before insertion/deletion of records can be done with the backend module
it has to be opened.
This is done with
.Vt birdb_backend_open
which requires a pointer to the module, the BioAPI BSP UUID used and optional
module dependend arguments specified by
.Vt argc
and
.Vt argv.
This function returns a private module dependant handle which should be
supplied with any further access to this module.
.Pp
The function
.Vt birdb_backend_close
must be used to close a backend previously opened by
.Vt birdb_backend_open
.Pp
Further access to the backend requires a BIR DB record,
.Vt struct birdb_rec : 
.Bd -literal -offset indent
struct birdb_rec {
	time_t br_ctime; /* Creation time */
	char    *br_key; /* Key (username) */ 
	BioAPI_BIR *br_bir; /* BioAPI BIR */
};

.Ed
The
.Vt br_key
field together with
.Vt br_ctime
forms the unique key for a record. 
.Pp
.Vt birdb_backend_get
uses the
.Vt br_key
field and returns a NULL terminated list of partial matches.
This list must be freed with with
.Vt birdb_backend_freegetres.
.Pp
Inserting a new record is done with
.Vt birdb_backend_ins,
it requires a complete
.Vt struct birdb_rec
including the BioAPI BIR.
.Vt br_ctime
will be set automatically.
Zero is returned on success, otherwise a non-zero value.
.Pp
Removing a record is done with
.Vt birdb_backend_del.
The fields
.Vt br_key
and
.Vt br_ctime
must identify the record to be removed.
Other fields are ignored and may contain any data.
Zero is returned on success, otherwise a non-zero value.
.Pp
Traversing the list of avaiable records can be done with
.Vt birdb_backend_seqgetfirst
and
.Vt birdb_backend_seqgetnext.
Call
.Vt birdb_backend_seqgetfirst
to get the logical first record, pass the returned result to
.Vt birdb_backend_seqgetnext
to obtain the logical next record.
If no more records are avaiable NULL will be returned.
When finished (even if the whole list is traversed) you should call
.Vt
birdb_backend_seqfree 
to let the backend free any allocated resources.
.Pp
.Vt birdb_freerec
frees all resources allocated to a
.Vt struct birdb_rec
object.
.Ss Writing backend modules 
The following glue is the core of a backend module, all fields are required
.Bd -literal -offset indent
BIRDB_BACKEND_PARAMS = {
    char *be_name; 
    char *be_desc;
    void * (*be_open) (const char *, int, char *[]);
    void (*be_close) (void *);
    struct birdb_rec ** (*be_get) (void *, struct birdb_rec *);
    void (*be_freegetres) (void *, struct birdb_rec **);
    int (*be_ins) (void *, struct birdb_rec *);
    int (*be_del) (void *, struct birdb_rec *);
    struct birdb_rec * (*be_seqgetfirst) (void *);
    struct birdb_rec * (*be_seqgetnext) (void *, struct birdb_rec *);
    void (*be_seqfree) (void *, struct birdb_rec *);
};

.Ed
.Vt be_name
and
.Vt be_desc
should be set to a unique identifier and a descrptive string respectively.
.Pp
.Vt be_open
should allocate a new handle and perform initialization needed before get/set.
.Vt be_close
should perform clean up routines and free the allocated handle.
.Pp
.Vt be_get
should return an array of
.Vt struct birdb_rec
objects which match the field
.Vt br_key.
Any resources allocated by
.Vt be_get
should be freed by
.Vt be_freegetres.
.Pp
.Vt be_ins
should insert the new record and save it with the modules long-term storage.
.Vt be_del
should remove the record matching the fields
.Vt br_key
and
.Vt br_ctime 
from the modules long-term storage.
.Pp
.Vt be_seqgetfirst
should return the logical first record and
.Vt be_seqgetnext
should return the logical next record or NULL when no more records are
avaiable.
.Vt be_seqfree
should free resources allocated by be_seqgetnext.
.Sh AUTHORS
Written by Fredrik Lindberg for pam_bsdbioapi
.Sh SEE ALSO
.Xr bbdm 1
.Xr pam_bsdbioapi 8