git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_getfilter.3

   1 .TH LDAP_GETFILTER 3 "22 September 1998" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_init_getfilter, ldap_init_getfilter_buf, ldap_getfilter_free,
   7 ldap_getfirstfilter, ldap_getnextfilter, ldap_build_filter \- LDAP filter generating routines
   8 .SH SYNOPSIS
   9 .nf
  10 .ft B
  11 #include <ldap.h>
  12 .ft
  13 .fi
  14 .LP
  15 .nf
  16 .ft B
  17 #define LDAP_FILT_MAXSIZ        1024
  18
  19 typedef struct ldap_filt_info {
  20         char                    *lfi_filter;
  21         char                    *lfi_desc;
  22         int                     lfi_scope;
  23         int                     lfi_isexact;
  24         struct ldap_filt_info   *lfi_next;
  25 } LDAPFiltInfo;
  26
  27 typedef struct ldap_filt_list {
  28     char                        *lfl_tag;
  29     char                        *lfl_pattern;
  30     char                        *lfl_delims;
  31     LDAPFiltInfo                *lfl_ilist;
  32     struct ldap_filt_list       *lfl_next;
  33 } LDAPFiltList;
  34
  35 typedef struct ldap_filt_desc {
  36         LDAPFiltList            *lfd_filtlist;
  37         LDAPFiltInfo            *lfd_curfip;
  38         LDAPFiltInfo            lfd_retfi;
  39         char                    lfd_filter[ LDAP_FILT_MAXSIZ ];
  40         char                    *lfd_curval;
  41         char                    *lfd_curvalcopy;
  42         char                    **lfd_curvalwords;
  43         char                    *lfd_filtprefix;
  44         char                    *lfd_filtsuffix;
  45 } LDAPFiltDesc;
  46 .ft
  47 .fi
  48 .LP
  49 .ft B
  50 LDAPFiltDesc *ldap_init_getfilter( file )
  51 .ft
  52 char *file;
  53 .LP
  54 .nf
  55 .ft B
  56 LDAPFiltDesc *ldap_init_getfilter_buf( buf, buflen )
  57 .ft
  58 char *buf;
  59 long buflen;
  60 .LP
  61 .ft B
  62 ldap_getfilter_free( lfdp )
  63 .ft
  64 LDAPFiltDesc *lfdp;
  65 .LP
  66 .nf
  67 .ft B
  68 LDAPFiltInfo *ldap_getfirstfilter(lfdp, tagpat, value)
  69 .ft
  70 LDAPFiltDesc *lfdp;
  71 char *tagpat;
  72 char *value;
  73 .LP
  74 .nf
  75 .ft B
  76 LDAPFiltInfo *ldap_getnextfilter(lfdp)
  77 .ft
  78 LDAPFiltDesc *lfdp;
  79 .LP
  80 .ft B
  81 void ldap_setfilteraffixes(lfdp, prefix, suffix)
  82 .ft
  83 LDAPFiltDesc *lfdp;
  84 char *prefix;
  85 char *suffix;
  86 .LP
  87 .ft B
  88 void ldap_build_filter( buf, buflen, pattern, prefix, suffix,
  89         attr, value, valwords )
  90 .ft
  91 char *buf;
  92 unsigned long buflen;
  93 char *pattern;
  94 char *prefix;
  95 char *suffix;
  96 char *attr;
  97 char *value;
  98 char **valwords;
  99 .SH DESCRIPTION
 100 .LP
 101 These routines are used to generate filters to be used in
 102 ldap_search(3) or ldap_search_s(3).  Either ldap_init_getfilter or
 103 ldap_init_getfilter_buf must be called prior to calling any of
 104 the other routines except ldap_build_filter.
 105 .LP
 106 ldap_init_getfilter()
 107 takes a file name as its only argument.  The contents of the file must
 108 be a valid LDAP filter configuration file (see ldapfilter.conf(5)).  If
 109 the file is successfully read, a pointer to an LDAPFiltDesc is
 110 returned.  This is an opaque object that is passed in subsequent get
 111 filter calls.
 112 .LP
 113 ldap_init_getfilter_buf()
 114 reads from
 115 .I buf
 116 (whose length is
 117 .I buflen)
 118 the LDAP filter configuration information.
 119 .I buf
 120 must point to the contents of a valid LDAP filter configuration file
 121 (see ldapfilter.conf(5)).  If the filter configuration information is
 122 successfully read, a pointer to an LDAPFiltDesc is returned.  This is
 123 an opaque object that is passed in subsequent get filter calls.
 124 .LP
 125 ldap_getfilter_free()
 126 deallocates the memory consumed by ldap_init_getfilter.  Once it is
 127 called, the LDAPFiltDesc is no longer valid and cannot be used again.
 128 .LP
 129 ldap_getfirstfilter()
 130 retrieves the first filter that is appropriate for
 131 .I value.
 132 Only filter sets that have tags that match the regular expession
 133 .I tagpat
 134 are considered.  ldap_getfirstfilter returns a pointer to an
 135 LDAPFiltInfo structure, which contains a filter with
 136 .I value
 137 inserted as appropriate in lfi_filter, a text match description in
 138 lfi_desc, lfi_scope set to indicate the search scope, and lfi_isexact
 139 set to indicate the type of filter.  NULL is returned
 140 if no matching filters are found.  lfi_scope will be one of
 141 .B LDAP_SCOPE_BASE,
 142 .B LDAP_SCOPE_ONELEVEL,
 143 or
 144 .B LDAP_SCOPE_SUBTREE.
 145 lfi_isexact
 146 will be zero if the filter has any '~' or '*' characters in it and
 147 non-zero otherwise.
 148 .LP
 149 ldap_getnextfilter()
 150 retrieves the next appropriate filter in the filter set that was
 151 determined when ldap_getfirstfilter was called.  It returns NULL when
 152 the list has been exhausted.
 153 .LP
 154 ldap_setfilteraffixes()
 155 sets a
 156 .I prefix
 157 to be prepended and a
 158 .I suffix
 159 to be appended to all filters returned in the future.
 160 .LP
 161 ldap_build_filter()
 162 constructs an LDAP search filter in
 163 .I buf.
 164 .I buflen
 165 is the size, in bytes, of the largest filter
 166 .I buf
 167 can hold.  A pattern for the desired filter is passed in
 168 .I pattern.
 169 Where the string %a appears in the pattern it is replaced with
 170 .I attr.
 171 .I prefix
 172 is pre-pended to the resulting filter, and
 173 .I suffix
 174 is appended.  Either can be NULL (in which case they are not used).
 175 .I value
 176 and
 177 .I valwords
 178 are used when the string %v appears in
 179 .I pattern.
 180 See ldapfilter.conf(5) for a description of how %v is handled.
 181 .LP
 182 .SH ERRORS
 183 NULL is returned by ldap_init_getfilter if there is an error reading
 184 .I file.
 185 NULL is returned by ldap_getfirstfilter and ldap_getnextfilter when there
 186 are no more appropriate filters to return.
 187 .SH NOTES
 188 .LP
 189 The return values for all of these functions are declared in the
 190 <ldap.h> header file.
 191 Some routines may dynamically allocate memory
 192 which the caller must free using the supplied deallocator routines.
 193 .SH FILES
 194 ETCDIR/ldapfilter.conf
 195 .SH SEE ALSO
 196 .BR ldap (3),
 197 .BR ldapfilter.conf (5)
 198 .SH ACKNOWLEDGEMENTS
 199 .B      OpenLDAP
 200 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 201 .B      OpenLDAP
 202 is derived from University of Michigan LDAP 3.3 Release.