Main Page | Namespace List | Class Hierarchy | Class List | Directories | File List | Class Members | File Members

pldap.h

Go to the documentation of this file.
00001 /*
00002  * pldap.h
00003  *
00004  * Lightweight Directory Access Protocol interface class.
00005  *
00006  * Portable Windows Library
00007  *
00008  * Copyright (c) 1993-2003 Equivalence Pty. Ltd.
00009  *
00010  * The contents of this file are subject to the Mozilla Public License
00011  * Version 1.0 (the "License"); you may not use this file except in
00012  * compliance with the License. You may obtain a copy of the License at
00013  * http://www.mozilla.org/MPL/
00014  *
00015  * Software distributed under the License is distributed on an "AS IS"
00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
00017  * the License for the specific language governing rights and limitations
00018  * under the License.
00019  *
00020  * The Original Code is Portable Windows Library.
00021  *
00022  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
00023  *
00024  * Contributor(s): ______________________________________.
00025  *
00026  * $Log: pldap.h,v $
00027  * Revision 1.9  2004/05/24 12:02:49  csoutheren
00028  * Add function to permit setting a limit on the number of results returned
00029  * from an LDAP query. Change the default number of results to unlimited,
00030  * rather than MAX_INT which apparently is clamped to some arbitrary low value.
00031  * Thanks to Damien Sandras
00032  *
00033  * Revision 1.8  2004/02/20 16:28:27  ykiryanov
00034  * if'd LDAP code to enable non-LDAP builds
00035  *
00036  * Revision 1.7  2003/06/05 23:17:07  rjongbloed
00037  * Added functions to get and set LDAP operation timeout.
00038  *
00039  * Revision 1.6  2003/06/05 05:29:30  rjongbloed
00040  * Fixed LDAP bind authentication methods, thanks Ravelli Rossano
00041  *
00042  * Revision 1.5  2003/04/07 12:00:04  robertj
00043  * Fixed search function returning an error if can't find anything for filter.
00044  *
00045  * Revision 1.4  2003/04/01 07:05:29  robertj
00046  * Added ability to specify host:port in opening an LDAP server
00047  *
00048  * Revision 1.3  2003/03/31 09:02:43  robertj
00049  * Added missing return for error number.
00050  *
00051  * Revision 1.2  2003/03/31 03:32:41  robertj
00052  * Major addition of functionality.
00053  *
00054  * Revision 1.1  2003/03/28 01:15:44  robertj
00055  * OpenLDAP support.
00056  *
00057  *
00058  */
00059 
00060 #ifndef _PLDAP_H
00061 #define _PLDAP_H
00062 
00063 #ifdef P_USE_PRAGMA
00064 #pragma interface
00065 #endif
00066 
00067 #if P_LDAP
00068 
00069 #include <ptlib/sockets.h>
00070 
00071 
00072 struct ldap;
00073 struct ldapmsg;
00074 struct ldapmod;
00075 struct berval;
00076 
00077 class PLDAPStructBase;
00078 
00079 
00082 class PLDAPSession : public PObject
00083 {
00084   PCLASSINFO(PLDAPSession, PObject);
00085   public:
00088     PLDAPSession(
00089       const PString & defaultBaseDN = PString::Empty()
00090     );
00091 
00094     ~PLDAPSession();
00095 
00102     BOOL Open(
00103       const PString & server,
00104       WORD port = 0
00105     );
00106 
00109     BOOL Close();
00110 
00113     BOOL IsOpen() const { return ldapContext != NULL; }
00114 
00117     BOOL SetOption(
00118       int optcode,
00119       int value
00120     );
00121 
00124     BOOL SetOption(
00125       int optcode,
00126       void * value
00127     );
00128 
00129     enum AuthenticationMethod {
00130       AuthSimple,
00131       AuthSASL,
00132       AuthKerberos,
00133       NumAuthenticationMethod
00134     };
00135 
00138     BOOL Bind(
00139       const PString & who = PString::Empty(),
00140       const PString & passwd = PString::Empty(),
00141       AuthenticationMethod authMethod = AuthSimple
00142     );
00143 
00144     class ModAttrib : public PObject {
00145         PCLASSINFO(ModAttrib, PObject);
00146       public:
00147         enum Operation {
00148           Add,
00149           Replace,
00150           Delete,
00151           NumOperations
00152         };
00153 
00154       protected:
00155         ModAttrib(
00156           const PString & name,
00157           Operation op = NumOperations
00158         );
00159 
00160       public:
00161         const PString & GetName() const { return name; }
00162 
00163         Operation GetOperation() const { return op; }
00164 
00165         void SetLDAPMod(
00166           struct ldapmod & mod,
00167           Operation defaultOp
00168         );
00169 
00170       protected:
00171         virtual BOOL IsBinary() const = 0;
00172         virtual void SetLDAPModVars(struct ldapmod & mod) = 0;
00173 
00174         PString   name;
00175         Operation op;
00176     };
00177 
00178     class StringModAttrib : public ModAttrib {
00179         PCLASSINFO(StringModAttrib, ModAttrib);
00180       public:
00181         StringModAttrib(
00182           const PString & name,
00183           Operation op = NumOperations
00184         );
00185         StringModAttrib(
00186           const PString & name,
00187           const PString & value,
00188           Operation op = NumOperations
00189         );
00190         StringModAttrib(
00191           const PString & name,
00192           const PStringList & values,
00193           Operation op = NumOperations
00194         );
00195         void SetValue(
00196           const PString & value
00197         );
00198         void AddValue(
00199           const PString & value
00200         );
00201       protected:
00202         virtual BOOL IsBinary() const;
00203         virtual void SetLDAPModVars(struct ldapmod & mod);
00204 
00205         PStringList values;
00206         PBaseArray<char *> pointers;
00207     };
00208 
00209     class BinaryModAttrib : public ModAttrib {
00210         PCLASSINFO(BinaryModAttrib, ModAttrib);
00211       public:
00212         BinaryModAttrib(
00213           const PString & name,
00214           Operation op = Add
00215         );
00216         BinaryModAttrib(
00217           const PString & name,
00218           const PBYTEArray & value,
00219           Operation op = Add
00220         );
00221         BinaryModAttrib(
00222           const PString & name,
00223           const PList<PBYTEArray> & values,
00224           Operation op = Add
00225         );
00226         void SetValue(
00227           const PBYTEArray & value
00228         );
00229         void AddValue(
00230           const PBYTEArray & value
00231         );
00232       protected:
00233         virtual BOOL IsBinary() const;
00234         virtual void SetLDAPModVars(struct ldapmod & mod);
00235 
00236         PList<PBYTEArray> values;
00237         PBaseArray<struct berval *> pointers;
00238         PBYTEArray bervals;
00239     };
00240 
00243     BOOL Add(
00244       const PString & dn,
00245       const PList<ModAttrib> & attributes
00246     );
00247 
00250     BOOL Add(
00251       const PString & dn,
00252       const PStringToString & attributes
00253     );
00254 
00258     BOOL Add(
00259       const PString & dn,
00260       const PStringArray & attributes
00261     );
00262 
00266     BOOL Add(
00267       const PString & dn,
00268       const PLDAPStructBase & data
00269     );
00270 
00273     BOOL Modify(
00274       const PString & dn,
00275       const PList<ModAttrib> & attributes
00276     );
00277 
00280     BOOL Modify(
00281       const PString & dn,
00282       const PStringToString & attributes
00283     );
00284 
00288     BOOL Modify(
00289       const PString & dn,
00290       const PStringArray & attributes
00291     );
00292 
00296     BOOL Modify(
00297       const PString & dn,
00298       const PLDAPStructBase & data
00299     );
00300 
00303     BOOL Delete(
00304       const PString & dn
00305     );
00306 
00307 
00308     enum SearchScope {
00309       ScopeBaseOnly,
00310       ScopeSingleLevel,
00311       ScopeSubTree,
00312       NumSearchScope
00313     };
00314 
00315     class SearchContext {
00316       public:
00317         SearchContext();
00318         ~SearchContext();
00319 
00320         BOOL IsCompleted() const { return completed; }
00321 
00322       private:
00323         int              msgid;
00324         struct ldapmsg * result;
00325         struct ldapmsg * message;
00326         BOOL             found;
00327         BOOL             completed;
00328 
00329       friend class PLDAPSession;
00330     };
00331 
00334     BOOL Search(
00335       SearchContext & context,
00336       const PString & filter,
00337       const PStringArray & attributes = PStringList(),
00338       const PString & base = PString::Empty(),
00339       SearchScope scope = ScopeSubTree
00340     );
00341 
00344     BOOL GetSearchResult(
00345       SearchContext & context,
00346       PStringToString & data
00347     );
00348 
00351     BOOL GetSearchResult(
00352       SearchContext & context,
00353       const PString & attribute,
00354       PString & data
00355     );
00356 
00359     BOOL GetSearchResult(
00360       SearchContext & context,
00361       const PString & attribute,
00362       PStringArray & data
00363     );
00364 
00367     BOOL GetSearchResult(
00368       SearchContext & context,
00369       const PString & attribute,
00370       PArray<PBYTEArray> & data
00371     );
00372 
00375     BOOL GetSearchResult(
00376       SearchContext & context,
00377       PLDAPStructBase & data
00378     );
00379 
00382     PString GetSearchResultDN(
00383       SearchContext & context
00384     );
00385 
00388     BOOL GetNextSearchResult(
00389       SearchContext & context
00390     );
00391 
00396     PList<PStringToString> Search(
00397       const PString & filter,
00398       const PStringArray & attributes = PStringList(),
00399       const PString & base = PString::Empty(),
00400       SearchScope scope = ScopeSubTree
00401     );
00402 
00403 
00406     void SetBaseDN(
00407       const PString & dn
00408     ) { defaultBaseDN = dn; }
00409 
00412     const PString & GetBaseDN() const { return defaultBaseDN; }
00413 
00416     int GetErrorNumber() const { return errorNumber; }
00417 
00420     PString GetErrorText() const;
00421 
00424     struct ldap * GetOpenLDAP() const { return ldapContext; }
00425 
00428     const PTimeInterval & GetTimeout() const { return timeout; }
00429 
00432     void SetTimeout(
00433       const PTimeInterval & t
00434     ) { timeout = t; }
00435 
00438      void SetSearchLimit(
00439       const unsigned s
00440     ) { searchLimit = s; }
00441 
00442   protected:
00443     struct ldap * ldapContext;
00444     int           errorNumber;
00445     unsigned      protocolVersion;
00446     PString       defaultBaseDN;
00447     unsigned      searchLimit;
00448     PTimeInterval timeout;
00449     PString       multipleValueSeparator;
00450 };
00451 
00452 
00453 
00454 class PLDAPStructBase;
00455 
00456 class PLDAPAttributeBase : public PObject
00457 {
00458     PCLASSINFO(PLDAPAttributeBase, PObject);
00459   public:
00460     PLDAPAttributeBase(const char * name, void * pointer, PINDEX size);
00461 
00462     const char * GetName() const { return name; }
00463     BOOL IsBinary() const { return pointer != NULL; }
00464 
00465     virtual void Copy(const PLDAPAttributeBase & other) = 0;
00466 
00467     virtual PString ToString() const;
00468     virtual void FromString(const PString & str);
00469     virtual PBYTEArray ToBinary() const;
00470     virtual void FromBinary(const PArray<PBYTEArray> & data);
00471 
00472   protected:
00473     const char * name;
00474     void       * pointer;
00475     PINDEX       size;
00476 };
00477 
00478 
00479 class PLDAPStructBase : public PObject {
00480     PCLASSINFO(PLDAPStructBase, PObject);
00481   protected:
00482     PLDAPStructBase();
00483     PLDAPStructBase & operator=(const PLDAPStructBase &);
00484     PLDAPStructBase & operator=(const PStringArray & array);
00485     PLDAPStructBase & operator=(const PStringToString & dict);
00486   private:
00487     PLDAPStructBase(const PLDAPStructBase &) { }
00488 
00489   public:
00490     void PrintOn(ostream & strm) const;
00491 
00492     PINDEX GetNumAttributes() const { return attributes.GetSize(); }
00493     PLDAPAttributeBase & GetAttribute(PINDEX idx) const { return attributes.GetDataAt(idx); }
00494     PLDAPAttributeBase * GetAttribute(const char * name) const { return attributes.GetAt(name); }
00495 
00496     void AddAttribute(PLDAPAttributeBase * var);
00497     static PLDAPStructBase & GetInitialiser() { return *PAssertNULL(initialiserInstance); }
00498 
00499   protected:
00500     void EndConstructor();
00501 
00502     PDictionary<PString, PLDAPAttributeBase> attributes;
00503 
00504     PLDAPStructBase        * initialiserStack;
00505     static PMutex            initialiserMutex;
00506     static PLDAPStructBase * initialiserInstance;
00507 };
00508 
00509 
00510 #define PLDAP_STRUCT_BEGIN(name) \
00511   class name : public PLDAPStructBase { \
00512     public: name() { EndConstructor(); } \
00513     public: name(const name & other) { EndConstructor(); operator=(other); } \
00514     public: name(const PStringArray & array) { EndConstructor(); operator=(array); } \
00515     public: name(const PStringToString & dict) { EndConstructor(); operator=(dict); } \
00516     public: name & operator=(const name & other) { PLDAPStructBase::operator=(other); return *this; } \
00517     public: name & operator=(const PStringArray & array) { PLDAPStructBase::operator=(array); return *this; } \
00518     public: name & operator=(const PStringToString & dict) { PLDAPStructBase::operator=(dict); return *this; } \
00519     PLDAP_ATTR_INIT(name, PString, objectClass, #name);
00520 
00521 #define PLDAP_ATTRIBUTE(base, type, attribute, pointer, init) \
00522     public: type attribute; \
00523     private: struct PLDAPAttr_##attribute : public PLDAPAttributeBase { \
00524       PLDAPAttr_##attribute() \
00525         : PLDAPAttributeBase(#attribute, pointer, sizeof(type)), \
00526           instance(((base &)base::GetInitialiser()).attribute) \
00527         { init } \
00528       virtual void PrintOn (ostream & s) const { s << instance; } \
00529       virtual void ReadFrom(istream & s)       { s >> instance; } \
00530       virtual void Copy(const PLDAPAttributeBase & other) \
00531                     { instance = ((PLDAPAttr_##attribute &)other).instance; } \
00532       type & instance; \
00533     } pldapvar_##attribute
00534 
00535 #define PLDAP_ATTR_SIMP(base, type, attribute) \
00536         PLDAP_ATTRIBUTE(base, type, attribute, NULL, ;)
00537 
00538 #define PLDAP_ATTR_INIT(base, type, attribute, init) \
00539         PLDAP_ATTRIBUTE(base, type, attribute, NULL, instance = init;)
00540 
00541 #define PLDAP_BINATTRIB(base, type, attribute) \
00542         PLDAP_ATTRIBUTE(base, type, attribute, &((base &)base::GetInitialiser()).attribute, ;)
00543 
00544 #define PLDAP_STRUCT_END() \
00545   };
00546 
00547 #endif // P_LDAP
00548 
00549 #endif // _PLDAP_H
00550 
00551 
00552 // End of file ////////////////////////////////////////////////////////////////

Generated on Sat Dec 22 16:46:51 2007 for PWLib by  doxygen 1.4.2