Previous     Contents     Index     Next     
Setup Util Programmer's Guide



Chapter 25   Ldapu.h Library Reference


This chapter describes ldapu.h, the library containing LDAP utility functions used during installation. It contains the following sections:



Error Codes


General Definition

typedef int LdapErrorCode;


Error Codes Used by ldapu.h

These are an extension of the current LDAP error codes.

#define OKAY 0x00


#define INVALID_INPUT

0x90

#define INVALID_URL

0x91

#define INVALID_AUTH

0x92

/* Not authorized */

#define INVALID_USER

0x93

/*User doesn't exist or isn't accessible*/

#define INVALID_OBJECT

0x94

/* The entry is empty */

#define INVALID_ROOT

0x95

/* NetscapeRoot does not exist */

#define INVALID_DN

0x96

/* DN does not exist */

#define CONN_FAILED

0x97

/* Failed connection to LDAP server */

#define ALREADY_EXISTS

0x98

/* Object already exists */

#define NOT_FOUND

0x99

/* Entry not found */

#define MISSING_ATTR

0x9A

/* Missing mandatory attributes */

#define INSTALL_DN_ERR

0x9B

/* InstallDN is missing */

#define UNKNOWN_ERR

0x9F

/* Some unknown LDAP error */

" Setup Util Error Codes



Routines


General Information on Working in C

When working with ldapu.h routines in C, you must first create an LDAP object, passing in an LDAP URL, a UID, and the password of the user who has access to the LDAP entries you want to manipulate. You can also pass the optional Bind DN and Bind password to bootstrap the initial search used to authenticate the LDAP user. Specify NULLs if you don't have the Bind DN/Password.

To work with a generic LDAP entry, create an LdapEntry object using the previously created Ldap object. Use the retrieveEntry and retrieveEntries functions to retrieve one or more LDAP entries. At present, retrieveEntries() returns only the first entry. Use getAttributes() to retrieve the values of the entry's attributes.

To insert an entry, you must first set the required attributes using setAttribute() or setAttributes(). These set single and multi-value attributes respectively. To determine if any entry exists without changing the internals of the LdapEntry, use the exists() function.

After an entry is retrieved or inserted, use entryDN() to get the DN of the entry.

Note that the Ldap object must exist and remain valid for the duration of the LdapEntry object that uses it. Call destroyLdapEntry() and destroyLdap() to delete the objects.


Ldap Objects

NSAPI_EXTERN LdapErrorCode createLdap(Ldap ** ldap,const char
   *ldapURL,const char *ldapUser,const char *ldapPwd,const char
   *binddn,const char *bindpwd);

NSAPI_EXTERN void destroyLdap (Ldap *);

NSAPI_EXTERN const char *userDN (const Ldap *);

NSAPI_EXTERN const char *ldapServerVersion(const Ldap *);

NSAPI_EXTERN LdapEntry *createLdapEntry(const Ldap *);

NSAPI_EXTERN void destroyLdapEntry(LdapEntry *);

NSAPI_EXTERN Bool entryExists(LdapEntry *, const char *entryDN);

NSAPI_EXTERN LdapErrorCode retrieveLdapEntry(LdapEntry *, const char
   *entryDN);

NSAPI_EXTERN LdapErrorCode retrieveLdapEntries(LdapEntry *, const
   char *criteria, int scope,const char *baseDN);

NSAPI_EXTERN LdapErrorCode nextLdapEntry(LdapEntry *);


Get all Attribute Names in this Entry
NSAPI_EXTERN char **getLdapAttributeNames(const LdapEntry *);

NSAPI_EXTERN void freeLdapAttributeNames(LdapEntry *, char
   **attrNames);

/* Given the name of an attribute, return the NULL terminated list of
 * associated attribute value(s). Use freeAttributes() to free the
 * returned list after use.
 */

NSAPI_EXTERN char **getLdapAttributes(const LdapEntry *, const char
   *name);

NSAPI_EXTERN void freeLdapAttributes(LdapEntry *, char
   **attributes);

