HELPLIB.HLB  —  LDAP  Introduction
          The C LDAP API is designed to be powerful, yet simple
    to use. It defines compatible synchronous and asynchronous
    interfaces to LDAP to support a wide variety of applications.

1  –  Overview of the LDAP Model

    LDAP is the lightweight directory access protocol, which is based
    on a client-server model. In this model, a client makes a TCP
    connection to an LDAP server, over which it sends requests and
    receives responses.

    The LDAP information model is based on the entry, which contains
    information about some object (for example, a person). Entries
    are composed of attributes, which have a type and one or more
    values. Each attribute has a syntax that determines what kinds
    of values are allowed in the attribute (for example, ASCII
    characters or a jpeg photograph) and how those values behave
    during directory operations (for example, whether case is
    significant during comparisons).

    Entries may be organized in a tree structure, usually based on
    political, geographical, or organizational boundaries. Each entry
    is uniquely named relative to its sibling entries by its relative
    distinguished name (RDN) consisting of one or more distinguished
    attribute values from the entry. At most, one value from each
    attribute may be used in the RDN. For example, the entry for the
    person Babs Jensen might be named with the Barbara Jensen value
    from the commonName attribute.

    A globally unique name for an entry, called a distinguished name
    or DN, is constructed by concatenating the sequence of RDNs from
    the entry up to the root of the tree. For example, if Babs worked
    for the University of Michigan, the DN of her U-M entry might be
    the following:

    cn=Barbara Jensen, o=University of Michigan, c=US

    Operations are provided to authenticate, search for and retrieve
    information, modify information, and add and delete entries from
    the tree.

2  –  Overview of LDAP API Use

    An application generally uses the C LDAP API in four simple
    steps.

    o  Initialize an LDAP session with a primary LDAP server. The
       ldap_init() function returns a handle to the session, allowing
       multiple connections to be open at once.

    o  Authenticate to the LDAP server. The ldap_bind() function
       supports a variety of authentication methods.

    o  Perform some LDAP operations and obtain some results. The
       ldap_search() function returns results that can be parsed
       by ldap_parse_result(), ldap_first_entry(),  and ldap_next_
       entry().

    o  Close the session. The ldap_unbind() function closes the
       connection.

    Operations can be performed either synchronously or
    asynchronously. The names of the synchronous functions end
    in _s. For example, a synchronous search can be completed by
    calling ldap_search_s(). An asynchronous search can be initiated
    by calling ldap_search(). All synchronous functions return an
    indication of the outcome of the operation (for example, the
    constant LDAP_SUCCESS or some other error code). The asynchronous
    functions make available to the caller the message id of the
    operation initiated. This id can be used in subsequent calls
    to ldap_result() to obtain the result(s) of the operation. An
    asynchronous operation can be abandoned by calling ldap_abandon()
    or ldap_abandon_ext().

    Results and errors are returned in an opaque structure called
    LDAPMessage. Functions are provided to parse this structure,
    step through entries and attributes returned. Functions are also
    provided to interpret errors.

    LDAPv3 servers may return referrals to other servers. By default,
    implementations of this API will attempt to follow referrals
    automatically for the application. This behavior can be disabled
    globally (using the ldap_set_option() call) or on a per-request
    basis through the use of a server control.

    As in the LDAPv3 protocol, all DNs and string values that are
    passed into or produced by the C LDAP API are represented as
    UTF-8 characters. Conversion functions are described in Encoded
    ASN.1.

    For compatibility with existing applications, implementations of
    this API will, by default, use Version 2 of the LDAP protocol.
    Applications that intend to take advantage of LDAPv3 features
    will need to use the ldap_set_option() call with a LDAP_OPT_
    PROTOCOL_VERSION switch set to Version 3.

    The file LDAP_EXAMPLE.C in SYS$EXAMPLES contains an example
    program that demonstrates how to use the LDAP API on OpenVMS.

