PTLib  Version 2.10.10
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
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 
107  };
108 
111  PBoolean StartTLS();
112 
115  PBoolean Bind(
116  const PString & who = PString::Empty(),
117  const PString & passwd = PString::Empty(),
118  AuthenticationMethod authMethod = AuthSimple
119  );
120 
121  class ModAttrib : public PObject {
122  PCLASSINFO(ModAttrib, PObject);
123  public:
124  enum Operation {
129  };
130 
131  protected:
132  ModAttrib(
133  const PString & name,
135  );
136 
137  public:
138  const PString & GetName() const { return name; }
139 
140  Operation GetOperation() const { return op; }
141 
142  void SetLDAPMod(
143  struct ldapmod & mod,
144  Operation defaultOp
145  );
146 
147  protected:
148  virtual PBoolean IsBinary() const = 0;
149  virtual void SetLDAPModVars(struct ldapmod & mod) = 0;
150 
153  };
154 
155  class StringModAttrib : public ModAttrib {
156  PCLASSINFO(StringModAttrib, ModAttrib);
157  public:
159  const PString & name,
161  );
163  const PString & name,
164  const PString & value,
166  );
168  const PString & name,
169  const PStringList & values,
171  );
172  void SetValue(
173  const PString & value
174  );
175  void AddValue(
176  const PString & value
177  );
178  protected:
179  virtual PBoolean IsBinary() const;
180  virtual void SetLDAPModVars(struct ldapmod & mod);
181 
184  };
185 
186  class BinaryModAttrib : public ModAttrib {
187  PCLASSINFO(BinaryModAttrib, ModAttrib);
188  public:
190  const PString & name,
191  Operation op = Add
192  );
194  const PString & name,
195  const PBYTEArray & value,
196  Operation op = Add
197  );
199  const PString & name,
200  const PArray<PBYTEArray> & values,
201  Operation op = Add
202  );
203  void SetValue(
204  const PBYTEArray & value
205  );
206  void AddValue(
207  const PBYTEArray & value
208  );
209  protected:
210  virtual PBoolean IsBinary() const;
211  virtual void SetLDAPModVars(struct ldapmod & mod);
212 
216  };
217 
220  PBoolean Add(
221  const PString & dn,
222  const PArray<ModAttrib> & attributes
223  );
224 
227  PBoolean Add(
228  const PString & dn,
229  const PStringToString & attributes
230  );
231 
235  PBoolean Add(
236  const PString & dn,
237  const PStringArray & attributes
238  );
239 
243  PBoolean Add(
244  const PString & dn,
245  const PLDAPStructBase & data
246  );
247 
251  const PString & dn,
252  const PArray<ModAttrib> & attributes
253  );
254 
258  const PString & dn,
259  const PStringToString & attributes
260  );
261 
266  const PString & dn,
267  const PStringArray & attributes
268  );
269 
274  const PString & dn,
275  const PLDAPStructBase & data
276  );
277 
281  const PString & dn
282  );
283 
284 
285  enum SearchScope {
290  };
291 
293  public:
294  SearchContext();
295  ~SearchContext();
296 
297  PBoolean IsCompleted() const { return completed; }
298 
299  private:
300  int msgid;
301  struct ldapmsg * result;
302  struct ldapmsg * message;
303  PBoolean found;
304  PBoolean completed;
305 
306  friend class PLDAPSession;
307  };
308 
312  SearchContext & context,
313  const PString & filter,
314  const PStringArray & attributes = PStringList(),
315  const PString & base = PString::Empty(),
316  SearchScope scope = ScopeSubTree
317  );
318 
322  SearchContext & context,
323  PStringToString & data
324  );
325 
329  SearchContext & context,
330  const PString & attribute,
331  PString & data
332  );
333 
337  SearchContext & context,
338  const PString & attribute,
339  PStringArray & data
340  );
341 
345  SearchContext & context,
346  const PString & attribute,
347  PArray<PBYTEArray> & data
348  );
349 
353  SearchContext & context,
354  PLDAPStructBase & data
355  );
356 
360  SearchContext & context
361  );
362 
366  SearchContext & context
367  );
368 
374  const PString & filter,
375  const PStringArray & attributes = PStringList(),
376  const PString & base = PString::Empty(),
377  SearchScope scope = ScopeSubTree
378  );
379 
380 
383  void SetBaseDN(
384  const PString & dn
385  ) { defaultBaseDN = dn; }
386 
389  const PString & GetBaseDN() const { return defaultBaseDN; }
390 
393  int GetErrorNumber() const { return errorNumber; }
394 
397  PString GetErrorText() const;
398 
401  struct ldap * GetOpenLDAP() const { return ldapContext; }
402 
405  const PTimeInterval & GetTimeout() const { return timeout; }
406 
410  const PTimeInterval & t
411  ) { timeout = t; }
412 
416  const unsigned s
417  ) { searchLimit = s; }
418 
419  protected:
420  struct ldap * ldapContext;
422  unsigned protocolVersion;
424  unsigned searchLimit;
427 };
428 
429 
430 
431 class PLDAPStructBase;
432 
434 {
435  PCLASSINFO(PLDAPAttributeBase, PObject);
436  public:
437  PLDAPAttributeBase(const char * name, void * pointer, PINDEX size);
438 
439  const char * GetName() const { return name; }
440  PBoolean IsBinary() const { return pointer != NULL; }
441 
442  virtual void Copy(const PLDAPAttributeBase & other) = 0;
443 
444  virtual PString ToString() const;
445  virtual void FromString(const PString & str);
446  virtual PBYTEArray ToBinary() const;
447  virtual void FromBinary(const PArray<PBYTEArray> & data);
448 
449  protected:
450  const char * name;
451  void * pointer;
452  PINDEX size;
453 };
454 
455 
456 class PLDAPStructBase : public PObject {
457  PCLASSINFO(PLDAPStructBase, PObject);
458  protected:
459  PLDAPStructBase();
461  PLDAPStructBase & operator=(const PStringArray & array);
462  PLDAPStructBase & operator=(const PStringToString & dict);
463  private:
464  PLDAPStructBase(const PLDAPStructBase & obj) : PObject(obj) { }
465 
466  public:
467  void PrintOn(ostream & strm) const;
468 
469  PINDEX GetNumAttributes() const { return attributes.GetSize(); }
470  PLDAPAttributeBase & GetAttribute(PINDEX idx) const { return attributes.GetDataAt(idx); }
471  PLDAPAttributeBase * GetAttribute(const char * name) const { return attributes.GetAt(name); }
472 
473  void AddAttribute(PLDAPAttributeBase * var);
475 
476  protected:
477  void EndConstructor();
478 
480 
484 };
485 
487 
488 class PLDAPSchema : public PObject
489 {
490  public:
491  PLDAPSchema();
492 
498  };
499 
500  class Attribute
501  {
502  public:
504  Attribute(const PString & name, AttributeType type);
507  };
508 
509  typedef std::list<Attribute> attributeList;
510 
511  static PLDAPSchema * CreateSchema(const PString & schemaname, PPluginManager * pluginMgr = NULL);
512  static PStringList GetSchemaNames(PPluginManager * pluginMgr = NULL);
513  static PStringList GetSchemaFriendlyNames(const PString & schema, PPluginManager * pluginMgr = NULL);
514 
515  void OnReceivedAttribute(const PString & attribute, const PString & value);
516 
519 
520  void LoadSchema();
521 
523  virtual void AttributeList(attributeList & /*attrib*/) {};
524 
525 
527  PBoolean Exists(const PString & attribute);
528 
529  PBoolean SetAttribute(const PString & attribute, const PString & value);
530  PBoolean SetAttribute(const PString & attribute, const PBYTEArray & value);
531 
532  PBoolean GetAttribute(const PString & attribute, PString & value);
533  PBoolean GetAttribute(const PString & attribute, PBYTEArray & value);
534 
535  AttributeType GetAttributeType(const PString & attribute);
536 
537 
538  protected:
539  typedef std::map<PString,PString> ldapAttributes;
540  typedef std::map<PString,PBYTEArray> ldapBinAttributes;
541 
542 
546 };
547 
548 
549 template <class className> class LDAPPluginServiceDescriptor : public PDevicePluginServiceDescriptor
550 {
551  public:
552  virtual PObject * CreateInstance(int /*userData*/) const { return new className; }
553  virtual PStringArray GetDeviceNames(int /*userData*/) const { return className::SchemaName(); }
554 };
555 
556 #define LDAP_Schema(name) \
557  static LDAPPluginServiceDescriptor<name##_schema> name##_schema_descriptor; \
558  PCREATE_PLUGIN(name##_schema, PLDAPSchema, &name##_schema_descriptor)
559 
561 
562 #define PLDAP_STRUCT_BEGIN(name) \
563  class name : public PLDAPStructBase { \
564  public: name() : PLDAPStructBase() { EndConstructor(); } \
565  public: name(const name & other) : PLDAPStructBase() { EndConstructor(); operator=(other); } \
566  public: name(const PStringArray & array) : PLDAPStructBase() { EndConstructor(); operator=(array); } \
567  public: name(const PStringToString & dict) : PLDAPStructBase() { EndConstructor(); operator=(dict); } \
568  public: name & operator=(const name & other) { PLDAPStructBase::operator=(other); return *this; } \
569  public: name & operator=(const PStringArray & array) { PLDAPStructBase::operator=(array); return *this; } \
570  public: name & operator=(const PStringToString & dict) { PLDAPStructBase::operator=(dict); return *this; } \
571  PLDAP_ATTR_INIT(name, PString, objectClass, #name);
572 
573 #define PLDAP_ATTRIBUTE(base, type, attribute, pointer, init) \
574  public: type attribute; \
575  private: struct PLDAPAttr_##attribute : public PLDAPAttributeBase { \
576  PLDAPAttr_##attribute() \
577  : PLDAPAttributeBase(#attribute, pointer, sizeof(type)), \
578  instance(((base &)base::GetInitialiser()).attribute) \
579  { init } \
580  virtual void PrintOn (ostream & s) const { s << instance; } \
581  virtual void ReadFrom(istream & s) { s >> instance; } \
582  virtual void Copy(const PLDAPAttributeBase & other) \
583  { instance = ((PLDAPAttr_##attribute &)other).instance; } \
584  type & instance; \
585  } pldapvar_##attribute
586 
587 #define PLDAP_ATTR_SIMP(base, type, attribute) \
588  PLDAP_ATTRIBUTE(base, type, attribute, NULL, ;)
589 
590 #define PLDAP_ATTR_INIT(base, type, attribute, init) \
591  PLDAP_ATTRIBUTE(base, type, attribute, NULL, instance = init;)
592 
593 #define PLDAP_BINATTRIB(base, type, attribute) \
594  PLDAP_ATTRIBUTE(base, type, attribute, &((base &)base::GetInitialiser()).attribute, ;)
595 
596 #define PLDAP_STRUCT_END() \
597  };
598 
599 #endif // P_LDAP
600 
601 #endif // PTLIB_PLDAP_H
602 
603 
604 // End of file ////////////////////////////////////////////////////////////////
AttributeType GetAttributeType(const PString &attribute)
Definition: pldap.h:494
Definition: pldap.h:288
PLDAPAttributeBase * GetAttribute(const char *name) const
Definition: pldap.h:471
void SetSearchLimit(const unsigned s)
Set a limit on the number of results to return.
Definition: pldap.h:415
ldapAttributes attributes
Definition: pldap.h:544
PString defaultBaseDN
Definition: pldap.h:423
Operation op
Definition: pldap.h:152
Definition: pldap.h:121
void SetTimeout(const PTimeInterval &t)
Set the timeout for LDAP operations.
Definition: pldap.h:409
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:292
Definition: pldap.h:549
Definition: plugin.h:109
std::map< PString, PBYTEArray > ldapBinAttributes
Definition: pldap.h:540
static PLDAPStructBase * initialiserInstance
Definition: pldap.h:483
PString name
Definition: pldap.h:151
std::map< PString, PString > ldapAttributes
Definition: pldap.h:539
static PLDAPSchema * CreateSchema(const PString &schemaname, PPluginManager *pluginMgr=NULL)
const PTimeInterval & GetTimeout() const
Get the timeout for LDAP operations.
Definition: pldap.h:405
Definition: pluginmgr.h:57
virtual PString ToString() const
virtual PObject * CreateInstance(int) const
Definition: pldap.h:552
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:543
unsigned searchLimit
Definition: pldap.h:424
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:506
virtual PStringArray GetDeviceNames(int) const
Definition: pldap.h:553
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:474
This class will create an LDAP client to access a remote LDAP server.
Definition: pldap.h:55
Definition: pldap.h:125
PStringArray values
Definition: pldap.h:182
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:523
static PStringList GetSchemaNames(PPluginManager *pluginMgr=NULL)
SearchScope
Definition: pldap.h:285
This is an array collection class of PString objects.
Definition: pstring.h:2024
PString multipleValueSeparator
Definition: pldap.h:426
PBoolean GetAttribute(const PString &attribute, PString &value)
Definition: pldap.h:495
Definition: pldap.h:103
PString GetErrorText() const
Get the last OpenLDAP error as text string.
Definition: pldap.h:286
This template class maps the PAbstractList to a specific object type.
Definition: lists.h:321
AttributeType
Definition: pldap.h:493
PObject()
Constructor for PObject, made protected so cannot ever create one on its own.
Definition: object.h:1124
Definition: pldap.h:496
void SetBaseDN(const PString &dn)
Set the default base DN for use if not specified for searches.
Definition: pldap.h:383
BOOL PBoolean
Definition: object.h:102
struct ldap * GetOpenLDAP() const
Get the OpenLDAP context structure.
Definition: pldap.h:401
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:497
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:488
PDictionary< PString, PLDAPAttributeBase > attributes
Definition: pldap.h:479
static PStringList GetSchemaFriendlyNames(const PString &schema, PPluginManager *pluginMgr=NULL)
Definition: pldap.h:287
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:452
virtual D * GetAt(const K &key) const
Get the object at the specified key position.
Definition: dict.h:938
PLDAPStructBase * initialiserStack
Definition: pldap.h:481
Definition: pldap.h:186
static PString Empty()
Return an empty string.
virtual void SetLDAPModVars(struct ldapmod &mod)
ldapBinAttributes binattributes
Definition: pldap.h:545
PBoolean IsOpen() const
Determine of session is open.
Definition: pldap.h:86
PBoolean StartTLS()
Start encrypted connection.
PString m_name
Definition: pldap.h:505
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:425
int GetErrorNumber() const
Get the last OpenLDAP error code.
Definition: pldap.h:393
std::list< Attribute > attributeList
Definition: pldap.h:509
PLDAPStructBase & operator=(const PLDAPStructBase &)
static PMutex initialiserMutex
Definition: pldap.h:482
const char * GetName() const
Definition: pldap.h:439
Definition: pldap.h:126
Definition: pldap.h:456
void SetValue(const PBYTEArray &value)
struct ldap * ldapContext
Definition: pldap.h:420
PBYTEArray bervals
Definition: pldap.h:215
const PString & GetBaseDN() const
Set the default base DN for use if not specified for searches.
Definition: pldap.h:389
Operation GetOperation() const
Definition: pldap.h:140
Attribute()
Definition: pldap.h:503
PBoolean SetAttribute(const PString &attribute, const PString &value)
PStringList SchemaName()
Definition: pldap.h:522
Definition: pldap.h:155
const char * name
Definition: pldap.h:450
Definition: pldap.h:127
Synonym for PTimedMutex.
const PString & GetName() const
Definition: pldap.h:138
Definition: pldap.h:289
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:297
Definition: pldap.h:433
virtual void Copy(const PLDAPAttributeBase &other)=0
PBaseArray< char * > pointers
Definition: pldap.h:183
PINDEX GetNumAttributes() const
Definition: pldap.h:469
void * pointer
Definition: pldap.h:451
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:213
PBoolean Exists(const PString &attribute)
PLDAPAttributeBase & GetAttribute(PINDEX idx) const
Definition: pldap.h:470
Operation
Definition: pldap.h:124
unsigned protocolVersion
Definition: pldap.h:422
AuthenticationMethod
Definition: pldap.h:102
void OnSendSchema(PArray< PLDAPSession::ModAttrib > &attributes, PLDAPSession::ModAttrib::Operation op=PLDAPSession::ModAttrib::Add)
PBoolean IsBinary() const
Definition: pldap.h:440
virtual PBoolean IsBinary() const =0
PBaseArray< struct berval * > pointers
Definition: pldap.h:214
Definition: pldap.h:500
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:421
void PrintOn(ostream &strm) const
Output the contents of the object to the stream.