NSAPI_EXTERN const char *entryDN(const LdapEntry *);

/* Setting attributes. For single-value attribute, use setAttribute.
 * For attributes that are typically multivalue, especially
 * objectclass, use setAttributes(). Don't mix setAttribute and
 * setAttributes on the same attribute.
 */

NSAPI_EXTERN void setLdapAttribute(LdapEntry *, const char *name,
   const char *value);

NSAPI_EXTERN void addLdapAttribute(LdapEntry *, const char *name,
   const char *value);

NSAPI_EXTERN void addLdapAttributes(LdapEntry *, const char
   *name,const char **values);

NSAPI_EXTERN LdapErrorCode renameLdapEntry(LdapEntry *, const char
   *entryDN, const char *rdn);

NSAPI_EXTERN LdapErrorCode insertLdapEntry(LdapEntry *, const char
   *entryDN);

NSAPI_EXTERN LdapErrorCode updateLdapEntry(LdapEntry *, const char
   *entryDN);

NSAPI_EXTERN LdapErrorCode replaceLdapEntry(LdapEntry *, const char
   *entryDN);

/* Drop an entry */

NSAPI_EXTERN LdapErrorCode dropLdapEntry(Ldap *, const char
   *entryDN);

NSAPI_EXTERN LdapErrorCode dropAllLdapEntries(Ldap *, const char
   *entryDN);


SIE/ISIE Creation Routines


setupInstallFramework()
NSAPI_EXTERN LdapErrorCode setupInstallFramework(const Ldap *, const
   char *adminDomain);


createSIE()
Registers a Server Instance Entry specified by sieEntry. This entry is associated with the nsApplication specified by isieDN. The entry is to be inserted at subTreeDN.

This routine does the following:

  • Creates an installed software instance under NetscapeRoot if it has not been created. Otherwise, it updates the entry with appropriate information

  • Generate the appropriate SIE entry's common name to guarantee the uniqueness of the SIE. A seeAlso link will be created from the SIE to the ISIE and vice versa.

createSIE has the following parameters:

  • sieEntry: LDAP entry for the SIE

  • appEntry: LDAP entry for the ISIE

  • hostName: name of this machine. Does not need to be FQDN, but the serverHostName attribute of appEntry must contain the FQDN.

  • installedLocation: the location where this product is installed

  • subTreeDN: the DN of the subtree where the SIE is to be installed. The default is cn=NetscapeRoot,<base-suffix>

Required attributes for appEntry are:

  • objectclass = nsApplication

  • name = product name, e.g. Netscape Directory Server

  • version = product version , e.g. 4.0a0

  • other attributes from the Package Information File.

Required attributes for sieEntry are:

  • objectclass (netscapeXXXServer, e.g. netscapeDirectoryServer which must be inherited from NetscapeServer)

  • SIE's password

  • serverID



    Tip Use entryDN() to get the full DN of the ISIE and SIE then save them for later use.



NSAPI_EXTERN LdapErrorCode createSIE(
   LdapEntry *sieEntry,
   LdapEntry *appEntry,
   const char *hostName,
   const char *installedLocation,
   const char *adminDomain);


removeSIE
Removes the server instance (and the pointer to it) from the ISIE. Optionally, removeISIE can be set to True to remove the ISIE as well. In general, the removeISIE flag should be set to False. Only set it to True when using it in binary uninstallation code.

NSAPI_EXTERN LdapErrorCode removeSIE(Ldap *, const char *sieDN, Bool
   removeISIE);


removeISIE
Removes the installed software instance. You should use this function in your uninstallation code.

The ISIE can only be removed when there are no associated server instances. The routine will remove the whole SIE hierarchy if possible up to but not including netscapeRoot.

NSAPI_EXTERN LdapErrorCode removeISIE(Ldap *, const char *isieDN);


updateISIEVersionInfo
Updates the ISIE with the version information as well as other related information. Used by the setup program only.

