ABCDEFGHIJKLMNOPQRSTUVWXYZ

ldap_getfirstfilter

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 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;

       void ldap_setfilteraffixes(lfdp, prefix, suffix)
       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_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 name as its only argument.  The con-
       tents  of  the file must be a valid LDAP filter 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
       subsequent 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 configuration file (see ldapfilter.conf(5)).  If
       the filter configuration 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_get-
       filter.  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 filter has any '~' or '*' characters in it and  non-zero  other-
       wise.

       ldap_getnextfilter()  retrieves the next appropriate filter in the fil-
       ter set 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 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 valwords 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_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 the
       <ldap.h> header file.  Some routines may  dynamically  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  Project
       (http://www.openldap.org/).  OpenLDAP is  derived  from  University  of
       Michigan LDAP 3.3 Release.



OpenLDAP 2.0.27-Release        22 September 1998             LDAP_GETFILTER(3)