PTLib  Version 2.10.11
pldap.h
Go to the documentation of this file.
1 /*
2  * pldap.h
3  *
4  * Lightweight Directory Access Protocol interface class.
5  *
6  * Portable Windows Library
7  *
8  * Copyright (c) 1993-2003 Equivalence Pty. Ltd.
9  *
10  * The contents of this file are subject to the Mozilla Public License
11  * Version 1.0 (the "License"); you may not use this file except in
12  * compliance with the License. You may obtain a copy of the License at
13  * http://www.mozilla.org/MPL/
14  *
15  * Software distributed under the License is distributed on an "AS IS"
16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
17  * the License for the specific language governing rights and limitations
18  * under the License.
19  *
20  * The Original Code is Portable Windows Library.
21  *
22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
23  *
24  * Contributor(s): ______________________________________.
25  *
26  * $Revision: 27535 $
27  * $Author: rjongbloed $
28  * $Date: 2012-04-26 02:48:22 -0500 (Thu, 26 Apr 2012) $
29  */
30 
31 #ifndef PTLIB_PLDAP_H
32 #define PTLIB_PLDAP_H
33 
34 #ifdef P_USE_PRAGMA
35 #pragma interface
36 #endif
37 
38 #if defined(P_LDAP) && !defined(_WIN32_WCE)
39 
40 #include <ptlib/sockets.h>
41 #include <ptlib/pluginmgr.h>
42 #include <map>
43 #include <list>
44 
45 struct ldap;
46 struct ldapmsg;
47 struct ldapmod;
48 struct berval;
49 
50 class PLDAPStructBase;
51 
52 
55 class PLDAPSession : public PObject
56 {
57  PCLASSINFO(PLDAPSession, PObject);
58  public:
63  );
64 
67  ~PLDAPSession();
68 
75  PBoolean Open(
76  const PString & server,
77  WORD port = 0
78  );
79 
82  PBoolean Close();
83 
86  PBoolean IsOpen() const { return ldapContext != NULL; }
87 
91  int optcode,
92  int value
93  );
94 
98  int optcode,
99  void * value
100  );
101 
106 #ifdef SOLARIS
107  NumAuthenticationMethod1,
108  NumAuthenticationMethod2
109 #else
111 #endif
112  };
113 
116  PBoolean StartTLS();
117 
120  PBoolean Bind(
121  const PString & who = PString::Empty(),
122  const PString & passwd = PString::Empty(),
123  AuthenticationMethod authMethod = AuthSimple
124  );
125 
126  class ModAttrib : public PObject {
127  PCLASSINFO(ModAttrib, PObject);
128  public:
129  enum Operation {
134  };
135 
136  protected:
137  ModAttrib(
138  const PString & name,
140  );
141 
142  public:
143  const PString & GetName() const { return name; }
144 
145  Operation GetOperation() const { return op; }
146 
147  void SetLDAPMod(
148  struct ldapmod & mod,
149  Operation defaultOp
150  );
151 
152  protected:
153  virtual PBoolean IsBinary() const = 0;
154  virtual void SetLDAPModVars(struct ldapmod & mod) = 0;
155 
158  };
159 
160  class StringModAttrib : public ModAttrib {
161  PCLASSINFO(StringModAttrib, ModAttrib);
162  public:
164  const PString & name,
166  );
168  const PString & name,
169  const PString & value,
171  );
173  const PString & name,
174  const PStringList & values,
176  );
177  void SetValue(
178  const PString & value
179  );
180  void AddValue(
181  const PString & value
182  );
183  protected:
184  virtual PBoolean IsBinary() const;
185  virtual void SetLDAPModVars(struct ldapmod & mod);
186 
189  };
190 
191  class BinaryModAttrib : public ModAttrib {
192  PCLASSINFO(BinaryModAttrib, ModAttrib);
193  public:
195  const PString & name,
196  Operation op = Add
197  );
199  const PString & name,
200  const PBYTEArray & value,
201  Operation op = Add
202  );
204  const PString & name,
205  const PArray<PBYTEArray> & values,
206  Operation op = Add
207  );
208  void SetValue(
209  const PBYTEArray & value
210  );
211  void AddValue(
212  const PBYTEArray & value
213  );
214  protected:
215  virtual PBoolean IsBinary() const;
216  virtual void SetLDAPModVars(struct ldapmod & mod);
217 
221  };
222 
225  PBoolean Add(
226  const PString & dn,
227  const PArray<ModAttrib> & attributes
228  );
229 
232  PBoolean Add(
233  const PString & dn,
234  const PStringToString & attributes
235  );
236 
240  PBoolean Add(
241  const PString & dn,
242  const PStringArray & attributes
243  );
244 
248  PBoolean Add(
249  const PString & dn,
250  const PLDAPStructBase & data
251  );
252 
256  const PString & dn,
257  const PArray<ModAttrib> & attributes
258  );
259 
263  const PString & dn,
264  const PStringToString & attributes
265  );
266 
271  const PString & dn,
272  const PStringArray & attributes
273  );
274 
279  const PString & dn,
280  const PLDAPStructBase & data
281  );
282 
286  const PString & dn
287  );
288 
289 
290  enum SearchScope {
295  };
296 
298  public:
299  SearchContext();
300  ~SearchContext();
301 
302  PBoolean IsCompleted() const { return completed; }
303 
304  private:
305  int msgid;
306  struct ldapmsg * result;
307  struct ldapmsg * message;
308  PBoolean found;
309  PBoolean completed;
310 
311  friend class PLDAPSession;
312  };
313 
317  SearchContext & context,
318  const PString & filter,
319  const PStringArray & attributes = PStringList(),
320  const PString & base = PString::Empty(),
321  SearchScope scope = ScopeSubTree
322  );
323 
327  SearchContext & context,
328  PStringToString & data
329  );
330 
334  SearchContext & context,
335  const PString & attribute,
336  PString & data
337  );
338 
342  SearchContext & context,
343  const PString & attribute,
344  PStringArray & data
345  );
346 
350  SearchContext & context,
351  const PString & attribute,
352  PArray<PBYTEArray> & data
353  );
354 
358  SearchContext & context,
359  PLDAPStructBase & data
360  );
361 
365  SearchContext & context
366  );
367 
371  SearchContext & context
372  );
373 
379  const PString & filter,
380  const PStringArray & attributes = PStringList(),
381  const PString & base = PString::Empty(),
382  SearchScope scope = ScopeSubTree
383  );
384 
385 
388  void SetBaseDN(
389  const PString & dn
390  ) { defaultBaseDN = dn; }
391 
394  const PString & GetBaseDN() const { return defaultBaseDN; }
395 
398  int GetErrorNumber() const { return errorNumber; }
399 
402  PString GetErrorText() const;
403 
406  struct ldap * GetOpenLDAP() const { return ldapContext; }
407 
410  const PTimeInterval & GetTimeout() const { return timeout; }
411 
415  const PTimeInterval & t
416  ) { timeout = t; }
417 
421  const unsigned s
422  ) { searchLimit = s; }
423 
424  protected:
425  struct ldap * ldapContext;
427  unsigned protocolVersion;
429  unsigned searchLimit;
432 };
433 
434 
435 
436 class PLDAPStructBase;
437 
439 {
440  PCLASSINFO(PLDAPAttributeBase, PObject);
441  public:
442  PLDAPAttributeBase(const char * name, void * pointer, PINDEX size);
443 
444  const char * GetName() const { return name; }
445  PBoolean IsBinary() const { return pointer != NULL; }
446 
447  virtual void Copy(const PLDAPAttributeBase & other) = 0;
448 
449  virtual PString ToString() const;
450  virtual void FromString(const PString & str);
451  virtual PBYTEArray ToBinary() const;
452  virtual void FromBinary(const PArray<PBYTEArray> & data);
453 
454  protected:
455  const char * name;
456  void * pointer;
457  PINDEX size;
458 };
459 
460 
461 class PLDAPStructBase : public PObject {
462  PCLASSINFO(PLDAPStructBase, PObject);
463  protected:
464  PLDAPStructBase();
466  PLDAPStructBase & operator=(const PStringArray & array);
467  PLDAPStructBase & operator=(const PStringToString & dict);
468  private:
469  PLDAPStructBase(const PLDAPStructBase & obj) : PObject(obj) { }
470 
471  public:
472  void PrintOn(ostream & strm) const;
473 
474  PINDEX GetNumAttributes() const { return attributes.GetSize(); }
475  PLDAPAttributeBase & GetAttribute(PINDEX idx) const { return attributes.GetDataAt(idx); }
476  PLDAPAttributeBase * GetAttribute(const char * name) const { return attributes.GetAt(name); }
477 
478  void AddAttribute(PLDAPAttributeBase * var);
480 
481  protected:
482  void EndConstructor();
483 
485 
489 };
490 
492 
493 class PLDAPSchema : public PObject
494 {
495  public:
496  PLDAPSchema();
497 
503  };
504 
505  class Attribute
506  {
507  public:
509  Attribute(const PString & name, AttributeType type);
512  };
513 
514  typedef std::list<Attribute> attributeList;
515 
516  static PLDAPSchema * CreateSchema(const PString & schemaname, PPluginManager * pluginMgr = NULL);
517  static PStringList GetSchemaNames(PPluginManager * pluginMgr = NULL);
518  static PStringList GetSchemaFriendlyNames(const PString & schema, PPluginManager * pluginMgr = NULL);
519 
520  void OnReceivedAttribute(const PString & attribute, const PString & value);
521 
524 
525  void LoadSchema();
526 
528  virtual void AttributeList(attributeList & /*attrib*/) {};
529 
530 
532  PBoolean Exists(const PString & attribute);
533 
534  PBoolean SetAttribute(const PString & attribute, const PString & value);
535  PBoolean SetAttribute(const PString & attribute, const PBYTEArray & value);
536 
537  PBoolean GetAttribute(const PString & attribute, PString & value);
538  PBoolean GetAttribute(const PString & attribute, PBYTEArray & value);
539 
540  AttributeType GetAttributeType(const PString & attribute);
541 
542 
543  protected:
544  typedef std::map<PString,PString> ldapAttributes;
545  typedef std::map<PString,PBYTEArray> ldapBinAttributes;
546 
547 
548  attributeList attributelist;
549  ldapAttributes attributes;
550  ldapBinAttributes binattributes;
551 };
552 
553 
554 template <class className> class LDAPPluginServiceDescriptor : public PDevicePluginServiceDescriptor
555 {
556  public:
557  virtual PObject * CreateInstance(int /*userData*/) const { return new className; }
558  virtual PStringArray GetDeviceNames(int /*userData*/) const { return className::SchemaName(); }
559 };
560 
561 #define LDAP_Schema(name) \
562  static LDAPPluginServiceDescriptor<name##_schema> name##_schema_descriptor; \
563  PCREATE_PLUGIN(name##_schema, PLDAPSchema, &name##_schema_descriptor)
564 
566 
567 #define PLDAP_STRUCT_BEGIN(name) \
568  class name : public PLDAPStructBase { \
569  public: name() : PLDAPStructBase() { EndConstructor(); } \
570  public: name(const name & other) : PLDAPStructBase() { EndConstructor(); operator=(other); } \
571  public: name(const PStringArray & array) : PLDAPStructBase() { EndConstructor(); operator=(array); } \
572  public: name(const PStringToString & dict) : PLDAPStructBase() { EndConstructor(); operator=(dict); } \
573  public: name & operator=(const name & other) { PLDAPStructBase::operator=(other); return *this; } \
574  public: name & operator=(const PStringArray & array) { PLDAPStructBase::operator=(array); return *this; } \
575  public: name & operator=(const PStringToString & dict) { PLDAPStructBase::operator=(dict); return *this; } \
576  PLDAP_ATTR_INIT(name, PString, objectClass, #name);
577 
578 #define PLDAP_ATTRIBUTE(base, type, attribute, pointer, init) \
579  public: type attribute; \
580  private: struct PLDAPAttr_##attribute : public PLDAPAttributeBase { \
581  PLDAPAttr_##attribute() \
582  : PLDAPAttributeBase(#attribute, pointer, sizeof(type)), \
583  instance(((base &)base::GetInitialiser()).attribute) \
584  { init } \
585  virtual void PrintOn (ostream & s) const { s << instance; } \
586  virtual void ReadFrom(istream & s) { s >> instance; } \
587  virtual void Copy(const PLDAPAttributeBase & other) \
588  { instance = ((PLDAPAttr_##attribute &)other).instance; } \
589  type & instance; \
590  } pldapvar_##attribute
591 
592 #define PLDAP_ATTR_SIMP(base, type, attribute) \
593  PLDAP_ATTRIBUTE(base, type, attribute, NULL, ;)
594 
595 #define PLDAP_ATTR_INIT(base, type, attribute, init) \
596  PLDAP_ATTRIBUTE(base, type, attribute, NULL, instance = init;)
597 
598 #define PLDAP_BINATTRIB(base, type, attribute) \
599  PLDAP_ATTRIBUTE(base, type, attribute, &((base &)base::GetInitialiser()).attribute, ;)
600 
601 #define PLDAP_STRUCT_END() \
602  };
603 
604 #endif // P_LDAP
605 
606 #endif // PTLIB_PLDAP_H
607 
608 
609 // End of file ////////////////////////////////////////////////////////////////
AttributeType GetAttributeType(const PString &attribute)
Definition: pldap.h:499
Definition: pldap.h:293
PLDAPAttributeBase * GetAttribute(const char *name) const
Definition: pldap.h:476
void SetSearchLimit(const unsigned s)
Set a limit on the number of results to return.
Definition: pldap.h:420
ldapAttributes attributes
Definition: pldap.h:549
PString defaultBaseDN
Definition: pldap.h:428
Operation op
Definition: pldap.h:157
Definition: pldap.h:126
void SetTimeout(const PTimeInterval &t)
Set the timeout for LDAP operations.
Definition: pldap.h:414
This class defines an arbitrary time interval to millisecond accuracy.
Definition: timeint.h:55
PBoolean Modify(const PString &dn, const PArray< ModAttrib > &attributes)
Modify an existing distringuished name to LDAP dirctory.
PBoolean Delete(const PString &dn)
Delete the distinguished name from LDAP directory.
Definition: pldap.h:297
Definition: pldap.h:554
Definition: plugin.h:109
std::map< PString, PBYTEArray > ldapBinAttributes
Definition: pldap.h:545
static PLDAPStructBase * initialiserInstance
Definition: pldap.h:488
PString name
Definition: pldap.h:156
std::map< PString, PString > ldapAttributes
Definition: pldap.h:544
static PLDAPSchema * CreateSchema(const PString &schemaname, PPluginManager *pluginMgr=NULL)
const PTimeInterval & GetTimeout() const
Get the timeout for LDAP operations.
Definition: pldap.h:410
Definition: pluginmgr.h:57
virtual PString ToString() const
virtual PObject * CreateInstance(int) const
Definition: pldap.h:557
virtual void FromBinary(const PArray< PBYTEArray > &data)
PBoolean Open(const PString &server, WORD port=0)
Open the LDAP session to the specified server.
attributeList attributelist
Definition: pldap.h:548
unsigned searchLimit
Definition: pldap.h:429
PStringList GetAttributeList()
virtual PBoolean IsBinary() const
Definition: pldap.h:105
ModAttrib(const PString &name, Operation op=NumOperations)
This is a dictionary collection class of PString objects, keyed by another string.
Definition: pstring.h:2784
AttributeType m_type
Definition: pldap.h:511
virtual PStringArray GetDeviceNames(int) const
Definition: pldap.h:558
PBoolean GetNextSearchResult(SearchContext &context)
Get the next search result.
void SetValue(const PString &value)
void OnReceivedAttribute(const PString &attribute, const PString &value)
static PLDAPStructBase & GetInitialiser()
Definition: pldap.h:479
This class will create an LDAP client to access a remote LDAP server.
Definition: pldap.h:55
Definition: pldap.h:130
PStringArray values
Definition: pldap.h:187
void EndConstructor()
StringModAttrib(const PString &name, Operation op=NumOperations)
PLDAPSession(const PString &defaultBaseDN=PString::Empty())
Create a LDAP client.
virtual void AttributeList(attributeList &)
Definition: pldap.h:528
static PStringList GetSchemaNames(PPluginManager *pluginMgr=NULL)
SearchScope
Definition: pldap.h:290
This is an array collection class of PString objects.
Definition: pstring.h:2024
PString multipleValueSeparator
Definition: pldap.h:431
PBoolean GetAttribute(const PString &attribute, PString &value)
Definition: pldap.h:500
Definition: pldap.h:103
PString GetErrorText() const
Get the last OpenLDAP error as text string.
Definition: pldap.h:291
This template class maps the PAbstractList to a specific object type.
Definition: lists.h:321
AttributeType
Definition: pldap.h:498
PObject()
Constructor for PObject, made protected so cannot ever create one on its own.
Definition: object.h:1124
Definition: pldap.h:501
void SetBaseDN(const PString &dn)
Set the default base DN for use if not specified for searches.
Definition: pldap.h:388
BOOL PBoolean
Definition: object.h:102
struct ldap * GetOpenLDAP() const
Get the OpenLDAP context structure.
Definition: pldap.h:406
void AddAttribute(PLDAPAttributeBase *var)
PBoolean Search(SearchContext &context, const PString &filter, const PStringArray &attributes=PStringList(), const PString &base=PString::Empty(), SearchScope scope=ScopeSubTree)
Start search for specified information.
virtual PBoolean IsBinary() const
Array of unsigned characters.
Definition: array.h:670
PBoolean Bind(const PString &who=PString::Empty(), const PString &passwd=PString::Empty(), AuthenticationMethod authMethod=AuthSimple)
Bind to the remote LDAP server.
virtual PBYTEArray ToBinary() const
PBoolean SetOption(int optcode, int value)
Set LDAP option parameter (OpenLDAp specific values)
Definition: pldap.h:502
D & GetDataAt(PINDEX index) const
Get the data in the dictionary at the ordinal index position.
Definition: dict.h:969
#define PAssertNULL(ptr)
This macro is used to assert that a pointer must be non-null.
Definition: object.h:220
virtual PINDEX GetSize() const
Get the current size of the container.
virtual void SetLDAPModVars(struct ldapmod &mod)
void AddValue(const PBYTEArray &value)
Definition: pldap.h:493
PDictionary< PString, PLDAPAttributeBase > attributes
Definition: pldap.h:484
static PStringList GetSchemaFriendlyNames(const PString &schema, PPluginManager *pluginMgr=NULL)
Definition: pldap.h:292
Definition: pldap.h:104
PLDAPAttributeBase(const char *name, void *pointer, PINDEX size)
The character string class.
Definition: pstring.h:108
PINDEX size
Definition: pldap.h:457
virtual D * GetAt(const K &key) const
Get the object at the specified key position.
Definition: dict.h:938
PLDAPStructBase * initialiserStack
Definition: pldap.h:486
Definition: pldap.h:191
static PString Empty()
Return an empty string.
virtual void SetLDAPModVars(struct ldapmod &mod)
ldapBinAttributes binattributes
Definition: pldap.h:550
PBoolean IsOpen() const
Determine of session is open.
Definition: pldap.h:86
PBoolean StartTLS()
Start encrypted connection.
PString m_name
Definition: pldap.h:510
PBoolean Add(const PString &dn, const PArray< ModAttrib > &attributes)
Add a new distringuished name to LDAP dirctory.
This is a list collection class of PString objects.
Definition: pstring.h:2184
PTimeInterval timeout
Definition: pldap.h:430
int GetErrorNumber() const
Get the last OpenLDAP error code.
Definition: pldap.h:398
std::list< Attribute > attributeList
Definition: pldap.h:514
PLDAPStructBase & operator=(const PLDAPStructBase &)
static PMutex initialiserMutex
Definition: pldap.h:487
const char * GetName() const
Definition: pldap.h:444
Definition: pldap.h:131
Definition: pldap.h:461
void SetValue(const PBYTEArray &value)
struct ldap * ldapContext
Definition: pldap.h:425
PBYTEArray bervals
Definition: pldap.h:220
const PString & GetBaseDN() const
Set the default base DN for use if not specified for searches.
Definition: pldap.h:394
Operation GetOperation() const
Definition: pldap.h:145
Attribute()
Definition: pldap.h:508
PBoolean SetAttribute(const PString &attribute, const PString &value)
PStringList SchemaName()
Definition: pldap.h:527
Definition: pldap.h:160
const char * name
Definition: pldap.h:455
Definition: pldap.h:132
Synonym for PTimedMutex.
const PString & GetName() const
Definition: pldap.h:143
Definition: pldap.h:294
PBoolean Close()
Close the LDAP session.
void AddValue(const PString &value)
void SetLDAPMod(struct ldapmod &mod, Operation defaultOp)
BinaryModAttrib(const PString &name, Operation op=Add)
PBoolean IsCompleted() const
Definition: pldap.h:302
Definition: pldap.h:438
virtual void Copy(const PLDAPAttributeBase &other)=0
PBaseArray< char * > pointers
Definition: pldap.h:188
PINDEX GetNumAttributes() const
Definition: pldap.h:474
void * pointer
Definition: pldap.h:456
virtual void SetLDAPModVars(struct ldapmod &mod)=0
~PLDAPSession()
Close the sesison on destruction.
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
void LoadSchema()
PArray< PBYTEArray > values
Definition: pldap.h:218
PBoolean Exists(const PString &attribute)
PLDAPAttributeBase & GetAttribute(PINDEX idx) const
Definition: pldap.h:475
Operation
Definition: pldap.h:129
unsigned protocolVersion
Definition: pldap.h:427
AuthenticationMethod
Definition: pldap.h:102
void OnSendSchema(PArray< PLDAPSession::ModAttrib > &attributes, PLDAPSession::ModAttrib::Operation op=PLDAPSession::ModAttrib::Add)
PBoolean IsBinary() const
Definition: pldap.h:445
virtual PBoolean IsBinary() const =0
PBaseArray< struct berval * > pointers
Definition: pldap.h:219
Definition: pldap.h:505
PString GetSearchResultDN(SearchContext &context)
Get the current search result distinguished name entry.
virtual void FromString(const PString &str)
PBoolean GetSearchResult(SearchContext &context, PStringToString &data)
Get the current search result entry.
int errorNumber
Definition: pldap.h:426
void PrintOn(ostream &strm) const
Output the contents of the object to the stream.