openldap/contrib/ldapc++/src/LDAPAsynConnection.h

/*
 * Copyright 2000, OpenLDAP Foundation, All Rights Reserved.
 * COPYING RESTRICTIONS APPLY, see COPYRIGHT file
 */


#ifndef LDAP_ASYN_CONNECTION_H
#define LDAP_ASYN_CONNECTION_H

#include<iostream>
#include<string>

#include<ldap.h>
#include<lber.h>

#include "LDAPMessageQueue.h"
#include "LDAPConstraints.h"
#include "LDAPModification.h"
#include "LDAPModList.h"
#include "LDAPUrl.h"
#include "LDAPUrlList.h"

class LDAPEntry;
class LDAPAttribute;

//* Main class for an asynchronous LDAP connection 
/**
 * This class represents an asynchronous connection to an LDAP-Server. It 
 * provides the methods for authentication, and all other LDAP-Operations
 * (e.g. search, add, delete, etc.)
 * All of the LDAP-Operations return a pointer to a LDAPMessageQueue-Object,
 * which can be used to obtain the results of that operation.
 * A basic example of this class could be like this:  <BR>
 * 1. Create a new LDAPAsynConnection Object: <BR>
 * 2. Use the init-method to initialize the connection <BR>
 * 3. Call the bind-method to authenticate to the directory <BR>
 * 4. Obtain the bind results from the return LDAPMessageQueue-Object <BR>
 * 5. Perform on of the operations on the directory (add, delete, search, ..)
 *    <BR>
 * 6. Use the return LDAPMessageQueue to obtain the results of the operation 
 * <BR>
 * 7. Close the connection (feature not implemented yet :) ) <BR>
 */
class LDAPAsynConnection{
    public :
        static const int SEARCH_BASE=0;
        static const int SEARCH_ONE=1;
        static const int SEARCH_SUB=2;
//        static const int SEARCH_SUB=LDAP_SCOPE_SUBTREE;
//        static const int SEARCH_ONE=LDAP_SCOPE_ONELEVEL;
//        static const int SEARCH_SUB=LDAP_SCOPE_SUBTREE;

        //* Construtor that initializes a connection to a server
        /**
         * @param hostname Name (or IP-Adress) of the destination host
         * @param port Port the LDAP server is running on
         * @param cons Default constraints to use with operations over 
         *      this connection
         */
        LDAPAsynConnection(const string& hostname=string("localhost"),
                int port=389, LDAPConstraints *cons=new LDAPConstraints() );

        //* Destructor
        virtual ~LDAPAsynConnection();

        /** 
         * Initzializes a connection to a server. There actually no
         * communication to the server. Just the object is initialized
         * (e.g. this method is called with the 
         * LDAPAsynConnection(char*,int,LDAPConstraints) constructor.)
         */
        void init(const string& hostname, int port);

        //* Simple authentication to a LDAP-Server
        /**
         * This method does a simple (username, password) bind to the server.
         * Other, saver, authentcation methods are provided later
         * @param dn the distiguished name to bind as
         * @param passwd cleartext password to use
         */
        LDAPMessageQueue* bind(const string& dn="", const string& passwd="",
                const LDAPConstraints *cons=0);

        //* Performing a search on a directory tree.
        /**
         * Use the search method to perform a search on the LDAP-Directory
         * @param base The distinguished name of the starting point for the
         *      search operation
         * @param scope The scope of the search. Possible values: <BR> 
         *      LDAPAsynConnection::SEARCH_BASE, <BR> 
         *      LDAPAsynConnection::SEARCH_ONE, <BR>
         *      LDAPAsynConnection::SEARCH_SUB
         * @param attrsOnly true if only the attributes names (no values) 
         *      should be returned
         * @param cons A set of constraints that should be used with this
         *      request
         */
        LDAPMessageQueue* search(const string& base="", int scope=0, 
                                 const string& filter="objectClass=*", 
                                 const StringList& attrs=StringList(), 
                                 bool attrsOnly=false,
                                 const LDAPConstraints *cons=0);
        
        //* Delete an entry from the directory
        /**
         * This method sends a delete request to the server
         * @param dn    Distinguished name of the entry that should be deleted
         * @param cons  A set of constraints that should be used with this
         *              request
         */
        LDAPMessageQueue* del(const string& dn, const LDAPConstraints *cons=0);
        
        //* Perform the compare operation on an attribute 
        /**
         * @param dn    Distinguished name of the entry for which the compare
         *              should be performed
         * @param attr  An Attribute (one (!) value) to use for the
         *      compare operation
         * @param cons  A set of constraints that should be used with this
         *              request
         */
        LDAPMessageQueue* compare(const string& dn, const LDAPAttribute& attr, 
                const LDAPConstraints *cons=0);

        //* Add an entry to the directory
        /**
         * @see LDAPEntry
         * @param le The entry that will be added to the directory
         */
        LDAPMessageQueue* add( const LDAPEntry* le,
                const LDAPConstraints *const=0);

        //* Apply modifications to attributes of an entry
        /**
         * @param dn Distiguished Name of the Entry to modify
         * @param modlist A set of modification that should be applied
         *      to the Entry
         * @param cons  A set of constraints that should be used with this
         *              request
         */
        LDAPMessageQueue* modify(const string& dn, const LDAPModList *modlist,
                const LDAPConstraints *cons=0);

        //* modify the DN of an entry
        /**
         * @param dn            DN to modify
         * @param newRDN        The new relative DN for the entry
         * @param delOldRDN     true=The old RDN will be removed from the 
         *                      attributes <BR>
         *                      false=The old RDN will still be present in the
         *                      attributes of the entry
         * @param newParentDN   The DN of the new parent entry of the entry
         *                      0 to keep the old one
         */
        LDAPMessageQueue* rename(const string& dn, const string& newRDN,
                bool delOldRDN=false, const string& newParentDN="",
                const LDAPConstraints* cons=0);
        
        //* Perform a LDAP extended Operation
        /**
         * e.g. requesting TLS security features
         * @param oid The dotted decimal representation of the extended 
         *      Operation that should be performed
         * @param value The data asociated with this operation
         * @param cons  A set of constraints that should be used with this
         *              request
         */
        LDAPMessageQueue* extOperation(const string& oid, 
                const string& value="", const LDAPConstraints *cons=0);
        
        //* End an outstanding request
        /**
         * @param q All outstanding request related to this LDAPMessageQueue 
         *      will be abandoned
         */
        void abandon(LDAPMessageQueue *q);
        void unbind();
        LDAP* getSessionHandle() const ;
        const string& getHost() const;
        int getPort() const;
        
        //* Change the default constraints of the connection
        /**
         * @cons cons New LDAPConstraints to use with the connection
         */
        void setConstraints(LDAPConstraints *cons);
        
        //* Get the default constraints of the connection
        /**
         * @return Pointer to the LDAPConstraints-Object that is currently
         *      used with the Connection
         */
        const LDAPConstraints* getConstraints() const;

        //* used internally only for automatic referral chasing
        LDAPAsynConnection* referralConnect(const LDAPUrlList& urls,
                LDAPUrlList::const_iterator& usedUrl,
                const LDAPConstraints* cons) const;


    private :
        // no copy constructor
        LDAPAsynConnection(const LDAPAsynConnection& lc){};
        LDAP *cur_session;
        LDAPConstraints *m_constr;
        string m_host;
        int m_port;

};
#endif //LDAP_ASYN_CONNECTION_H