Sun logo      Previous      Contents      Index      Next     

Sun Java System LDAP SDK for C Programming Guide

Chapter 10
Retrieving Server Information

The Sun™ Java System LDAP SDK for C contains functions to access and modify information about your Lightweight Directory Access Protocol (LDAP) directory server. This chapter contains information about your server attributes and how to retrieve the information. It includes the following sections:


Understanding DSEs

A directory server entry or DSE is an entry in the directory that contains information specific to the server. In a directory tree, the root of the tree is the root DSE. It is not part of any naming context. For example, it is above dc=example,dc=com in the directory tree.


Note

The root DSE is specified as part of the LDAPv3. LDAPv2 servers do not necessarily have a root DSE.


The root DSE can contain the following information:

Table 10-1 lists the types of information available in the different attributes of the root DSE.

Table 10-1  Information available in the root DSE

Attribute Name

Description of Values

namingContexts

The naming contexts supported by this server (for example, dc=example,dc=com).

altServer

LDAP URLs that identify other servers to contact if this server is unavailable.

supportedExtension

The object identifiers (OIDs) of the LDAPv3 extended operations supported by this server. If this attribute is not in the root DSE, the server does not support any extended operations.

supportedControl

The OIDs of the LDAPv3 controls supported by this server. If this attribute is not in the root DSE, the server does not support any LDAPv3 controls.

supportedSASLMechanisms

The names of the SASL mechanisms supported by the server. If this attribute is not in the root DSE, the server does not support any SASL mechanisms.

supportedLDAPVersion

The values of this attribute are the versions of the LDAP supported by this server (for example, 2 and 3).


Getting the Root DSE

This is the procedure to get the root DSE for an LDAP server.

  1. Initialize an LDAP session by calling the ldap_init() function.
  2. Turn off automatic referral handling by calling the ldap_set_option() function and setting the LDAP_OPT_REFERRALS option to LDAP_OPT_OFF.
  3. Search the directory using the following criteria:
    • Set the search scope to a base search.
    • Specify an empty string for the base DN.
    • Use the search filter (objectclass=*).

    • Note

      For details on how to use API functions to search the directory, see Chapter 5, "Searching a LDAP Directory."


  4. Check the results of the search.

Code Example 10-1 gets the root DSE for a server and prints out its attributes. The function assumes that you are passing in a valid connection handle (LDAP structure) that you have created by calling ldap_init(). The function returns 0 if successful or 1 if an error occurred.

Code Example 10-1  Getting the Root DSE Attribute Values 

int printdse( LDAP *ld )

