CONTENTSThese release notes include:
SUPPORTED PLATFORMSThe LDAP SDK for C, version 4.1 provides support for the following platforms:
INSTALLING THE SDKFollow these instructions to install the Netscape LDAP SDK for C:
Note that you should install this version of the LDAP SDK for C into a different directory than any other installed version of this software.
NEW FEATURES AND ENHANCEMENTSThis section of enhancements details the changes that were made to both versions 4.0 and 4.1 of the LDAP SDK for C. The following set of modifications were made to the LDAP SDK for C, version 4.1:
The following set of modifications were made to the LDAP SDK for C, version 4.0:
LDAP_X_OPT_CONNECT_TIMEOUTThe LDAP SDK for C, v4.1 provides a new option that allows you to control the TCP/IP timeout. Normally connection attempts will block for a period of time when the connection is for a host that is not reachable. LDAP_X_OPT_CONNECT_TIMEOUT allows you to control the amount of time for which a connection attempt will block in the event that the host is not reachable. You can tell the SDK to return immediately, return after an amount of time that you specify, or to block indefinitely. The timeout value is set on a per-session handle basis and you can control the default timeout that is used by all session handles. Use ldap_set_option() to set the timeout value. Use ldap_get_option() to return the timeout value that is set for the current session handle. Timeout ValuesTo support this option, the following special values are now available:
In addition, you can specify a timeout value in milliseconds. Setting the Timeout ValueThe following code fragment sets the timeout value for the session handle to 10 seconds. #include <stdio.h> #include "ldap.h" #define HOST "mydirectory.siroe.com" #define PORT 389 ... LDAP *ld; LDAPMessage *result; int rc, version; /* timeout is specified in milliseconds. 10000 = 10 seconds. */ int timeout = 10000; ... if ( ( ld = ldap_init( HOST, PORT ) ) == NULL ) { perror( "ldap_init" ); return( -1 ); } if ( ldap_set_option( ld, LDAP_X_OPT_CONNECT_TIMEOUT, &timeout ) != LDAP_SUCCESS ) { rc = ldap_get_lderrno( ld, NULL, NULL); fprintf( stderr, "ldap_set_option: %s\n", ldap_err2string( rc ) ); ldap_unbind( ld ); return (rc); } ... You can also control the default timeout for all LDAP session handles by setting the int timeout = LDAP_X_IO_TIMEOUT_WAIT; ldap_set_option( NULL, LDAP_X_OPT_CONNECT_TIMEOUT, &timeout ); /* the default timeout is now set for all new ldap connections that are created after this call to ldap_set_option. */ Retrieving the Timeout ValueThe following code fragment retrieves the timeout value for the current session handle. #include <stdio.h> #include "ldap.h" #define HOST "mydirectory.siroe.com" #define PORT 389 ... LDAP *ld; LDAPMessage *result; int rc, version, timeout; ... if ( ( ld = ldap_init( HOST, PORT ) ) == NULL ) { perror( "ldap_init" ); return( -1 ); } if ( ldap_get_option( ld, LDAP_X_OPT_CONNECT_TIMEOUT, &timeout ) != LDAP_SUCCESS ) { rc = ldap_get_lderrno( ld, NULL, NULL); fprintf( stderr, "ldap_set_option: %s\n", ldap_err2string( rc ) ); ldap_unbind( ld ); return (rc); } switch( timeout ) { case LDAP_X_IO_TIMEOUT_NO_WAIT: printf("The connection is set to not block\n"); break; case LDAP_X_IO_TIMEOUT_NO_TIMEOUT: printf("The connection is set to block indefinitely\n"); break; default: printf("The connection timeout is set to %d seconds", (timeout/1000) ); break; } ...
LDAP library/API Version Mismatch Error MessagesThis feature was added to version 4.0 of the LDAP SDK for C. Various macros and structures have been added to the SDK to allow for compile-time and run-time discovery of the API version. Their intended use is to allow you to ensure that you are compiling and running with the correct version of the LDAP SDK for C. These features are in line with the latest LDAP SDK for C API Internet Draft. As a result of these changes, the command line tools bundled with the LDAP SDK for C now check to ensure that they are running with the correct version of the library. If your library path variable (LD_LIBRARY_PATH on most Unix systems and the PATH variable on Windows NT) is set so that an old version of the LDAP SDK for C library is in use, then the command line tools can return one of the following error messages: ldapsearch: unable to retrieve LDAP library version information; this program requires an LDAP library that implements revision 2003 or greater of the LDAP API. ldapsearch: this program requires an LDAP library that implements revision 2003 or greater of the LDAP API; running with revision 2002. ldapsearch: this program requires Netscape Communications Corp.'s LDAP library version 3.20 or greater; running with version 3.00. By default, the tools will exit if they see a mismatch in versions. To override the version mismatch, you can use -0 option (zero, not 'o') with the tools, but results may vary.
64-Bit Safe ChangesThis feature was added to version 4.0 of the LDAP SDK for C. Internal data types for liblber have been upgraded so that the data types are 64-bit safe. This is done in the following section of code in lber.h: /* * Implementation-specific integer data types. If living in an LP64 * environment (where sizeof(long) is 64 bits), we use unsigned ints; * otherwise we use unsigned longs. The goal is to always use 32-bit * quantities and to also be backwards compatible with previous SDK * versions which used unsigned longs. */ #if defined(_LP64) typedef unsigned int ber_len_t; typedef int ber_signed_len_t; typedef unsigned int ber_tag_t; typedef int ber_int_t; #else typedef unsigned long ber_len_t; typedef long ber_signed_len_t; typedef unsigned long ber_tag_t; typedef long ber_int_t; #endif This change makes liblber consistent between environments where int data types are 32 bits and those where they are 64 bits. However, this change may cause some compilers, especially c++ compilers where strong type checking is enforced, to emit warnings or errors when you recompile old code.
ldap_url_parse() with Space-Separated Lists of HostsThis feature was added to version 4.0 of the LDAP SDK for C. You can now pass ldap_url_parse() a string that uses the following format: ldap://host1:port1 host2:port2 host2:port3 ... hostn:portn/<basedn> Using this formatting, ldap_url_parse() will return results that are acceptable to ldap_init(). For example: LDAP *ld; LDAPURLDesc *ludpp; int res; char *url = "ldap://phonebook.airius.com:2389 directory.airius.com:389/o=airius.com"; res = ldap_url_parse(url, &ludpp); ld = ldap_init(ludpp->host, ludpp->port); This input causes ldap_init() to try to connect to each host and port in the URL string until it finds a host with which it can connect. Note that ludpp->port is set to the port identified on the last host in the URL string. If ludpp->port is used as shown here, then the last port identified on the URL string becomes the default port for any hosts for which a port is not explicitly set. Using the example above, suppose the URL string contained the following: ldap://phonebook.airius.com phonebook2.airius.com phonebook3.airius.com:2389/o=airius.com Here, ldap_init() would use port 2389 for all the hosts that it tries. If the last host in the string does not identify a port, then ludpp->port is set to zero (0). Setting the port to 0 tells ldap_init() to use the default port, which is 389 for ldap:// urls and 636 for ldaps:// urls.
KNOWN PROBLEMSThe following is a known bug in this release of the LDAP SDK for C:
MORE INFORMATIONNetscape and iPlanet provide binary releases of this SDK. However, note that this SDK is also available in source code form as part of the Mozilla.org open source project. Refer to the following site for more information on how you can get the source code and contribute to the further development of this SDK: http://www.mozilla.org/directory Product DocumentationThe LDAP SDK for C Programmer's Guide, version 4.1 is available in HTML and PDF formats. You can access this manual at the following site: http://docs.iplanet.com/docs/manuals/directory.html#SDKC. Installation instructions and release notes for all iPlanet and Netscape servers are posted at http://docs.iplanet.com/docs/manuals/index.html. Reporting Problems with the LDAP SDK for CPlease submit problem reports to the netscape.public.mozilla.directory newsgroup and/or mailing list. For information on locating this and other Mozilla newsgroups and mailing lists, please see http://www.mozilla.org/community.html
|