pldap.h
Go to the documentation of this file.
/*
* pldap.h
*
* Lightweight Directory Access Protocol interface class.
*
* Portable Windows Library
*
* Copyright (c) 1993-2003 Equivalence Pty. Ltd.
*
* The contents of this file are subject to the Mozilla Public License
* Version 1.0 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS"
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
* the License for the specific language governing rights and limitations
* under the License.
*
* The Original Code is Portable Windows Library.
*
* The Initial Developer of the Original Code is Equivalence Pty. Ltd.
*
* Contributor(s): ______________________________________.
*
* $Revision: 27535 $
* $Author: rjongbloed $
* $Date: 2012-04-26 02:48:22 -0500 (Thu, 26 Apr 2012) $
*/
#ifndef PTLIB_PLDAP_H
#define PTLIB_PLDAP_H
#ifdef P_USE_PRAGMA
#pragma interface
#endif
#if defined(P_LDAP) && !defined(_WIN32_WCE)
#include <ptlib/sockets.h>
#include <ptlib/pluginmgr.h>
#include <map>
#include <list>
struct ldap;
struct ldapmsg;
struct ldapmod;
struct berval;
class PLDAPStructBase;
class PLDAPSession : public PObject
{
PCLASSINFO(PLDAPSession, PObject);
public:
PLDAPSession(
const PString & defaultBaseDN = PString::Empty()
);
~PLDAPSession();
PBoolean Open(
const PString & server,
WORD port = 0
);
PBoolean Close();
PBoolean IsOpen() const { return ldapContext != NULL; }
PBoolean SetOption(
int optcode,
int value
);
PBoolean SetOption(
int optcode,
void * value
);
enum AuthenticationMethod {
AuthSimple,
AuthSASL,
AuthKerberos,
#ifdef SOLARIS
NumAuthenticationMethod1,
NumAuthenticationMethod2
#else
NumAuthenticationMethod
#endif
};
PBoolean StartTLS();
PBoolean Bind(
const PString & who = PString::Empty(),
const PString & passwd = PString::Empty(),
AuthenticationMethod authMethod = AuthSimple
);
class ModAttrib : public PObject {
PCLASSINFO(ModAttrib, PObject);
public:
enum Operation {
Add,
Replace,
Delete,
NumOperations
};
protected:
ModAttrib(
const PString & name,
Operation op = NumOperations
);
public:
const PString & GetName() const { return name; }
Operation GetOperation() const { return op; }
void SetLDAPMod(
struct ldapmod & mod,
Operation defaultOp
);
protected:
virtual PBoolean IsBinary() const = 0;
virtual void SetLDAPModVars(struct ldapmod & mod) = 0;
PString name;
Operation op;
};
class StringModAttrib : public ModAttrib {
PCLASSINFO(StringModAttrib, ModAttrib);
public:
StringModAttrib(
const PString & name,
Operation op = NumOperations
);
StringModAttrib(
const PString & name,
const PString & value,
Operation op = NumOperations
);
StringModAttrib(
const PString & name,
const PStringList & values,
Operation op = NumOperations
);
void SetValue(
const PString & value
);
void AddValue(
const PString & value
);
protected:
virtual PBoolean IsBinary() const;
virtual void SetLDAPModVars(struct ldapmod & mod);
PStringArray values;
PBaseArray<char *> pointers;
};
class BinaryModAttrib : public ModAttrib {
PCLASSINFO(BinaryModAttrib, ModAttrib);
public:
BinaryModAttrib(
const PString & name,
Operation op = Add
);
BinaryModAttrib(
const PString & name,
const PBYTEArray & value,
Operation op = Add
);
BinaryModAttrib(
const PString & name,
const PArray<PBYTEArray> & values,
Operation op = Add
);
void SetValue(
const PBYTEArray & value
);
void AddValue(
const PBYTEArray & value
);
protected:
virtual PBoolean IsBinary() const;
virtual void SetLDAPModVars(struct ldapmod & mod);
PArray<PBYTEArray> values;
PBaseArray<struct berval *> pointers;
PBYTEArray bervals;
};
PBoolean Add(
const PString & dn,
const PArray<ModAttrib> & attributes
);
PBoolean Add(
const PString & dn,
const PStringToString & attributes
);
PBoolean Add(
const PString & dn,
const PStringArray & attributes
);
PBoolean Add(
const PString & dn,
const PLDAPStructBase & data
);
PBoolean Modify(
const PString & dn,
const PArray<ModAttrib> & attributes
);
PBoolean Modify(
const PString & dn,
const PStringToString & attributes
);
PBoolean Modify(
const PString & dn,
const PStringArray & attributes
);
PBoolean Modify(
const PString & dn,
const PLDAPStructBase & data
);
PBoolean Delete(
const PString & dn
);
enum SearchScope {
ScopeBaseOnly,
ScopeSingleLevel,
ScopeSubTree,
NumSearchScope
};
class SearchContext {
public:
SearchContext();
~SearchContext();
PBoolean IsCompleted() const { return completed; }
private:
int msgid;
struct ldapmsg * result;
struct ldapmsg * message;
PBoolean found;
PBoolean completed;
friend class PLDAPSession;
};
PBoolean Search(
SearchContext & context,
const PString & filter,
const PStringArray & attributes = PStringList(),
const PString & base = PString::Empty(),
SearchScope scope = ScopeSubTree
);
PBoolean GetSearchResult(
SearchContext & context,
PStringToString & data
);
PBoolean GetSearchResult(
SearchContext & context,
const PString & attribute,
PString & data
);
PBoolean GetSearchResult(
SearchContext & context,
const PString & attribute,
PStringArray & data
);
PBoolean GetSearchResult(
SearchContext & context,
const PString & attribute,
PArray<PBYTEArray> & data
);
PBoolean GetSearchResult(
SearchContext & context,
PLDAPStructBase & data
);
PString GetSearchResultDN(
SearchContext & context
);
PBoolean GetNextSearchResult(
SearchContext & context
);
PList<PStringToString> Search(
const PString & filter,
const PStringArray & attributes = PStringList(),
const PString & base = PString::Empty(),
SearchScope scope = ScopeSubTree
);
void SetBaseDN(
const PString & dn
) { defaultBaseDN = dn; }
const PString & GetBaseDN() const { return defaultBaseDN; }
int GetErrorNumber() const { return errorNumber; }
PString GetErrorText() const;
struct ldap * GetOpenLDAP() const { return ldapContext; }
const PTimeInterval & GetTimeout() const { return timeout; }
void SetTimeout(
const PTimeInterval & t
) { timeout = t; }
void SetSearchLimit(
const unsigned s
) { searchLimit = s; }
protected:
struct ldap * ldapContext;
int errorNumber;
unsigned protocolVersion;
PString defaultBaseDN;
unsigned searchLimit;
PTimeInterval timeout;
PString multipleValueSeparator;
};
class PLDAPStructBase;
class PLDAPAttributeBase : public PObject
{
PCLASSINFO(PLDAPAttributeBase, PObject);
public:
PLDAPAttributeBase(const char * name, void * pointer, PINDEX size);
const char * GetName() const { return name; }
PBoolean IsBinary() const { return pointer != NULL; }
virtual void Copy(const PLDAPAttributeBase & other) = 0;
virtual PString ToString() const;
virtual void FromString(const PString & str);
virtual PBYTEArray ToBinary() const;
virtual void FromBinary(const PArray<PBYTEArray> & data);
protected:
const char * name;
void * pointer;
PINDEX size;
};
class PLDAPStructBase : public PObject {
PCLASSINFO(PLDAPStructBase, PObject);
protected:
PLDAPStructBase();
PLDAPStructBase & operator=(const PLDAPStructBase &);
PLDAPStructBase & operator=(const PStringArray & array);
PLDAPStructBase & operator=(const PStringToString & dict);
private:
PLDAPStructBase(const PLDAPStructBase & obj) : PObject(obj) { }
public:
void PrintOn(ostream & strm) const;
PINDEX GetNumAttributes() const { return attributes.GetSize(); }
PLDAPAttributeBase & GetAttribute(PINDEX idx) const { return attributes.GetDataAt(idx); }
PLDAPAttributeBase * GetAttribute(const char * name) const { return attributes.GetAt(name); }
void AddAttribute(PLDAPAttributeBase * var);
static PLDAPStructBase & GetInitialiser() { return *PAssertNULL(initialiserInstance); }
protected:
void EndConstructor();
PDictionary<PString, PLDAPAttributeBase> attributes;
PLDAPStructBase * initialiserStack;
static PMutex initialiserMutex;
static PLDAPStructBase * initialiserInstance;
};
class PLDAPSchema : public PObject
{
public:
PLDAPSchema();
enum AttributeType {
AttibuteUnknown = -1,
AttributeString,
AttributeBinary,
AttributeNumeric
};
class Attribute
{
public:
Attribute() : m_type(AttibuteUnknown) { }
Attribute(const PString & name, AttributeType type);
PString m_name;
AttributeType m_type;
};
typedef std::list<Attribute> attributeList;
static PLDAPSchema * CreateSchema(const PString & schemaname, PPluginManager * pluginMgr = NULL);
static PStringList GetSchemaNames(PPluginManager * pluginMgr = NULL);
static PStringList GetSchemaFriendlyNames(const PString & schema, PPluginManager * pluginMgr = NULL);
void OnReceivedAttribute(const PString & attribute, const PString & value);
void OnSendSchema(PArray<PLDAPSession::ModAttrib> & attributes,
PLDAPSession::ModAttrib::Operation op=PLDAPSession::ModAttrib::Add);
void LoadSchema();
PStringList SchemaName() { return PStringList(); }
virtual void AttributeList(attributeList & /*attrib*/) {};
PStringList GetAttributeList();
PBoolean Exists(const PString & attribute);
PBoolean SetAttribute(const PString & attribute, const PString & value);
PBoolean SetAttribute(const PString & attribute, const PBYTEArray & value);
PBoolean GetAttribute(const PString & attribute, PString & value);
PBoolean GetAttribute(const PString & attribute, PBYTEArray & value);
AttributeType GetAttributeType(const PString & attribute);
protected:
typedef std::map<PString,PString> ldapAttributes;
typedef std::map<PString,PBYTEArray> ldapBinAttributes;
attributeList attributelist;
ldapAttributes attributes;
ldapBinAttributes binattributes;
};
template <class className> class LDAPPluginServiceDescriptor : public PDevicePluginServiceDescriptor
{
public:
virtual PObject * CreateInstance(int /*userData*/) const { return new className; }
virtual PStringArray GetDeviceNames(int /*userData*/) const { return className::SchemaName(); }
};
#define LDAP_Schema(name) \
static LDAPPluginServiceDescriptor<name##_schema> name##_schema_descriptor; \
PCREATE_PLUGIN(name##_schema, PLDAPSchema, &name##_schema_descriptor)
#define PLDAP_STRUCT_BEGIN(name) \
class name : public PLDAPStructBase { \
public: name() : PLDAPStructBase() { EndConstructor(); } \
public: name(const name & other) : PLDAPStructBase() { EndConstructor(); operator=(other); } \
public: name(const PStringArray & array) : PLDAPStructBase() { EndConstructor(); operator=(array); } \
public: name(const PStringToString & dict) : PLDAPStructBase() { EndConstructor(); operator=(dict); } \
public: name & operator=(const name & other) { PLDAPStructBase::operator=(other); return *this; } \
public: name & operator=(const PStringArray & array) { PLDAPStructBase::operator=(array); return *this; } \
public: name & operator=(const PStringToString & dict) { PLDAPStructBase::operator=(dict); return *this; } \
PLDAP_ATTR_INIT(name, PString, objectClass, #name);
#define PLDAP_ATTRIBUTE(base, type, attribute, pointer, init) \
public: type attribute; \
private: struct PLDAPAttr_##attribute : public PLDAPAttributeBase { \
PLDAPAttr_##attribute() \
: PLDAPAttributeBase(#attribute, pointer, sizeof(type)), \
instance(((base &)base::GetInitialiser()).attribute) \
{ init } \
virtual void PrintOn (ostream & s) const { s << instance; } \
virtual void ReadFrom(istream & s) { s >> instance; } \
virtual void Copy(const PLDAPAttributeBase & other) \
{ instance = ((PLDAPAttr_##attribute &)other).instance; } \
type & instance; \
} pldapvar_##attribute
#define PLDAP_ATTR_SIMP(base, type, attribute) \
PLDAP_ATTRIBUTE(base, type, attribute, NULL, ;)
#define PLDAP_ATTR_INIT(base, type, attribute, init) \
PLDAP_ATTRIBUTE(base, type, attribute, NULL, instance = init;)
#define PLDAP_BINATTRIB(base, type, attribute) \
PLDAP_ATTRIBUTE(base, type, attribute, &((base &)base::GetInitialiser()).attribute, ;)
#define PLDAP_STRUCT_END() \
};
#endif // P_LDAP
#endif // PTLIB_PLDAP_H
// End of file ////////////////////////////////////////////////////////////////
PLDAPSession::ScopeSubTree
Definition: pldap.h:293
PLDAPSession::SetSearchLimit
void SetSearchLimit(const unsigned s)
Set a limit on the number of results to return.
Definition: pldap.h:420
PLDAPSchema::attributes
ldapAttributes attributes
Definition: pldap.h:549
PLDAPSession::defaultBaseDN
PString defaultBaseDN
Definition: pldap.h:428
PLDAPSession::ModAttrib::op
Operation op
Definition: pldap.h:157
PLDAPSession::ModAttrib
Definition: pldap.h:126
PLDAPSession::SetTimeout
void SetTimeout(const PTimeInterval &t)
Set the timeout for LDAP operations.
Definition: pldap.h:414
PTimeInterval
This class defines an arbitrary time interval to millisecond accuracy.
Definition: timeint.h:55
PLDAPSession::Modify
PBoolean Modify(const PString &dn, const PArray< ModAttrib > &attributes)
Modify an existing distringuished name to LDAP dirctory.
pluginmgr.h
PCLASSINFO
#define PCLASSINFO(cls, par)
Declare all the standard PTLib class information.
Definition: object.h:1049
PLDAPSession::SearchContext
Definition: pldap.h:297
PBaseArray
This template class maps the PAbstractArray to a specific element type.
Definition: array.h:274
LDAPPluginServiceDescriptor
Definition: pldap.h:554
PDevicePluginServiceDescriptor
Definition: plugin.h:109
PLDAPSchema::ldapBinAttributes
std::map< PString, PBYTEArray > ldapBinAttributes
Definition: pldap.h:545
PLDAPStructBase::initialiserInstance
static PLDAPStructBase * initialiserInstance
Definition: pldap.h:488
LDAPPluginServiceDescriptor::GetDeviceNames
virtual PStringArray GetDeviceNames(int) const
Definition: pldap.h:558
PLDAPSession::ModAttrib::name
PString name
Definition: pldap.h:156
PLDAPSchema::ldapAttributes
std::map< PString, PString > ldapAttributes
Definition: pldap.h:544
PPluginManager
Definition: pluginmgr.h:57
PDictionary< PString, PLDAPAttributeBase >
PLDAPSession::Open
PBoolean Open(const PString &server, WORD port=0)
Open the LDAP session to the specified server.
PLDAPSchema::attributelist
attributeList attributelist
Definition: pldap.h:548
PLDAPSession::searchLimit
unsigned searchLimit
Definition: pldap.h:429
PLDAPSession::AuthKerberos
Definition: pldap.h:105
PLDAPSession::ModAttrib::ModAttrib
ModAttrib(const PString &name, Operation op=NumOperations)
PStringToString
This is a dictionary collection class of PString objects, keyed by another string.
Definition: pstring.h:2784
PLDAPSchema::Attribute::m_type
AttributeType m_type
Definition: pldap.h:511
PLDAPSession::GetNextSearchResult
PBoolean GetNextSearchResult(SearchContext &context)
Get the next search result.
PLDAPStructBase::GetInitialiser
static PLDAPStructBase & GetInitialiser()
Definition: pldap.h:479
PLDAPSession
This class will create an LDAP client to access a remote LDAP server.
Definition: pldap.h:55
PLDAPSession::ModAttrib::Add
Definition: pldap.h:130
PLDAPSession::StringModAttrib::values
PStringArray values
Definition: pldap.h:187
PLDAPSession::PLDAPSession
PLDAPSession(const PString &defaultBaseDN=PString::Empty())
Create a LDAP client.
PLDAPSchema::AttributeList
virtual void AttributeList(attributeList &)
Definition: pldap.h:528
PLDAPSession::SearchScope
SearchScope
Definition: pldap.h:290
PStringArray
This is an array collection class of PString objects.
Definition: pstring.h:2024
PLDAPSession::multipleValueSeparator
PString multipleValueSeparator
Definition: pldap.h:431
PLDAPAttributeBase::GetName
const char * GetName() const
Definition: pldap.h:444
PLDAPSchema::AttributeString
Definition: pldap.h:500
PLDAPSession::AuthSimple
Definition: pldap.h:103
PLDAPSession::ScopeBaseOnly
Definition: pldap.h:291
PLDAPSession::GetErrorNumber
int GetErrorNumber() const
Get the last OpenLDAP error code.
Definition: pldap.h:398
PList
This template class maps the PAbstractList to a specific object type.
Definition: lists.h:321
PLDAPSchema::AttributeType
AttributeType
Definition: pldap.h:498
PObject::PrintOn
virtual void PrintOn(ostream &strm) const
Output the contents of the object to the stream.
PObject::PObject
PObject()
Constructor for PObject, made protected so cannot ever create one on its own.
Definition: object.h:1124
PLDAPSession::ModAttrib::GetName
const PString & GetName() const
Definition: pldap.h:143
PLDAPSchema::AttributeBinary
Definition: pldap.h:501
PLDAPAttributeBase::IsBinary
PBoolean IsBinary() const
Definition: pldap.h:445
PLDAPSession::SetBaseDN
void SetBaseDN(const PString &dn)
Set the default base DN for use if not specified for searches.
Definition: pldap.h:388
PBoolean
BOOL PBoolean
Definition: object.h:102
PLDAPSession::GetErrorText
PString GetErrorText() const
Get the last OpenLDAP error as text string.
PLDAPSession::Search
PBoolean Search(SearchContext &context, const PString &filter, const PStringArray &attributes=PStringList(), const PString &base=PString::Empty(), SearchScope scope=ScopeSubTree)
Start search for specified information.
PBYTEArray
Array of unsigned characters.
Definition: array.h:670
PLDAPSession::Bind
PBoolean Bind(const PString &who=PString::Empty(), const PString &passwd=PString::Empty(), AuthenticationMethod authMethod=AuthSimple)
Bind to the remote LDAP server.
PLDAPSession::SetOption
PBoolean SetOption(int optcode, int value)
Set LDAP option parameter (OpenLDAp specific values)
PLDAPSession::GetTimeout
const PTimeInterval & GetTimeout() const
Get the timeout for LDAP operations.
Definition: pldap.h:410
PAssertNULL
#define PAssertNULL(ptr)
This macro is used to assert that a pointer must be non-null.
Definition: object.h:220
PLDAPSession::GetOpenLDAP
struct ldap * GetOpenLDAP() const
Get the OpenLDAP context structure.
Definition: pldap.h:406
PLDAPSchema
Definition: pldap.h:493
PLDAPStructBase::attributes
PDictionary< PString, PLDAPAttributeBase > attributes
Definition: pldap.h:484
PLDAPSession::ScopeSingleLevel
Definition: pldap.h:292
PLDAPSession::AuthSASL
Definition: pldap.h:104
PLDAPSession::SearchContext::IsCompleted
PBoolean IsCompleted() const
Definition: pldap.h:302
PString
The character string class.
Definition: pstring.h:108
PLDAPAttributeBase::size
PINDEX size
Definition: pldap.h:457
PLDAPStructBase::GetAttribute
PLDAPAttributeBase * GetAttribute(const char *name) const
Definition: pldap.h:476
PLDAPStructBase::initialiserStack
PLDAPStructBase * initialiserStack
Definition: pldap.h:486
PLDAPSession::BinaryModAttrib
Definition: pldap.h:191
PString::Empty
static PString Empty()
Return an empty string.
PLDAPSchema::binattributes
ldapBinAttributes binattributes
Definition: pldap.h:550
PLDAPSession::StartTLS
PBoolean StartTLS()
Start encrypted connection.
PLDAPSchema::Attribute::m_name
PString m_name
Definition: pldap.h:510
PLDAPSession::IsOpen
PBoolean IsOpen() const
Determine of session is open.
Definition: pldap.h:86
PStringList
This is a list collection class of PString objects.
Definition: pstring.h:2184
PLDAPSession::timeout
PTimeInterval timeout
Definition: pldap.h:430
PLDAPSchema::attributeList
std::list< Attribute > attributeList
Definition: pldap.h:514
PLDAPStructBase::initialiserMutex
static PMutex initialiserMutex
Definition: pldap.h:487
PLDAPSession::ModAttrib::Replace
Definition: pldap.h:131
PLDAPStructBase
Definition: pldap.h:461
LDAPPluginServiceDescriptor::CreateInstance
virtual PObject * CreateInstance(int) const
Definition: pldap.h:557
PLDAPSession::ldapContext
struct ldap * ldapContext
Definition: pldap.h:425
PLDAPSession::BinaryModAttrib::bervals
PBYTEArray bervals
Definition: pldap.h:220
PLDAPSchema::Attribute::Attribute
Attribute()
Definition: pldap.h:508
PLDAPSchema::SchemaName
PStringList SchemaName()
Definition: pldap.h:527
PLDAPSession::StringModAttrib
Definition: pldap.h:160
PLDAPAttributeBase::name
const char * name
Definition: pldap.h:455
PArray< PBYTEArray >
PLDAPSession::ModAttrib::Delete
Definition: pldap.h:132
sockets.h
PMutex
Synonym for PTimedMutex.
PLDAPStructBase::GetNumAttributes
PINDEX GetNumAttributes() const
Definition: pldap.h:474
PLDAPSession::NumSearchScope
Definition: pldap.h:294
PLDAPSession::Close
PBoolean Close()
Close the LDAP session.
PLDAPSession::GetBaseDN
const PString & GetBaseDN() const
Set the default base DN for use if not specified for searches.
Definition: pldap.h:394
PLDAPSession::ModAttrib::SetLDAPMod
void SetLDAPMod(struct ldapmod &mod, Operation defaultOp)
PLDAPSession::ModAttrib::NumOperations
Definition: pldap.h:133
PLDAPAttributeBase
Definition: pldap.h:438
PLDAPSession::StringModAttrib::pointers
PBaseArray< char * > pointers
Definition: pldap.h:188
PLDAPAttributeBase::pointer
void * pointer
Definition: pldap.h:456
PLDAPSession::ModAttrib::SetLDAPModVars
virtual void SetLDAPModVars(struct ldapmod &mod)=0
PLDAPSession::~PLDAPSession
~PLDAPSession()
Close the sesison on destruction.
PObject
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
PLDAPSession::BinaryModAttrib::values
PArray< PBYTEArray > values
Definition: pldap.h:218
PLDAPSession::ModAttrib::Operation
Operation
Definition: pldap.h:129
PLDAPSession::protocolVersion
unsigned protocolVersion
Definition: pldap.h:427
PLDAPSession::AuthenticationMethod
AuthenticationMethod
Definition: pldap.h:102
PLDAPSession::ModAttrib::GetOperation
Operation GetOperation() const
Definition: pldap.h:145
PLDAPStructBase::GetAttribute
PLDAPAttributeBase & GetAttribute(PINDEX idx) const
Definition: pldap.h:475
PLDAPSession::NumAuthenticationMethod
Definition: pldap.h:110
PLDAPSession::ModAttrib::IsBinary
virtual PBoolean IsBinary() const =0
PLDAPSession::BinaryModAttrib::pointers
PBaseArray< struct berval * > pointers
Definition: pldap.h:219
PLDAPSchema::Attribute
Definition: pldap.h:505
PLDAPSession::GetSearchResultDN
PString GetSearchResultDN(SearchContext &context)
Get the current search result distinguished name entry.
PLDAPSession::GetSearchResult
PBoolean GetSearchResult(SearchContext &context, PStringToString &data)
Get the current search result entry.
PLDAPSession::errorNumber
int errorNumber
Definition: pldap.h:426