1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
/*
myldap.h - simple interface to do LDAP requests
This file is part of the nss-pam-ldapd library.
Copyright (C) 2007, 2008, 2009 Arthur de Jong
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA
*/
/*
This file describes the API of the myldap module which takes the complexity
out of using the OpenLDAP library. Memory management, paging, reconnect
logic, idle timeout of connections, etc is taken care of by the module.
Use of this module is very straightforeward. You first have to create a
session (with myldap_create_session()), with this session you can start
searches (with myldap_search()), from a search you can get entries (with
myldap_get_entry()) from the LDAP database and from these entries you can
get attribute values (with myldap_get_values()).
*/
#ifndef _MYLDAP_H
#define _MYLDAP_H
/* for size_t */
#include <stdlib.h>
/* for LDAP_SCOPE_* */
#include <lber.h>
#include <ldap.h>
#include "compat/attrs.h"
#ifndef LDAP_SCOPE_DEFAULT
#define LDAP_SCOPE_DEFAULT LDAP_SCOPE_SUBTREE
#endif /* not LDAP_SCOPE_DEFAULT */
/* This a a generic session handle. */
typedef struct ldap_session MYLDAP_SESSION;
/* Note that this session handle may be used within one thread only. No
locking is performed to prevent concurrent modifications. Most LDAP
libraries also are not thread-safe in that a single connection may be
shared by multiple threads. It seems however that OpenLDAP at least does
not have any problems with an LDAP *ld per thread.
http://www.openldap.org/lists/openldap-software/200606/msg00252.html */
/* A result set as returned by myldap_search(). */
typedef struct myldap_search MYLDAP_SEARCH;
/* A single entry from the LDAP database as returned by myldap_get_entry(). */
typedef struct myldap_entry MYLDAP_ENTRY;
/* Create a new session, this does not yet connect to the LDAP server. The
connection to the server is made on-demand when a search is performed. This
uses the configuration to find the URLs to attempt connections to. */
MUST_USE MYLDAP_SESSION *myldap_create_session(void);
/* Set alternative credentials for the session and try to open a connection
with those credentials. Returns an LDAP status code. */
int myldap_set_credentials(MYLDAP_SESSION *session,const char *dn,
const char *password);
/* Closes all pending searches and deallocates any memory that is allocated
with these searches. This does not close the session. */
void myldap_session_cleanup(MYLDAP_SESSION *session);
/* Close the session and free all the resources allocated for the session.
After a call to this function the referenced handle is invalid. */
void myldap_session_close(MYLDAP_SESSION *session);
/* Do an LDAP search and return a reference to the results (returns NULL on
error). This function uses paging, and does reconnects to the configured
URLs transparently. */
MUST_USE MYLDAP_SEARCH *myldap_search(
MYLDAP_SESSION *session,
const char *base,int scope,const char *filter,const char **attrs);
/* Close the specified search. This frees all the memory that was allocated
for the search and its results. */
void myldap_search_close(MYLDAP_SEARCH *search);
/* Get an entry from the result set, going over all results (returns NULL if
no more entries are available). Note that any memory allocated to return
information about the previous entry (e.g. with myldap_get_values()) is
freed with this call. The search is autoamtically closed when no more
results are available. The function returns an LDAP status code in the
location pointed to by rcp if it is non-NULL. */
MUST_USE MYLDAP_ENTRY *myldap_get_entry(MYLDAP_SEARCH *search,int *rcp);
/* Get the DN from the entry. This function does not return NULL (on error
"unknown" is returned). */
MUST_USE const char *myldap_get_dn(MYLDAP_ENTRY *entry);
/* Just like myldap_get_dn() but copies the result into the buffer. */
char *myldap_cpy_dn(MYLDAP_ENTRY *entry,char *buf,size_t buflen);
/* Get the attribute values from a certain entry as a NULL terminated list.
May return NULL or an empty array. */
MUST_USE const char **myldap_get_values(MYLDAP_ENTRY *entry,const char *attr);
/* Checks to see if the entry has the specified object class. */
MUST_USE int myldap_has_objectclass(MYLDAP_ENTRY *entry,const char *objectclass);
/* Get the RDN's value: eg. if the DN was cn=lukeh, ou=People, dc=example,
dc=com getrdnvalue(entry,cn) would return lukeh. If the attribute was not
found in the DN or if some error occurs NULL is returned. This method may
be used to get the "most authorative" value for an attribute. */
MUST_USE const char *myldap_get_rdn_value(MYLDAP_ENTRY *entry,const char *attr);
/* Just like myldap_get_rdn_value() but use the supplied character sequence
and copies the result into the buffer.
Returns a pointer to the start of the string on success and NULL on
failure. */
MUST_USE const char *myldap_cpy_rdn_value(const char *dn,const char *attr,
char *buf,size_t buflen);
/* Escapes characters in a string for use in a search filter. */
MUST_USE int myldap_escape(const char *src,char *buffer,size_t buflen);
/* Set the debug level globally. Returns an LDAP status code. */
int myldap_set_debuglevel(int i);
/* Perform an EXOP password modification call. */
int myldap_passwd(
MYLDAP_SESSION *session,
const char *userdn,const char *oldpassword,const char *newpasswd);
#endif /* not _MYLDAP_H */
|