1 /* spmfilter - mail filtering framework 2 * Copyright (C) 2009-2012 Axel Steiner and SpaceNet AG 3 * 4 * This program is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 3 of the License, or (at your option) any later version. 8 * 9 * This program is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this program. If not, see <http://www.gnu.org/licenses/>. 16 */ 17 18 /*! 19 * @file smf_lookup.h 20 * @brief SQL and LDAP lookup functions. 21 * @details Spmfilter implements a small, fast, and easy to use database API 22 * with thread-safe connection pooling. The library can connect transparently 23 * to multiple database systems, has zero configuration and connections are 24 * specified via a standard URL scheme. 25 * 26 * @details Supported are variety of database systems: 27 * - MySQL 28 * - PostgreSQL 29 * - Oracle 30 * - SQLite 31 * - Berkeley DB 32 * - LDAP directories 33 * @details Spmfilter cares completely around connection management, load balancing 34 * and fallback connections. Failed connections will be also reconnected again 35 * automatically. 36 * @details Whether you are using a SQL database or a LDAP directory, all results are 37 * delivered as a #SMFList_T back. Each element is a #SMFDict_T dictionary, in 38 * which each key a SQL column or a LDAP attribute represents. 39 * @details The only exception here is Berkeley DB, as this does not require a query 40 * language and is based on key/values. 41 * @details In order to use database lookups, you have to set a appropriate backend in 42 * spmfilter.conf, this can be sql or ldap. If a valid backend is configured, 43 * spmfilter will automatically establish the connection. 44 */ 45 46 #ifndef _SMF_LOOKUP_H 47 #define _SMF_LOOKUP_H 48 49 #include "smf_settings.h" 50 #include "smf_session.h" 51 #include "smf_list.h" 52 53 /*! 54 * @fn char *smf_lookup_db4_query(char *database, char *key) 55 * @brief function to get value by key from berkeley hash table 56 * @param database path to database 57 * @param key key for which the value should be returned 58 * @returns newly allocated char pointer value string for given key, NULL if none found 59 */ 60 char *smf_lookup_db4_query(char *database, char *key); 61 62 /*! 63 * @fn int smf_lookup_db4_update(const char *database, const char *key, const char *value) 64 * @brief Updates a key in a berkeley database. The database is created if it does not exist. 65 * Afterwards the key is created or updated with the given value. 66 * 67 * @param database The path of the database to update (resp. create) 68 * @param key The key to update (resp. create) 69 * @param value The new value of the key 70 * @return On success 0 is returned or -1 in case of an error 71 */ 72 int smf_lookup_db4_update(const char *database, const char *key, const char *value); 73 74 /*! 75 * @fn int smf_lookup_sql_connect(SMFSettings_T *settings) 76 * @brief connect to sql server 77 * @param settings Pointer to SMFSettings_T 78 * @returns 0 on success or -1 in case of error 79 */ 80 int smf_lookup_sql_connect(SMFSettings_T *settings); 81 82 /*! 83 * @fn void smf_lookup_sql_disconnect(SMFSettings_T *settings) 84 * @brief Disconnect from sql server 85 * @param settings a SMFSettings_T object 86 */ 87 void smf_lookup_sql_disconnect(SMFSettings_T *settings); 88 89 /*! 90 * @fn SMFList_T *smf_lookup_sql_query(SMFSettings_T *settings, const char *q, ...) 91 * @brief Query SQL server with given query string 92 * @param settings Pointer to SMFSettings_T 93 * @param session Point to SMFSession_T 94 * @param q format string for sql query for sql query 95 * @returns SMFList_T or NULL 96 */ 97 SMFList_T *smf_lookup_sql_query(SMFSettings_T *settings, SMFSession_T *session, const char *q, ...); 98 99 /*! 100 * @fn int smf_lookup_ldap_connect(SMFSettings_T *settings) 101 * @brief Open a connection to ldap server 102 * @param settings Pointer to SMFSettings_T 103 * @returns 0 on success or -1 in case of error 104 */ 105 int smf_lookup_ldap_connect(SMFSettings_T *settings); 106 107 /*! 108 * @fn void smf_lookup_ldap_disconnect(SMFSettings_T *settings) 109 * @brief Disconnect from LDAP Server 110 * @param settings Pointer to SMFSettings_T 111 * @returns newly allocated char pointer value string for given key, NULL if none found 112 */ 113 void smf_lookup_ldap_disconnect(SMFSettings_T *settings); 114 115 /*! 116 * @fn SMFList_T *smf_lookup_ldap_query(SMFSettings_T *settings, const char *q, ...) 117 * @brief query LDAP Server with given query string 118 * @param settings Pointer to SMFSettings_T 119 * @param session Point to SMFSession_T 120 * @param q format string pointer for ldap query 121 * @param ... format string arguments 122 * @returns newly allocated SMFList_T 123 */ 124 SMFList_T *smf_lookup_ldap_query(SMFSettings_T *settings, SMFSession_T *session, const char *q, ...); 125 126 127 #endif /* _SMF_LOOKUP_H */ 128 129