NSAPI_EXTERN LdapErrorCode updateISIEVersionInfo (
   Ldap *,
   LdapEntry *,
   const char *productName,
   const char *hostName,
   const char *installedLocation,
   const char *adminDomainName);


createACIForConfigData
Sets the appropriate access control for the LDAP entry that contains modifiable configuration data. e.g. cn=Configuration, cn=sie-cn, ou=Netscape Suitespot, o=example.com. The sieDN must be a valid DN for an existing SIE entry.

NSAPI_EXTERN LdapErrorCode createACIForConfigEntry (LdapEntry
   *configEntry, const char *sieDN);


Miscellaneous Routines


printEntry
Prints entry to fileName. Set fileName to NULL to print to stdout.

NSAPI_EXTERN void printLdapEntry(const LdapEntry *, const char
   *fileName);


verifyLdapUrl
Verifies the validity of an LDAP URL (format, ldap server, etc...)

extern LdapErrorCode verifyLdapUrl(
   const char *url,
   const char *bindDN,
   const char *bindPwd);


authLdapUser()
Authenticates an LDAP user. This is just a wrapper for createLdap() that does not return the LDAP object.

extern LdapErrorCode authLdapUser(
   const char *url,
   const char *ldapUser,
   const char *ldapPwd,
   const char *bindDN,
   const char *bindPwd);


isSubTreeWritable
Tests whether a subtree is writable.

NSAPI_EXTERN LdapErrorCode isSubTreeWritable(const Ldap *, const
   char *subTreeDN);


insertLdifEntries
Inserts LDAP entries specified in an LDIF-like file into LDAP below a given DN.

  • Ldap: pointer to a valid LDAP struct

  • subTreeDN: the DN of the location where the entries will be inserted. If the entry in the LDIF file has a DN attribute, it should be a relative DN as it will be prepended to subTreeDN to form the location where the entry is inserted.

    If subTreeDN is NULL, the DN attribute found in the entry will be used as an absolute DN. If subTreeDN is not NULL and there's no DN attribute in the LDIF entry, subTreeDN will be used as an absolute DN. If both subTreeDN and the DN attribute are missing, the entry is skipped.

  • ldifFile: name of the LDIF file

  • adminSIEDN: NULL in general. If not NULL, specify the DN of the Admin's SIE to be appended to the values of all className attributes found in the LDIF entries.

NSAPI_EXTERN LdapErrorCode insertLdifEntries (const Ldap *ldap,
   const char *subTreeDN, const char *ldifFile, const char
   *adminSieDN);

NSAPI_EXTERN LdapErrorCode insertSchemaEntries (Ldap *ldap, const
   char *schemaFile);

NSAPI_EXTERN LdapErrorCode appendSchemaEntries (Ldap *ldap, const
   char *schemaFile);


guessAdminDomain
Guesses the Administration Domain that might exist on this Directory Server.

NSAPI_EXTERN char * guessAdminDomainName(const char *ldapURL, const
   char *ldapUser, const char *ldapPwd);


checkAdminDomain
Checks the validity of the Administration Domain that exists on this Directory Server.

NSAPI_EXTERN LdapErrorCode checkAdminDomain(const Ldap *ldap, const
   char *adminDomain);


addUserDirectory
Configures a domain with a User Directory.

NSAPI_EXTERN LdapErrorCode addGlobalUserDirectory (const Ldap *ldap,
   const char *domain, const char *userDirUrl, const char *bindDN,
   const char *bindPwd);


getUserDirectory
Gets the user Directory associated with this SIE.

NSAPI_EXTERN LdapErrorCode getUserDirectory(const Ldap *ldap, const
   char *sieDN, char **url, char **bindDN, char **bindPwd);


getLocalUserDirectory
Gets the User Directory associated with this server root.

NSAPI_EXTERN LdapErrorCode getLocalUserDirectory (const Ldap *,
   const char *domain, const char *hostName, const char *serverRoot,
   char **userDirUrl, char **bindDN, char **bindPwd);


getGlobalUserDirectory
Gets the User Directory associated with this domain.

