ldap_init_getfilter, ldap_init_getfilter_buf, ldap_getfil
ter_free, ldap_getfirstfilter, ldap_getnextfilter,
ldap_build_filter - LDAP filter 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 ) char *file;
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;
LDAPFiltDesc *lfdp;
char *prefix;
char *suffix;
void ldap_build_filter( buf, buflen, pattern, prefix, suffix,
attr, value, valwords )
char *buf;
unsigned long buflen;
char *pattern;
char *prefix;
char *suffix;
char *attr;
char *value;
char **valwords;
DESCRIPTION
These routines are used to generate filters to be used in
ldap_search(3) or ldap_search_s(3). Either ldap_init_get
filter or ldap_init_getfilter_buf must be called prior to
calling any of the other routines except ldap_build_fil
ter.
ldap_init_getfilter() takes a file name as its only argu
ment. The contents of the file must be a valid LDAP fil
ter configuration file (see ldapfilter.conf(5)). If the
file is successfully read, a pointer to an LDAPFiltDesc is
returned. This is an opaque object that is passed in sub
sequent get filter calls.
ldap_init_getfilter_buf() reads from buf (whose length is
buflen) the LDAP filter configuration information. buf
must point to the contents of a valid LDAP filter configu
ration file (see ldapfilter.conf(5)). If the filter con
figuration information is successfully read, a pointer to
an LDAPFiltDesc is returned. This is an opaque object
that is passed in subsequent get filter calls.
ldap_getfilter_free() deallocates the memory consumed by
ldap_init_getfilter. Once it is called, the LDAPFiltDesc
is no longer valid and cannot be used again.
ldap_getfirstfilter() retrieves the first filter that is
appropriate for value. Only filter 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 with value inserted as
appropriate in lfi_filter, a text match description in
lfi_desc, lfi_scope set to indicate the search scope, and
lfi_isexact set to indicate the type of filter. NULL is
returned if 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 the fil
ter has any '~' or '*' characters in it and non-zero
ldap_getnextfilter() retrieves the next appropriate filter
in the filter set that was determined when ldap_getfirst
filter 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 the
future.
ldap_build_filter() constructs an LDAP search filter in
buf. buflen is the size, in bytes, of the largest filter
buf can hold. A pattern for the desired filter is passed
in pattern. Where the string %a appears in the pattern it
is replaced with attr. prefix is pre-pended to the
resulting filter, and suffix is appended. Either can be
NULL (in which case they are not used). value and val
words are used when the string %v appears in pattern. See
ldapfilter.conf(5) for a description of how %v is handled.
ERRORS
NULL is returned by ldap_init_getfilter if there is an
error reading file. NULL is returned by ldap_getfirstfil
ter and ldap_getnextfilter when there are no more appro
priate filters to return.
NOTES
The return values for all of these functions are declared
in the <ldap.h> header file. Some routines may dynami
cally allocate memory which the caller must free using the
supplied deallocator routines.
FILES
/etc/openldap/ldapfilter.conf
SEE ALSO
ldap(3), ldapfilter.conf(5)
ACKNOWLEDGEMENTS
OpenLDAP is developed and maintained by The OpenLDAP Pro
ject (http://www.openldap.org/). OpenLDAP is derived from
University of Michigan LDAP 3.3 Release.
Man(1) output converted with
man2html