n LDAP URL is a URL that begins with the ldap:// protocol prefix (or ldaps://, if the server is communicating over an SSL connection) and specifies a search request sent to an LDAP server.
With the LDAP API, you can call functions that parse an LDAP URL into its components and that process a search request specified by an LDAP URL. This chapter explains how to use these functions to work with LDAP URLs. The chapter contains the following sections:
ldap:// protocol is used to connect to LDAP servers over unsecured connections, and the ldaps:// protocol is used to connect to LDAP servers over SSL connections.)
Table 7.1 lists the components of an LDAP URL.
Any "unsafe" characters in the URL need to be represented by a special sequence of characters (this is often called escaping unsafe characters). For example, a space must be represented as %20. Thus, the distinguished name "o=Ace Industry" must be encoded as "o=Ace%20Industry".
For more details on "unsafe characters", see RFC 1738, Uniform Resource Locators (URLs).
Note that <attributes>, <scope>, and <filter> are identified by their positions in the URL. If you do not want to specify any attributes, you still need to include the question marks delimiting that field.
For example, to specify a subtree search starting from "o=Ace Industry,c=US" that returns all attributes for entries matching "(sn=Jensen)", use the following URL:
ldap://ldap.netscape.com/o=Ace%20Industry,c=US??sub?(sn=Jensen)
Note that the two consecutive question marks -- ?? -- indicate that no attributes have been specified. Since no specific attributes are identified in the URL, all attributes are returned in the search.
Examples of LDAP URLs
The following LDAP URL specifies a base search for the entry with the distinguished name "o=Ace Industry, c=US".
ldap://ldap.netscape.com/o=Ace%20Industry,c=US
"(objectclass=*)" is used.
postalAddress attribute of the Ace Industry entry:
ldap://ldap.netscape.com/o=Ace%20Industry,c=US?postalAddressThe following LDAP URL retrieves the
cn, mail, and telephoneNumber attributes of the entry for Barbara Jensen:
ldap://ldap.netscape.com/cn=Barbara%20Jensen,o=Ace%20Industry,c=US?cn,mail,telephoneNumberThe following LDAP URL specifies a search for entries that have the last name
Jensen and are at any level under "o=Ace Industry,c=US":
ldap://ldap.netscape.com/o=Ace%20Industry,c=US??sub?(sn=Jensen)The following LDAP URL specifies a search for the object class for all entries one level under
"o=Ace Industry,c=US":
ldap://ldap.netscape.com/o=Ace%20Industry,c=US?objectClass?one
"(objectclass=*)" is used.
Important
The syntax for LDAP URLs does not include any means for specifying
credentials or passwords. Search requests initiated through LDAP URLs are
unauthenticated.
ldap_is_ldap_url() function. This function returns a nonzero value if the URL is an LDAP URL. If the URL is not an LDAP URL, the function returns 0.
The following section of code determines if a URL is an LDAP URL.
#include <stdio.h>
#include <ldap.h>
...
char *my_url = "ldap://ldap.netscape.com/o=Ace%20Industry,c=US";
...
if ( ldap_is_ldap_url( my_url ) != 0 ) {
printf( "%s is an LDAP URL.\n", my_url );
} else {
printf( "%s is not an LDAP URL.\n", my_url );
}
...
To verify that a URL complies with the LDAP URL syntax, you should call the ldap_url_parse() function (see "Getting the Components of a URL").
Getting the Components of a URL
To get the individual components of the URL, call the ldap_url_parse() function. This function returns the LDAP URL components in an LDAPURLDesc structure, which is shown here:
typedef struct ldap_url_desc {
char *lud_host;
int lud_port;
char *lud_dn;
char **lud_attrs;
int lud_scope;
char *lud_filter;
unsigned long lud_options;
}LDAPURLDesc;
Here is a list of the field descriptions: The following section of code parses an LDAP URL and prints out each component of the URL.
#include <stdio.h>
#include <ldap.h>
...
char *my_url = "ldap://ldap.netscape.com:5000/o=Ace%20Industry,c=US?cn,mail,telephoneNumber?sub?(sn=Jensen)";
LDAPURLDesc *ludpp;
int res, i;
...
if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) {
switch( res ){
case LDAP_URL_ERR_NOTLDAP:
printf( "URL does not begin with \"ldap://\"\n" );
break;
case LDAP_URL_ERR_NODN:
printf( "URL missing trailing slash after host or port\n" );
break;
case LDAP_URL_ERR_BADSCOPE:
printf( "URL contains an invalid scope\n" );
break;
case LDAP_URL_ERR_MEM:
printf( "Not enough memory\n" );
break;
default:
printf( "Unknown error\n" );
}
return( 1 );
}
printf( "Components of the URL:\n" );
printf( "Host name: %s\n", ludpp->lud_host );
printf( "Port number: %d\n", ludpp->lud_port );
if ( ludpp->lud_dn != NULL ) {
printf( "Base entry: %s\n", ludpp->lud_dn );
} else {
printf( "Base entry: Root DN\n" );
}
if ( ludpp->lud_attrs != NULL ) {
printf( "Attributes returned: \n" );
for ( i=0; ludpp->lud_attrs[i] != NULL; i++ ) {
printf( "\t%s\n", ludpp->lud_attrs[i] );
}
} else {
printf( "No attributes returned.\n" );
}
printf( "Scope of the search: " );
switch( ludpp->lud_scope ) {
case LDAP_SCOPE_BASE:
printf( "base\n" );
break;
case LDAP_SCOPE_ONELEVEL:
printf( "one\n" );
break;
case LDAP_SCOPE_SUBTREE:
printf( "sub\n" );
break;
default:
printf( "Unknown scope\n" );
}
printf( "Filter: %s\n", ludpp->lud_filter );
...
The code prints out the following results:
Components of the URL: Host name: ldap.netscape.com Port number: 5000 Base entry: o=Ace Industry,c=US Attributes returned: cn mail telephoneNumber Scope of the search: sub Filter: (sn=Jensen)
LDAPURLDesc structure from memory by calling the ldap_free_urldesc() function.
The following section of code parses an LDAP URL and then frees the LDAPURLDesc structure from memory after verifying that the LDAP URL is valid.
#include <stdio.h>
#include <ldap.h>
...
char *my_url = "ldap://ldap.netscape.com:5000/o=Ace%20Industry,c=US?cn,mail,telephoneNumber?sub?(sn=Jensen)";
LDAPURLDesc *ludpp;
int res, i;
...
if ( ( res = ldap_url_parse( my_url, &ludpp ) ) != 0 ) {
switch( res ){
case LDAP_URL_ERR_NOTLDAP:
printf( "URL does not begin with \"ldap://\"\n" );
break;
case LDAP_URL_ERR_NODN:
printf( "URL does not contain a distinguished name\n" );
break;
case LDAP_URL_ERR_BADSCOPE:
printf( "URL contains an invalid scope\n" );
break;
case LDAP_URL_ERR_MEM:
printf( "Not enough memory\n" );
break;
default:
printf( "Unknown error\n" );
}
return( 1 );
}
printf( "URL is a valid LDAP URL\n" );
ldap_free_urldesc( ludpp );
...
ldap_url_search_s(), ldap_url_search_st(), or ldap_url_search() function.
ldap_url_search_s() is a synchronous function that completes the search operation before returning. Call this function if you need to wait for the operation to finish before continuing.
ldap_url_search_s() function returns LDAP_SUCCESS if the
operation completed successfully. If an error occurred, the function returns
an error code. (See "Status Codes" for a complete listing of error codes.)
ldap_url_search_st() is a synchronous function that allows a certain amount of time for the completion of the search operation. Call this function if you need to wait for the operation to complete and if you want to set a timeout period for the operation.
ldap_url_search() is an asynchronous function that initiates the search operation but does not wait for the operation to complete. Call this function if you want to perform other work (in parallel) while waiting for the operation to complete.
ldap_url_search() function returns a message ID identifying the
search operation. To determine whether the operation is completed or still
in progress, call the ldap_result() function.
After the operation is completed, call the ldap_result2error()
function to determine whether the operation was successful. If the
operation completed successfully, the ldap_result2error() function
returns LDAP_SUCCESS. If an error occurred, the function returns an error
code. (See "Status Codes" for a complete listing.)
The following example processes a search request from an LDAP URL.
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
char *my_url = "ldap://ldap.netscape.com/o=Ace Industry,%20c=US?cn,mail,telephoneNumber?sub?(sn=Jensen)";
/* Process the search request in the URL. */
if ( ldap_url_search_s( ld, my_url, 0, &result ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_url_search_s" );
return( 1 );
}
Last modified: March 31, 1997
Copyright © 1997 Netscape
Communications Corporation