3  –  LDAP API Use on OpenVMS Systems

    This release of the LDAP API provides support for client
    applications written in C or C++.

    In order to use the LDAP API, a program must use an include
    statement of the form:

    #include <ldap.h>

    The LDAP.H header file includes prototypes and data structures
    for all of the functions that are available in the LDAP API.

    The shareable image LDAP$SHR.EXE includes run-time support for
    LDAP applications. This shareable image resides in SYS$LIBRARY
    and should be included in the library IMAGELIB.OLB, which means
    that no special action is necessary to link or run your programs.
    For example:

      $ type myprog.c

      /* A not very useful program */
      #include <stdio.h>
      #include <ldap.h>
      void main(int argc, char *argv[])
      {
        LDAP *ld;
        if (argc != 2) {
          printf("usage: %s <hostname>\n",argv[0]);
          return;
        }
        ld = ldap_init(argv[1],LDAP_PORT);
        if (ld != NULL) {
          printf("ldap_init returned 0x%p\n",ld);
        } else {
          printf("ldap_init failed\n");
        }
      }

      $ cc myprog
      $ link myprog
      $ myprog :== $mydisk:[mydir]myprog.exe
      $ myprog fred
      ldap_init returned 0xA6748
      $

4  –  64-bit Addressing Support

    OpenVMS Alpha provides support for 64-bit virtual memory
    addressing. Applications that are built using a suitable compiler
    may take advantage of the 64-bit virtual address space to map and
    access large amounts of data.

4.1  –  Background

    The OpenVMS LDAP API supports both 32- and 64-bit client
    applications. In order to allow this, separate entry points are
    provided in the library for those functions that are sensitive to
    pointer size.

    When a user module is compiled, the header file LDAP.H determines
    the pointer size in effect and uses the C preprocessor to map
    the function names into the appropriate library entry point. This
    mapping is transparent to the user application and is effected by
    setting the /POINTER_SIZE qualifier at compilation time.

    For LDAP API users, switching between different pointer sizes
    should need only a recompilation-no code changes are necessary.

    This means that programs using the specification for the C LDAP
    API, as described in the Internet Engineering Task Force (IETF)
    documentation, can be built on OpenVMS with either 32-bit or
    64-bit pointer size, without having to change the source code.

4.2  –  Implementation

    The OpenVMS LDAP library uses 64-bit pointers internally and is
    capable of dealing with data structures allocated by the caller
    from 64-bit address space.

    Applications that use 32-bit pointers will use the 32-bit
    function entry points in the library. This means they can pass
    arguments that are based on 32-bit pointers and can assume that
    any pointers returned by the library will be 32-bit safe.

    While the mapping performed by LDAP.H is designed to be
    transparent, there may be occasions where it is useful (for
    example in debugging) to understand the consequences of having
    both 32- and 64-bit support in the same library.

4.2.1  –  Library Symbol Names

    The symbols exported by the LDAP$SHR OpenVMS run-time library
    differ from those specified in the IETF C LDAP API specification.

    The header file LDAP.H maps user references to LDAP API function
    names to the appropriate LDAP$SHR symbol name. Therefore, any
    application wishing to use the OpenVMS LDAP API must include the
    version of LDAP.H that ships with OpenVMS.

    All of the functions in the OpenVMS LDAP library are prefixed
    with the facility code "LDAP$".

    For those functions where the caller's pointer size is
    significant, the name of the 64-bit entry point will have a "_
    64" suffix, while the name of the 32-bit jacket will have a "_32"
    suffix. Functions that are not sensitive to pointer size have no
    special suffix.

    For example, the function ldap_modify() is sensitive to the
    caller's pointer size (because one of its arguments is an
    array of pointers). Therefore, the library exports symbols for
    LDAP$LDAP_MODIFY_64 and LDAP$LDAP_MODIFY_32. For the function
    ldap_simple_bind(), which is not sensitive to the caller's
    pointer size, a single entry point, LDAP$LDAP_SIMPLE_BIND, exists
    in the library.

    Because OpenVMS imposes a 31-character limit on the length of
    symbol names, certain functions in the library have names which
    are abbreviated versions of the public API name. For example,
    in the case of the function ldap_parse_sasl_bind_result(), the
    library provides two entry points, namely LDAP$LDAP_PRS_SASL_
    BIND_RES_32 and LDAP$LDAP_PRS_SASL_BIND_RES_64.

