include/v2l_conn.h

   1 /*
   2  *  This program is free software; you can redistribute it and/or modify
   3  *  it under the terms of the GNU General Public License as published by
   4  *  the Free Software Foundation; either version 2 of the License, or
   5  *  (at your option) any later version.
   6  *
   7  *  This program is distributed in the hope that it will be useful,
   8  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
   9  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10  *  GNU General Public License for more details.
  11  *
  12  *  You should have received a copy of the GNU General Public License
  13  *  along with this program; if not, write to the Free Software
  14  *  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  15  */
  16
  17 /*! \file v2l_conn.h
  18     \brief Handling the LDAP directory. Low-level tier.
  19 */
  20
  21 #ifndef __V2L_CONN_H
  22 #define __V2L_CONN_H
  23
  24 #include <ldap.h>
  25 #include <time.h>
  26
  27 #include <v2l_config.h>
  28
  29 /*! \brief Simple Linked List of connections to LDAP directory */
  30 typedef struct v2l_LdapConn
  31 {
  32   pool poolref;
  33   LDAP *ld;              /*!< LDAP descriptor */
  34   time_t creation_time;  /*!< timestamp */
  35   char *binddn;          /*!< complete dn */
  36   char *entry;           /*!< short dn */
  37   char *user;            /*!< username */
  38   struct v2l_LdapConn *next;
  39 } v2l_LdapConn;
  40
  41 /*! \brief Request (SLL) for LDAP directory */
  42 typedef struct v2l_LdapRequest
  43 {
  44   LDAPMod *attr;
  45   struct v2l_LdapRequest *next;
  46 } v2l_LdapRequest;
  47
  48 /*! \brief LDAP environment.
  49     Control struct for perform operations on the LDAP directory and retrieve
  50     results.
  51 */
  52 typedef struct v2l_LdapEvt
  53 {
  54   LDAP *ld;   /*!< LDAP descriptor */
  55   int msgid;  /*!< LDAP message id (see OpenLDAP API docs) */
  56   int rc;     /*!< LDAP error code */
  57   LDAPMessage *result; /*!< LDAP result (see OpenLDAP API docs) */
  58 } v2l_LdapEvt;
  59
  60 /*! \brief Match function type
  61     Generic attribute matching routine.
  62     \param attr The attribute.
  63     \param[out] shrdata Generic deferenced pointer. Shared data with a 'value
  64     function'
  65     \sa v2l_AttrValueFunction
  66     \sa v2l_ldap_for_all_attrs
  67     \return true if matching, otherwise false.
  68 */
  69 typedef int (*v2l_AttrMatchFunction) (const char *attr, void **shrdata);
  70
  71 /*! \brief Values read function type
  72     Generic values handling routine.
  73     \param attr The attribute.
  74     \param vals Values of attribute.
  75     \param pointer Generic multipurpose pointer.
  76     \param shrdata Shared data with 'match function'
  77     \sa v2l_MatchValueFunction
  78     \sa v2l_ldap_for_all_attrs
  79 */
  80 typedef void (*v2l_AttrValueFunction) (const char *attr, const char **vals,
  81   void *pointer, void *shrdata);
  82
  83 /*! \brief Gets a (ephemeral) connection by name. Creates one if doesn't exist.
  84     \warning The name defined by V2L_ADMIN is reserved for master conn.
  85     \pre self is valid, user is not null and exists.
  86     \post ephermeral connection for user is open.
  87     \param self Module config.
  88     \param user the username
  89     \sa V2L_ADMIN
  90     \sa v2l_get_master_conn
  91     \return the connection if no error, otherwise NULL.
  92 */
  93 extern v2l_LdapConn *v2l_get_conn (v2l_Config *self, const char *user);
  94
  95 /*! \brief Gets a connection master connection. Creates one if doesn't exist.
  96     \pre self is valid
  97     \post master connection is open.
  98     \param self Module config.
  99     \return the connection if no error, otherwise NULL.
 100 */
 101 extern v2l_LdapConn *v2l_get_master_conn (v2l_Config *self);
 102
 103 /*! \brief Frees and closes all connections (ephemeral or not)
 104     If connections doesn't exist does nothing.
 105     \post self->master_conn closed. Connections list empty.
 106 */
 107 extern void v2l_free_allconn ();
 108
 109 /*! \brief Retrieves an user entry from the LDAP directory
 110     \note Allocated memory must be freed by the caller.
 111     \param self Module config
 112     \param curr_conn user connection.
 113     \return evt_res LDAP descriptor, control code and result. NULL if error.
 114 */
 115 extern v2l_LdapEvt *v2l_ldap_get_entry (v2l_Config *self,
 116   v2l_LdapConn *curr_conn);
 117
 118 /*! \brief Executes a list of changes on the LDAP directory.
 119     \pre req is not NULL
 120     \param self Module config
 121     \param curr_conn The user connection.
 122     \param req list of changes.
 123     \return 1 if no error, otherwise 0
 124 */
 125 extern int v2l_request_record (v2l_Config *self, v2l_LdapConn *curr_conn,
 126   v2l_LdapRequest *req);
 127
 128 /*! \brief Adds a new request to the list
 129     \param req The list of requests.
 130     \param attr attribute name.
 131     \param str attribute value.
 132     \return The list of requests + the last added. The list of request if error.
 133 */
 134 extern v2l_LdapRequest *v2l_add_attr_str (v2l_LdapRequest *req,
 135   const char *attr, const char *str);
 136
 137 /*! \brief Applies a function to all LDAP object attributes.
 138     \pre evt_res should be a valid entry (ie. result of a search in directory)
 139     \param value_func Walker function.
 140     \param match_func Match function. If returns true we'll call to value_func
 141     \param pointer Generic multipurpose pointer. It will be passed to value_func
 142     \param evt_res LDAP descriptor, control code and result.
 143 */
 144 extern void v2l_ldap_for_all_attrs (v2l_AttrValueFunction value_func,
 145   v2l_AttrMatchFunction match_func, void *pointer, v2l_LdapEvt *evt_res);
 146 #endif