| Sun Java System LDAP SDK for C Programming Guide |
Chapter 9
Working with LDAP URLsThe Sun™ Java System LDAP SDK for C contains functions to parse a Lightweight Directory Access Protocol (LDAP) URL into its components and process a search request specified by an LDAP URL. This chapter contains information on working with LDAP URLs. It contains the following sections:
Understanding LDAP URLsAn LDAP URL is a URL that begins with the ldap:// or ldaps:// prefix and specifies a search request sent to an LDAP server. The ldap:// URL is used to connect to LDAP servers over unsecured connections, and the ldaps:// URL is used to connect to LDAP servers over Secure Sockets Layer (SSL) connections. All LDAP URLs have the following syntax:
ldap[s]://hostname:port/base_dn?attributes?scope?filter
Table 9-1 details the components.
Escaping Characters
Any unsafe characters in the URL need to be represented by a special sequence of characters (often called escaping). For example, a space must be represented as %20. Thus, the DN "ou=Product Development" must be encoded as "ou=Product%20Development".
Delimiting Fields
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 question marks delimiting that field. For example, to specify a subtree search starting from dc=example,dc=com that returns all attributes for entries matching (sn=Jensen), use:
ldap://ldap.iplanet.com/dc=example,dc=com??sub?(sn=Jensen)
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.
Note
The syntax for LDAP URLs does not include any means for specifying credentials or passwords. Search requests initiated through LDAP URLs are unauthenticated.
Examples of LDAP URLs
The following sections contain specific examples of LDAP URLs.
Specifying a Base Search
The first LDAP URL example specifies a base search for the entry with the DN dc=example,dc=com.
ldap://ldap.iplanet.com/dc=example,dc=com
Note the following about this first example:
- Because no port number is specified, the standard LDAP port number (389) is used.
- Because no attributes are specified, the search returns all attributes.
- Because no search scope is specified, the search is restricted to the base entry dc=example,dc=com.
- Because no filter is specified, the default filter (objectclass=*) is used.
Retrieving One Attribute
The second example retrieves the postalAddress attribute of the dc=example,dc=com entry.
ldap://ldap.iplanet.com/dc=example,dc=com?postalAddress
Note the following about this second example:
Retrieving Multiple Attributes
This third example retrieves the cn, mail, and telephoneNumber attributes of the entry for Barbara Jensen.
ldap://ldap.iplanet.com/uid=bjensen,ou=People,dc=example,dc=com? \
cn,mail,telephoneNumberNote the following about this third example:
Retrieving Entries from Multiple Levels
This LDAP URL specifies a search for entries that have the last name Jensen and are at any level under dc=example,dc=com.
ldap://ldap.iplanet.com/dc=example,dc=com??sub?(sn=Jensen)
Note the following about this example:
Retrieving Entries from One Level
This LDAP URL specifies a search for the object class for all entries one level under dc=example,dc=com.
ldap://ldap.iplanet.com/dc=example,dc=com?objectClass?one
Determining an LDAP URLTo determine whether a URL is an LDAP URL, call the 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. Code Example 9-1 determines if a URL is an LDAP URL.
ldap_is_ldap_url() determines whether a URL is an LDAP URL. To verify that an LDAP URL complies with the LDAP URL syntax, you should call the ldap_url_parse() function as detailed in "Getting the Components of an LDAP URL."
Getting the Components of an LDAP URLTo retrieve the individual components of an LDAP URL, call ldap_url_parse(). This function returns the LDAP URL components in an LDAPURLDesc structure as shown in Code Example 9-2.
Code Example 9-2 LDAPURLDesc Structure
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;
Table 9-2 is a list of the field descriptions.
Table 9-2 ldap_url_desc Field Descriptions
Field Name
Description
lud_host
The name of the host in the URL.
lud_port
The number of the port in the URL.
lud_dn
The distinguished name in the URL.
lud_attrs
A pointer to a NULL-terminated array of the attributes specified in the URL.
lud_scope
The scope of the search specified in the URL. This field can have the following values:
lud_filter
Search filter included in the URL.
lud_options
Options (if LDAP_URL_OPT_SECURE, indicates that the protocol is ldaps:// instead of ldap://).
Code Example 9-3 parses an LDAP URL and prints out each component of it.
Code Example 9-3 Parsing an LDAP URL
#include <stdio.h>
#include <ldap.h>
...
char *my_url = "ldap://ldap.iplanet.com:5000/dc=example,dc=com?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 in Code Example 9-3 prints out the results pictured in Code Example 9-4.
Code Example 9-4 Results of Parsing an LDAP URL
Components of the URL:
Host name: ldap.netscape.com
Port number: 5000
Base entry: dc=example,dc=com
Attributes returned:
cn
telephoneNumber
Scope of the search: sub
Filter: (sn=Jensen)
Freeing the Components of an LDAP URLWhen you have finished working with the components of an LDAP URL, you should free the LDAPURLDesc structure from memory by calling the ldap_free_urldesc() function. Code Example 9-5 parses an LDAP URL and then frees the LDAPURLDesc structure from memory after verifying that the LDAP URL is valid.
Code Example 9-5 Freeing LDAPURLDesc Structure From Memory
#include <stdio.h>
#include <ldap.h>
...
char *my_url = "ldap://ldap.netscape.com:5000/dc=example,dc=com?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 );
...
Processing an LDAP URLTo process an LDAP URL search request, call either the 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 other work. It returns LDAP_SUCCESS if the operation completed successfully. If an error occurred, the function returns an error code. (See Chapter 18, "Result 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. It 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 if 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. Code Example 9-6 processes a search request from an LDAP URL.
Code Example 9-6 Processing an LDAP URL Search Request
#include <stdio.h>
#include <ldap.h>
...
LDAP *ld;
LDAPMessage *result;
char *my_url = "ldap://ldap.netscape.com/dc=example,dc=com?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 );
}
