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

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