NSAPI_EXTERN LdapErrorCode getGlobalUserDirectory (const Ldap *,
   const char *domain, char **userDirUrl, char **bindDN, char
   **bindPwd);



LdapError Class

LDAP error object.


Public API

LdapError();

LdapError (LdapErrorCode errCode, const char *msg = "");

~LdapError()
{}


Assignment Operators
LdapError & operator = (const LdapError &error);

LdapError & operator = (LdapErrorCode error);

operator LdapErrorCode() {
   return _errCode;
}

LdapErrorCode errorCode() {
   return _errCode;
}

const char *msg() {
   return _errMsg.data();
}

LdapError & print (ostream& os = cerr);


Protected API

LdapErrorCode _errCode;
NSString _errMsg;
};



Ldap Class

An LDAP object.


General

class Ldap

{

friend class LdapEntry;


Public API


Member
Ldap::Ldap


Description
Creates an LDAP object. Given an LDAP URL, a uid, a password, and the optional bind DN and bind password, try to authenticate against the LDAP server.


Inputs

  • ldapURL: the URL of the LDAP server in the form ldap://<host>:<port>/<base suffix>

  • ldapUser: the uid or DN of the user to authenticate against the LDAP server. If a uid is given, the routine will use the supplied LDAP password to search the directory (when trying to authenticate the user).

  • ldapPwd: the associated password.

  • binddn/bindpwd: optional binddn and password used to initiate the initial LDAP search. If they are NULL, the routine attempts an anonymous search.


Outputs
  • LdapErrorCode


Definition
Ldap( LdapError & err,
   const char *ldapURL,
   const char *ldapUser, const char *ldapPwd,
   const char *binddn = 0, const char *bindpwd = 0);
   ~Ldap();


Members
Ldap::host()

Ldap::port

Ldap::baseSuffix()

Ldap::userDN()

Ldap::userPassword()

Ldap::version()

Ldap::rebindDN()

Ldap::rebindPwd()


Definitions
const char *host() const;
   int port() const;
   const char *baseSuffix() const;
   const char *userDN () const;
   const char *userPassword() const;
   const char *version() const;
   const char *rebindDN() const;
   const char *rebindPwd() const;


ldap_modify_s

This is a wrapper. It returns an LDAP error code.

int modify(const char *dn, LDAPMod **mods);


Private API


Member
Ldap::mapLdapError


Description
Maps a known LDAP error code to a Setup Util error code.


Returns
LdapError mapLdapError(int err);


Member
Ldap::verifyUrl


Description
Verifies that an LDAP server is valid.


Returns
LdapError verifyUrl (const char *ldapURL);


Member
Ldap::authenticate


Description
Authenticates against an LDAP server. If a uid was given for ldapUser, this routine will attempt to perform a search using the supplied LDAP password. The values for bindDN and bindPwd are used to initiate the LDAP search. If they were not supplied, the functions attempts an anonymous search.

You must call verifyUrl before authenticate().


Returns
LdapError authenticate(const char *ldapUser, const char *ldapPwd);
   NSString _ldapUser;
   NSString _ldapPwd;
   NSString _bindDN;
   NSString _bindPwd;
   NSString _rebindDN;
   NSString _rebindPwd;
   NSString _version;
   LDAP *_ldapHandle;
   LDAPURLDesc *_ldapUrlDesc;
};



LdapEntry Class

An LDAP entry object.


General

class LdapEntry


Public API

LdapEntry ()
{}

LdapEntry(const Ldap *ldap);

~LdapEntry();


entryDN
Gets the DN associated with this entry. Only valid after a successful retrieve() or insert().

const char *entryDN() const;


getAttributeNames
Gets the list of all attribute names in this entry. Use freeAttributenames to release the list.

char **getAttributeNames() const;

void freeAttributeNames(char **attrNames);


setAttribute
Sets an attribute with value. If this is a multivalue attribute it will become a single-value attribute.

void setAttribute(const char *attr, const char *value);


addAttribute
Adds a value to attribute. If it attribute does not exist it will be created

void addAttribute(const char *attr, const char *value);