4.2.2  –  LDAP Data Structures

    The LDAP API defines various data structures which are used to
    pass information to and from a client application. Some of these
    structures are opaque; that is, their internal layout is not
    visible to a client application. In such cases, the API may
    return a pointer to such a structure, but the only use of such
    a pointer to a client application is as a parameter to subsequent
    library calls.

    Some structures are public. Their contents are defined by the
    API, and client applications may allocate and manipulate such
    structures or use them as parameters to LDAP functions.

    All data structures used by the API are defined with "natural"
    alignment; that is, each member of a data structure will be
    aligned on an address boundary appropriate to its type.

    Opaque Data Structures

    The following data structures are opaque. Applications should
    not make any assumptions about the contents or size of such data
    structures.

        typedef struct ldap
                LDAP;

        typedef struct ldapmsg
                LDAPMessage;

        typedef struct berelement
                BerElement;

    Public Data Structures

    The following data structures are described in the IETF documents
    relating to the LDAP API, and definitions are provided for
    them in LDAP.H. Applications may allocate and manipulate such
    structures, as well as use them in calls to the LDAP API.

        typedef struct berval { .. }
                BerValue;

        typedef struct ldapapiinfo { .. }
                LDAPAPIInfo;

        typedef struct ldap_apifeature_info { .. }
                LDAPAPIFeatureInfo;

        typedef struct ldapcontrol { .. }
                LDAPControl;

        typedef struct ldapmod { .. }
                LDAPMod;

    Note that the pointer size in effect at compilation time
    determines the layout of data structures, which themselves
    contain pointer fields. Since all of the public data structures
    listed here contain one or more pointers, their size and layout
    will differ depending on the pointer size.

    For example, in the case of the structure berval, the API
    provides the following definition:

     struct berval {
          ber_len_t      bv_len;
          char           *bv_val;
     } BerValue;

    (where ber_len_t is equivalent on OpenVMS to an unsigned 32-bit
    integer).

    The following code would therefore work correctly regardless of
    pointer size:

         #include <ldap.h>
         .
         .
         .
           char       *buff;
           BerValue   val;
         .
         .
         .
           buff = (char *)malloc(255);
         .
         .
         .
           val.bv_len = 255;
           val.bv_val = buff;
         .
         .
         .

4.3  –  Mixing Pointer Sizes

    Two modules that include LDAP.H can be compiled with different
    pointer sizes and linked together. While each module may use the
    LDAP API on its own, it may not be possible for both modules to
    share LDAP-related data.

    None of the public LDAP data structures is directly compatible
    between 32- and 64-bit modules. For example, a BerValue that
    has been allocated by a 32-bit module does not have the same
    layout as a BerValue which a 64-bit module expects to see, and
    consequently cannot be exchanged between two such modules without
    some sort of data conversion taking place.

    Opaque data structures (such as LDAP *) have only a single
    structure definition inside the library, and so pointers to such
    structures may be exchanged between 32- and 64-bit callers. Note
    that these structures are allocated only by the library itself,
    and, in the case of a 64-bit caller, these structures may be
    allocated in 64-bit space. So while the LDAP handle returned to
    a 32-bit caller of ldap_init() could safely be used by a 64-bit
    module, the reverse may not be true.

5  –  Multithreading Support

    The OpenVMS LDAP API may be used by a multi-threaded application.
    Two of the functions in the library, ldap_perror() and ldap_
    result2error(), are not thread-safe.
Close Help