{

int rc, i;

char *matched_msg = NULL, *error_msg = NULL;

LDAPMessage *result, *e;

BerElement *ber;

char *a;

char **vals;

char *attrs[3];

/* Verify that the connection handle is valid. */

if ( ld == NULL ) {

fprintf( stderr, "Invalid connection handle.\n" );

return( 1 );

}

/* Set automatic referral processing off. */

if ( ldap_set_option( ld, LDAP_OPT_REFERRALS, LDAP_OPT_OFF ) != 0 ) {

rc = ldap_get_lderrno( ld, NULL, NULL );

fprintf( stderr, "ldap_set_option: %s\n", ldap_err2string( rc ) );

return( 1 );

}

/* Search for the root DSE. */

attrs[0] = "supportedControl";

attrs[1] = "supportedExtension";

attrs[2] = NULL;

rc = ldap_search_ext_s( ld, "", LDAP_SCOPE_BASE, "(objectclass=*)", attrs,

0, NULL, NULL, NULL, 0, &result );

/* Check the search results. */

switch( rc ) {

/* If successful, the root DSE was found. */

case LDAP_SUCCESS:

break;

/* If the root DSE was not found, the server does not comply

with the LDAPv3 protocol. */

case LDAP_PARTIAL_RESULTS:

case LDAP_NO_SUCH_OBJECT:

case LDAP_OPERATIONS_ERROR:

case LDAP_PROTOCOL_ERROR:

printf( "LDAP server returned result code %d (%s).\n"

"This server does not support the LDAPv3 protocol.\n",

rc, ldap_err2string( rc ) );

return( 1 );

/* If any other value is returned, an error must have occurred. */

default:

fprintf( stderr, "ldap_search_ext_s: %s\n", ldap_err2string( rc ) );

return( 1 );

}

/* Since only one entry should have matched, get that entry. */

e = ldap_first_entry( ld, result );

if ( e == NULL ) {

fprintf( stderr, "ldap_search_ext_s: Unable to get root DSE.\n");

ldap_memfree( result );

return( 1 );

}

/* Iterate through each attribute in the entry. */

for ( a = ldap_first_attribute( ld, e, &ber );

a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {

/* Print each value of the attribute. */

if ((vals = ldap_get_values( ld, e, a)) != NULL ) {

for ( i = 0; vals[i] != NULL; i++ ) {

printf( "%s: %s\n", a, vals[i] );

}

/* Free memory allocated by ldap_get_values(). */

ldap_value_free( vals );

}

/* Free memory allocated by ldap_first_attribute(). */

ldap_memfree( a );

}

/* Free memory allocated by ldap_first_attribute(). */

if ( ber != NULL ) {

ber_free( ber, 0 );

}

printf( "\n" );

/* Free memory allocated by ldap_search_ext_s(). */

ldap_msgfree( result );

ldap_unbind( ld );

return( 0 );

}


Determining LDAPv3 Support

You can determine what version an LDAP server supports by getting the supportedLDAPVersion attribute from the root DSE. This attribute could contain the value 2 or 3.


Note

You do not need to authenticate or bind before searching the directory. Unlike LDAPv2, LDAPv3 states that clients do not need to bind to the server before performing LDAP operations.


Code Example 10-2 connects to an LDAP server and determines whether or not that server supports the LDAPv3.

Code Example 10-2  Determining the Supported LDAP Version 

/* Function for determining if the LDAP server supports LDAPv3.

This function returns 1 if the server supports LDAPv3 or

0 if the server does not support LDAPv3.

*/

int

check_version( char *hostname, int portnum )

{

LDAP *ld;

int i, rc, v3supported = 0;

LDAPMessage *result, *e;

BerElement *ber;

LDAPControl **serverctrls = NULL, **clntctrls = NULL;

char *a, *dn;

char **vals;

char *attrs[2];

char *filter = "(objectClass=*)";

/* Check arguments */

if ( !hostname || !hostname[0] || !portnum ) {

printf( "Error: hostname or port number not specified\n" );

return( -1 );

}

/* Get a handle to an LDAP connection. */

if ( (ld = ldap_init( hostname, portnum )) == NULL ) {

perror( "ldap_init" );

return( -1 );

}

/* Set automatic referral processing off. */

if (ldap_set_option(ld, LDAP_OPT_REFERRALS, LDAP_OPT_OFF) != LDAP_SUCCESS) {

ldap_perror( ld, "ldap_set_option" );

return( -1 );

}

/* Search for the root DSE and get the supportedLDAPVersion attribute. */

attrs[0] = "supportedLDAPVersion";

attrs[1] = NULL;

rc = ldap_search_ext_s( ld, "", LDAP_SCOPE_BASE, filter, attrs, 0,

serverctrls, clntctrls, NULL, 0, &result );

/* Check the search results. */

switch( rc ) {

/* If successful, the root DSE was found. */

case LDAP_SUCCESS:

break;

/* If the root DSE was not found, the server does not comply

with the LDAPv3 protocol. */

case LDAP_PARTIAL_RESULTS:

case LDAP_NO_SUCH_OBJECT:

case LDAP_OPERATIONS_ERROR:

case LDAP_PROTOCOL_ERROR:

ldap_perror( ld, "ldap_search_ext_s" );

return( 0 );

break;

/* If an different result code is returned, an error may have

occurred (for example, the server may be down. */

default:

ldap_perror( ld, "ldap_search_ext_s" );

return( -1 );

break;

}

/* Get the values of the supportedLDAPVersion attribute in the entry. */

if (( e = ldap_first_entry( ld, result )) != NULL &&

( a = ldap_first_attribute( ld, e, &ber )) != NULL &&

(vals = ldap_get_values( ld, e, a)) != NULL ) {

for ( i = 0; vals[i] != NULL; i++ ) {

if ( !strcmp( "3", vals[i] ) ) {

v3supported = 1;

break;

}

}

/* Free any memory allocated. */

ldap_value_free( vals );

ldap_memfree( a );

if ( ber != NULL ) {

ber_free( ber, 0 );

}

}

/* Free memory allocated by ldap_search_ext_s(). */

ldap_msgfree( result );

/* Free the ld structure. */

ldap_unbind_s( ld );

/* Return a value indicating whether or not LDAPv3 is supported. */

return( v3supported );

}

...


Getting Schema Information

In the LDAPv3, an entry can specify the schema that defines the object classes, attributes, and matching rules used by the directory. This entry is called the subschema entry. To find the DN of the subschema entry, get the subschemaSubentry operational attribute from the root DSE or any entry.


Note

See "Specifying Attributes to Retrieve" in Chapter 5, "Searching a LDAP Directory" for details on how to get attributes.


The subschema entry can have the following attributes:

For information on the the format of the attribute values, see RFC 2252 - Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions (http://www.faqs.org/rfcs/rfc2252.html).



Previous      Contents      Index      Next     


Copyright 2004 Sun Microsystems, Inc. All rights reserved.