LDAP_GETFILTER(3) LDAP_GETFILTER(3)
NAME
ldap_init_getfilter, ldap_init_getfilter_buf, ldap_getfilter_free,
ldap_getfirstfilter, ldap_getnextfilter, ldap_build_filter - LDAP fil-
ter(1,3x,3x curs_util) generating routines
SYNOPSIS
#include <ldap.h>
#define LDAP_FILT_MAXSIZ 1024
typedef struct ldap_filt_info {
char *lfi_filter;
char *lfi_desc;
int lfi_scope;
int lfi_isexact;
struct ldap_filt_info *lfi_next;
} LDAPFiltInfo;
typedef struct ldap_filt_list {
char *lfl_tag;
char *lfl_pattern;
char *lfl_delims;
LDAPFiltInfo *lfl_ilist;
struct ldap_filt_list *lfl_next;
} LDAPFiltList;
typedef struct ldap_filt_desc {
LDAPFiltList *lfd_filtlist;
LDAPFiltInfo *lfd_curfip;
LDAPFiltInfo lfd_retfi;
char lfd_filter[ LDAP_FILT_MAXSIZ ];
char *lfd_curval;
char *lfd_curvalcopy;
char **lfd_curvalwords;
char *lfd_filtprefix;
char *lfd_filtsuffix;
} LDAPFiltDesc;
LDAPFiltDesc *ldap_init_getfilter( file(1,n) ) char *file(1,n);
LDAPFiltDesc *ldap_init_getfilter_buf( buf, buflen )
char *buf;
long buflen;
ldap_getfilter_free( lfdp )
LDAPFiltDesc *lfdp;
LDAPFiltInfo *ldap_getfirstfilter(lfdp, tagpat, value)
LDAPFiltDesc *lfdp;
char *tagpat;
char *value;
LDAPFiltInfo *ldap_getnextfilter(lfdp)
LDAPFiltDesc *lfdp;
void ldap_setfilteraffixes(lfdp, prefix, suffix)
LDAPFiltDesc *lfdp;
char *prefix;
char *suffix;
void ldap_build_filter( buf, buflen, pattern, prefix, suffix,
attr(1,5), value, valwords )
char *buf;
unsigned long buflen;
char *pattern;
char *prefix;
char *suffix;
char *attr(1,5);
char *value;
char **valwords;
DESCRIPTION
These routines are used to generate filters to be used in(1,8)
ldap_search(3) or ldap_search_s(3). Either ldap_init_getfilter or
ldap_init_getfilter_buf must be called prior to calling any of the
other routines except ldap_build_filter.
ldap_init_getfilter() takes a file(1,n) name as its only argument. The con-
tents of the file(1,n) must be a valid LDAP filter(1,3x,3x curs_util) configuration file(1,n) (see
ldapfilter.conf(5)). If the file(1,n) is successfully read(2,n,1 builtins), a pointer to an
LDAPFiltDesc is returned. This is an opaque object that is passed in(1,8)
subsequent get filter(1,3x,3x curs_util) calls.
ldap_init_getfilter_buf() reads from buf (whose length is buflen) the
LDAP filter(1,3x,3x curs_util) configuration information. buf must point to the contents
of a valid LDAP filter(1,3x,3x curs_util) configuration file(1,n) (see ldapfilter.conf(5)). If
the filter(1,3x,3x curs_util) configuration information is successfully read(2,n,1 builtins), a pointer to
an LDAPFiltDesc is returned. This is an opaque object that is passed
in(1,8) subsequent get filter(1,3x,3x curs_util) calls.
ldap_getfilter_free() deallocates the memory consumed by ldap_init_get-
filter. Once it is called, the LDAPFiltDesc is no longer valid and
cannot be used again.
ldap_getfirstfilter() retrieves the first filter(1,3x,3x curs_util) that is appropriate
for value. Only filter(1,3x,3x curs_util) sets that have tags that match the regular
expession tagpat are considered. ldap_getfirstfilter returns a pointer
to an LDAPFiltInfo structure, which contains a filter(1,3x,3x curs_util) with value
inserted as appropriate in(1,8) lfi_filter, a text match description in(1,8)
lfi_desc, lfi_scope set(7,n,1 builtins) to indicate the search scope, and lfi_isexact
set(7,n,1 builtins) to indicate the type of filter. NULL is returned if(3,n) no matching
filters are found. lfi_scope will be one of LDAP_SCOPE_BASE,
LDAP_SCOPE_ONELEVEL, or LDAP_SCOPE_SUBTREE. lfi_isexact will be zero
if(3,n) the filter(1,3x,3x curs_util) has any '~' or '*' characters in(1,8) it and non-zero other-
wise.
ldap_getnextfilter() retrieves the next appropriate filter(1,3x,3x curs_util) in(1,8) the fil-
ter(1,3x,3x curs_util) set(7,n,1 builtins) that was determined when ldap_getfirstfilter was called. It
returns NULL when the list has been exhausted.
ldap_setfilteraffixes() sets a prefix to be prepended and a suffix to
be appended to all filters returned in(1,8) the future.
ldap_build_filter() constructs an LDAP search filter(1,3x,3x curs_util) in(1,8) buf. buflen is
the size, in(1,8) bytes, of the largest filter(1,3x,3x curs_util) buf can hold. A pattern for
the desired filter(1,3x,3x curs_util) is passed in(1,8) pattern. Where the string(3,n) %a appears
in(1,8) the pattern it is replaced with attr. prefix is pre-pended to the
resulting filter(1,3x,3x curs_util), and suffix is appended. Either can be NULL (in(1,8) which
case they are not used). value and valwords are used when the string(3,n)
%v appears in(1,8) pattern. See ldapfilter.conf(5) for a description of how
%v is handled.
ERRORS
NULL is returned by ldap_init_getfilter if(3,n) there is an error(8,n) reading
file. NULL is returned by ldap_getfirstfilter and ldap_getnextfilter
when there are no more appropriate filters to return.
NOTES
The return values for all of these functions are declared in(1,8) the
<ldap.h> header file. Some routines may dynamically allocate memory
which the caller must free using the supplied deallocator routines.
FILES
ETCDIR/ldapfilter.conf
SEE ALSO
ldap(3,5,n)(3), ldapfilter.conf(5)
ACKNOWLEDGEMENTS
OpenLDAP is developed and maintained by The OpenLDAP Project
(http://www.openldap.org/). OpenLDAP is derived from University of
Michigan LDAP 3.3 Release.
OpenLDAP LDVERSION 22 September 1998 LDAP_GETFILTER(3)