void addAttributes(const char*attr, const char **values);


getAttributes
Gets all the values associated with attribute. Use freeAttributes to release the values.

char **getAttributes(const char *attr) const;

void freeAttributes (char **attrs);


deleteAttribute
Deletes an attribute

void deleteAttribute(const char *attr);


getAttribute
Gets the value of an attribute (first one if multi-value).

char *getAttribute(const char *attr) const;


checkAttribute
Verifies the existence of an attribute/value pair.

Bool checkAttribute(const char *attr, const char *value) const;


return
Returns associated LdapObject

const Ldap * ldap(void) const{
   return _ldap; }
void change_ldap(Ldap *new_ldap);


exists
Determines whether the entry at entryDN exists

Bool exists (const char *entryDN);


retrieve
Retrieves the entry at entryDN

LdapError retrieve (const char *entryDN);

LdapError retrieve (const char *criteria, int scope, const char                     *baseDN=0);


next
Retrieves the next entry. The current object will be overwritten if there is a next entry. Returns NOT_FOUND if there is no more entry, in which case the object will not be overwritten.

LdapError next();


rename
Renames this entry.

LdapError rename(const char *entryDN, const char *rdn);


insert
Inserts this entry given its DN. The entry must be properly set up.

LdapError insert (const char *entryDN);


update
Updates an entry. The entry must already exist. Note that this routine does not support changing the relative distinguished name. This routine updates the existing LDAP entry with the new attributes/values specified in the LdapEntry object. All existing attributes are kept. New attributes and values are added.

To remove an attribute using this routine, set the attribute value to an empty string ("").

LdapError update(const char *entryDN);


replace
Replaces an entry. The entry must already exist. This routine replaces an existing LDAP entry with the new one as specified in the LdapEntry object. Values of existing attributes are replaced with values specified in the object. Keep in mind that the new LdapEntry object completely replaces the existing object. Any attributes in the current object that are not in the new one will be lost.

To replace a subset of existing attributes, use update().

LdapError replace(const char *entryDN);


drop[All]
Drops the entry at entryDN. Use dropAll to drop multiple entries.

LdapError drop (const char *entryDN) const;

LdapError dropAll (const char *entryDN);


printEntry
Prints an entry to a file. Use NULL to print to stdout.

void printEntry(const char *filename) const;



LdifEntry Class

Simple class for reading LDIF files. This routine does not support line continuation.


General

class LdifEntry:public NVPair


Public API


Constructor
Creates the object from the given filename. If successful, the first entry is read.

LdifEntry (const char *fileName);


read
Reads LDIF entries from fileName. The first entry is immediately read. Subsequent entry can be retrieved using nextEntry(). Returns -1 on any error.

int read(const char *fileName);


isValid
Checks the validity of an LDIF entry. An entry is invalid if there is no LDIF file associated with it.

int isValid() const


nextEntry
Read next entry from LDIF file.

int nextEntry();



LdapSchema Class

Class for reading schema file.


General

class LdapSchema


Public API


Retrieve
Retrieves attributetypes and objectclasses from the Directory Server. Returns LDAP error numbers on failure.

int retrieve();


getValue
Gets an attributetype or objectclass value. Has the following parameters:

  • type: attributetypes for an attribute value, objectclasses for an object class value.

  • name: the name part of the value.

const char * getValue(char *type, char *name);


updateEntryValue
Updates value stored in Directory server. If name exists, the API tries to update it. Otherwise it adds a new entry to Directory Server. Has the following parameters:

  • type: attributetypes or objectclasses

  • name: the name part of value.

  • value: value

Returns an LDAP error number.

int updateEntryValue(char *type, char *name, char *value, int
                     doUpdate);


insertSchemaFile
Reads a schema configuration file and updates the Directory Server. Returns an LDAP error number.

int insertSchemaFile(const char *filename, int doUpdate);


Previous     Contents     Index     Next     
Copyright (C) 2005 Red Hat, Inc. All rights reserved.
This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/

Last Updated September 21, 2001