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

   1 .TH LDAP_URL 3 "22 September 1998" "OpenLDAP LDVERSION"
   2 .SH NAME
   3 ldap_is_ldap_url,
   4 ldap_url_parse,
   5 ldap_free_urldesc,
   6 ldap_url_search,
   7 ldap_url_search_s,
   8 ldap_url_search_st \- LDAP Uniform Resource Locator routines
   9 .SH SYNOPSIS
  10 .nf
  11 .ft B
  12 #include <lber.h>
  13 #include <ldap.h>
  14 .ft
  15 .LP
  16 .ft B
  17 int ldap_is_ldap_url( url )
  18 .ft
  19 char            *url;
  20 .LP
  21 .ft B
  22 int ldap_url_parse( url, ludpp )
  23 .ft
  24 char            *url;
  25 LDAPURLDesc     **ludpp;
  26 .LP
  27 typedef struct ldap_url_desc {
  28     char        *lud_host;      /* LDAP host to contact */
  29     int lud_port;               /* port on host */
  30     char        *lud_dn;                /* base for search */
  31     char        **lud_attrs;    /* NULL-terminate list of attributes */
  32     int lud_scope;      /* a valid LDAP_SCOPE_... value */
  33     char        *lud_filter;    /* LDAP search filter */
  34     char        *lud_string;    /* for internal use only */
  35 } LDAPURLDesc;
  36 .LP
  37 .ft B
  38 ldap_free_urldesc( ludp )
  39 .ft
  40 LDAPURLDesc     *ludp;
  41 .LP
  42 .ft B
  43 int ldap_url_search( ld, url, attrsonly )
  44 .ft
  45 LDAP            *ld;
  46 char            *url;
  47 int             attrsonly;
  48 .LP
  49 .ft B
  50 int ldap_url_search_s( ld, url, attrsonly, res )
  51 .ft
  52 LDAP            *ld;
  53 char            *url;
  54 int             attrsonly;
  55 LDAPMessage     **res;
  56 .LP
  57 .ft B
  58 int ldap_url_search_st( ld, url, attrsonly, timeout, res )
  59 .ft
  60 LDAP            *ld;
  61 char            *url;
  62 int             attrsonly;
  63 struct timeval  *timeout;
  64 LDAPMessage     **res;
  65 .SH DESCRIPTION
  66 These routines support the use of LDAP URLs (Uniform Resource Locators).
  67 LDAP URLs look like this:
  68 .nf
  69
  70   \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattributes\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP]]]
  71
  72 where:
  73   \fIhostport\fP is a host name with an optional ":portnumber"
  74   \fIdn\f is the base DN to be used for an LDAP search operation
  75   \fIattributes\fP is a comma separated list of attributes to be retrieved
  76   \fIscope\fP is one of these three strings:  base one sub (default=base)
  77   \fIfilter\f is LDAP search filter as used in a call to ldap_search(3)
  78
  79 e.g.,  ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
  80 .fi
  81 .LP
  82 URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also
  83 tolerated.
  84 .LP
  85 .B ldap_is_ldap_url()
  86 returns a non-zero value if \fIurl\fP looks like an LDAP URL (as
  87 opposed to some other kind of URL).  It can be used as a quick check
  88 for an LDAP URL; the
  89 .B ldap_url_parse()
  90 routine should be used if a more thorough check is needed.
  91 .LP
  92 .B ldap_url_parse()
  93 breaks down an LDAP URL passed in \fIurl\fP into its component pieces.
  94 If successful, zero is returned, an LDAP URL description is
  95 allocated, filled in, and \fIludpp\fP is set to point to it.  If an
  96 error occurs, one of these values is returned:
  97 .nf
  98
  99     LDAP_URL_ERR_NOTLDAP        - URL doesn't begin with "ldap://"
 100     LDAP_URL_ERR_NODN   - URL has no DN (required)
 101     LDAP_URL_ERR_BADSCOPE       - URL scope string is invalid
 102     LDAP_URL_ERR_MEM    - can't allocate memory space
 103 .fi
 104 .LP
 105 .B ldap_free_urldesc()
 106 should be called to free an LDAP URL description that was obtained from
 107 a call to
 108 .B ldap_url_parse().
 109 .LP
 110 .B ldap_url_search()
 111 initiates an asynchronous LDAP search based on the contents of the
 112 \fIurl\fP string.  This routine acts just like
 113 .BR ldap_search (3)
 114 except that many search parameters are pulled out of the URL.
 115 .LP
 116 .B ldap_url_search_s()
 117 performs a synchronous LDAP search based on the contents of the
 118 \fIurl\fP string.  This routine acts just like
 119 .BR ldap_search_s (3)
 120 except that many search parameters are pulled out of the URL.
 121 .LP
 122 .B ldap_url_search_st()
 123 performs a synchronous LDAP URL search with a specified \fItimeout\fP.
 124 This routine acts just like
 125 .BR ldap_search_st (3)
 126 except that many search parameters are pulled out of the URL.
 127 .SH SEE ALSO
 128 .BR ldap (3),
 129 .BR ldap_search (3)
 130 .LP
 131 .B An LDAP URL Format,
 132 Tim Howes and Mark Smith, December 1995.  Internet Draft (work in progress).
 133 Currently available at this URL:
 134 .nf
 135 ftp://ds.internic.net/internet-drafts/draft-ietf-asid-ldap-format-03.txt
 136 .fi
 137 .SH ACKNOWLEDGEMENTS
 138 .B      OpenLDAP
 139 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 140 .B      OpenLDAP
 141 is derived from University of Michigan LDAP 3.3 Release.