Seth Woolley's Man Viewer

ldap_getfilter(3) - ldap_build_filter, ldap_getfilter_free, ldap_getfirstfilter, ldap_getnextfilter, ldap_init_getfilter, ldap_init_getfilter_buf - LDAP filter generating routines - man 3 ldap_getfilter

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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)

References for this manual (incoming links)