<!--

Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
Portions copyright 1999 Netscape Communications Corporation. All
Rights Reserved.

The contents of this document are subject to the terms of the
Creative Commons Attribution-ShareAlike 2.5 license or any later
version (the "License"). You may not use this document except in
compliance with the License.

See the License for the specific language governing
permissions and limitations under the License. You can obtain
a copy of the License at
http://creativecommons.org/licenses/by-sa/2.5/legalcode.

-->
<chapter id="csdk-quickstart"><title>Getting Started With &DirectorySDKForC;</title>
<indexterm>
<primary>C SDK</primary>
<secondary>quick start</secondary>
</indexterm><highlights>
<itemizedlist>
<para>This chapter shows how to start using &DirectorySDKForC;and covers
the following topics:</para>
<listitem><para><olink targetptr="bdabt">Sample Directory Client Code</olink></para>
</listitem>
<listitem><para><olink targetptr="bdabu">Compiling Directory SDK for C Client
Applications</olink></para></listitem>
<listitem><para><olink targetptr="bdabx">Running the Client</olink></para>
</listitem>
</itemizedlist>
</highlights>
<sect1 id="bdabt"><title>Sample Directory Client Code</title>
<indexterm>
<primary>example programs</primary>
<secondary>C SDK</secondary>
<tertiary>directory entry retrieval<?Pub Caret></tertiary>
</indexterm>
<para>The following sample source code is for a command-line program that
retrieves the full name, last name, email address, and telephone number of
Barbara Jensen.</para>
<example id="csdk-quick-sample"><title>Retrieving a Directory Entry</title>
<programlisting>#include &lt;stdio.h>
#include "ldap.h"

/* Adjust these setting for your own LDAP server */
#define HOSTNAME "localhost"
#define PORT_NUMBER  LDAP_PORT
#define FIND_DN "uid=bjensen,ou=People,dc=example,dc=com"

int
main( int argc, char **argv )
{
  LDAP         *ld;
  LDAPMessage  *result, *e;
  BerElement   *ber;
  char         *a;
  char         **vals;
  int          i, rc;

  /* Get a handle to an LDAP connection. */
  /* To get the handle on an IPv6 network, use prldap_init() instead. */
  if ( (ld = ldap_init( HOSTNAME, PORT_NUMBER )) == NULL ) {
    perror( "ldap_init" );
    return( 1 );
  }

  /* Bind anonymously to the LDAP server. */
  rc = ldap_simple_bind_s( ld, NULL, NULL );
  if ( rc != LDAP_SUCCESS ) {
    fprintf(stderr, "ldap_simple_bind_s: %s\n", ldap_err2string(rc));
    return( 1 );
  }

  /* Search for the entry. */
  if ( ( rc = ldap_search_ext_s( ld, FIND_DN, LDAP_SCOPE_BASE,
    "(objectclass=*)", NULL, 0, NULL, NULL, LDAP_NO_LIMIT,
    LDAP_NO_LIMIT, &amp;result ) ) != LDAP_SUCCESS ) {
    fprintf(stderr, "ldap_search_ext_s: %s\n", ldap_err2string(rc));
    return( 1 );
  }

  /* Since we are doing a base search, there should be only
     one matching entry.  */
  e = ldap_first_entry( ld, result );
  if ( e != NULL ) {
    printf( "\nFound %s:\n\n", FIND_DN );

    /* Iterate through each attribute in the entry. */
    for ( a = ldap_first_attribute( ld, e, &amp;ber );
      a != NULL; a = ldap_next_attribute( ld, e, ber ) ) {

      /* For each attribute, print the attribute name and values. */
      if ((vals = ldap_get_values( ld, e, a)) != NULL ) {
        for ( i = 0; vals[i] != NULL; i++ ) {
          printf( "%s: %s\n", a, vals[i] );
        }
        ldap_value_free( vals );
      }
      ldap_memfree( a );
    }
    if ( ber != NULL ) {
      ber_free( ber, 0 );
    }
  }
  ldap_msgfree( result );
  ldap_unbind( ld );
  return( 0 );
}</programlisting>
</example>
</sect1>
<sect1 id="bdabu"><title>Compiling &DirectorySDKForC; Client Applications</title>
<indexterm>
<primary>C SDK</primary>
<secondary>compiling applications</secondary>
</indexterm>
<para>The method used to compile the source code depends on the operating
system on which you run the application. The following sections include instructions
for compiling on UNIX and Windows systems.</para>
<sect2 id="bdabv"><title>Compiling Programs on UNIX Systems</title>
<para>The &DirectorySDKForC; <filename>examples/</filename> directory contains
a UNIX <filename>Makefile</filename>. You can modify the <filename>Makefile</filename> to
compile the sample by adjusting the flags in the file. The <filename>Makefile</filename> assumes
that the &DirectorySDKForC; header files are located in the <filename>../include/
</filename> directory.</para></sect2>
<sect2 id="bdabw"><title>Compiling Programs on Windows Systems</title>
<itemizedlist>
<para>If you are compiling the sample client on Windows, set up the build
framework for this application. Make sure to do the following:</para>
<listitem><para>If you are using Microsoft development tools, create a new
project workspace for a console application. Then add the source file to the
project.</para></listitem>
<listitem><para>Set your options to include <filename>lib\</filename> as one
of the directories for library files, and <filename>include\</filename> as
one of the directories for include files.</para></listitem>
<listitem><para>Link to <filename>nsldap32v60.lib</filename>, the LDAP API
import library for Windows.</para></listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="bdabx"><title>Running the Client</title>
<para>Before running the sample client, make sure that your LDAP server is
set up with the entry the sample attempts to find. Unless you change the source
code in <olink targetptr="csdk-quick-sample">Example 5&ndash;1</olink>, the
entry would be for the full name, last name, email address, and telephone
number of Barbara Jensen.</para>
<sect2 id="bdaby"><title>Running Programs on UNIX Systems</title>
<para>If you have linked the client on a UNIX platform, the client requires
the SDK library file. Make sure to set your <envar>LD_LIBRARY_PATH</envar> to
locate the <filename>libldap60.so</filename> library file and its dependencies.</para>
<para>As an alternative, when linking the file, specify the option that identifies
the library directories that the runtime linker should search for. For example,
on Solaris systems use the <option>R</option> option to specify the location
of the <filename>libldap60.so</filename> file.</para></sect2>
<sect2 id="bdabz"><title>Running Programs on Windows Systems</title>
<para>If you have linked the client with the <filename>nsldap32v60.lib</filename> library
on a Windows system, copy the &DirectorySDKForC; DLL files to one of the
following directories:</para>
<itemizedlist>
<listitem><para>The directory where the application was loaded</para></listitem>
<listitem><para>The current directory</para></listitem>
<listitem><para>The Windows system directory, such as <filename>winnt\system32\</filename></para>
</listitem>
<listitem><para>The Windows directory</para></listitem>
<listitem><para>The directories listed in the <envar>PATH</envar> environment
variable</para></listitem>
</itemizedlist>
</sect2>
</sect1>
</chapter>
