Re: Backend API

["Pierangelo Masarati" <ando@sys-net.it>]

Looking at such an old version sounds pointless.  I wouldn't consider
anything earlier than 2.3, keeping in mind that HEAD code is changing in
some areas but the backend/overlay API is (almost) frozen now.

In general, I recommend back-bdb code be used as a reference, because it
implements (almost) all of the hooks in the most complete manner.  Some of
the hooks may not apply to some types of backends, though.

Considering 2.3/HEAD code:

> bi_entry_release_rw

releases an entry when acquired via bi_entry_get_rw; if the entry was
generated, none should be provided, and the entry will simply be freed. 
If the entry is actually stored in the backend's database, it should be
provided, and it should take care of disposing of the entry, or of
returning it to its storage, as appropriate per the "rw" parameter.

> bi_chk_referrals

This takes care of handling requests that affect referrals; usually search
operations need to treat referrals in a special manner.

> bi_acl_attribute

This was zapped out of the code long ago, since its functionality could be
provided directly by the frontend using lower level APIs; it's now back
into HEAD (but not in 2.3 yet) to ease the transition of SLAPI into an
overlay.  That should not be something one needs to take care of if the
backend implements bi_entry_get_rw.

> bi_has_subordinates

This is tells if an entry has subordinates.  It's essentially used in
filter checking and the compare replacement in the frontend if
filtering/comparing on the hasSubordinates attribute is requested.  I'd
consider it a really minor hook.

> bi_connection_init
> bi_connection_destroy.

These hooks are called whenever a connection is init'ed or destroyed to
give the backend a chance to setup/free resources it allocated during the
life of a connecton.  A clear example of their usage is given in back-ldap
and in general in all the proxy/relay backends and in the rwm overlay.

The API of most hooks is now standardized in the (Operation *, SlapReply
*) form for operation and sub-operation like hooks; in the (BackendDB *)
form for the database like hooks, or variants of the above.  For details
of each API please feel free to ask.

The *tool* hooks are used by slaptools (slapcat, slapadd, ...).  They
don't need to be provided unless a backend intends to support tool mode. 
The same applies to regular hooks, if the operation or the functionality
they provide must not be supported.  For instance, a read-only backend
doesn't need to provide bi_op_add and so.


> After browsing and looking at the source code i find very difficult to
> understand the meaning of the following hooks:
>   bi_extended
> bi_entry_release_rw
> bi_chk_referrals
> bi_acl_attribute
> bi_has_subordinates
> bi_connection_init
> bi_connection_destroy.
>  Also what is the purpose of the tool hooks.
>  I am looking at the 2.1.12 source.
>  Thanks
> Luca
>
>


-- 
Pierangelo Masarati
mailto:pierangelo.masarati@sys-net.it


    SysNet - via Dossi,8 27100 Pavia Tel: +390382573859 Fax: +390382476497