Drizzled Public API Documentation

plugin.h

00001 /* -*- mode: c++; c-basic-offset: 2; indent-tabs-mode: nil; -*-
00002  *  vim:expandtab:shiftwidth=2:tabstop=2:smarttab:
00003  *
00004  *  Copyright (C) 2008 Sun Microsystems, Inc.
00005  *
00006  *  This program is free software; you can redistribute it and/or modify
00007  *  it under the terms of the GNU General Public License as published by
00008  *  the Free Software Foundation; version 2 of the License.
00009  *
00010  *  This program is distributed in the hope that it will be useful,
00011  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00013  *  GNU General Public License for more details.
00014  *
00015  *  You should have received a copy of the GNU General Public License
00016  *  along with this program; if not, write to the Free Software
00017  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00018  */
00019 
00020 #pragma once
00021 
00022 #include <boost/program_options.hpp>
00023 #include <boost/filesystem.hpp>
00024 
00025 #include <drizzled/module/manifest.h>
00026 #include <drizzled/module/module.h>
00027 #include <drizzled/plugin/version.h>
00028 #include <drizzled/module/context.h>
00029 #include <drizzled/definitions.h>
00030 
00031 #include <drizzled/lex_string.h>
00032 #include <drizzled/sys_var.h>
00033 
00034 #include <drizzled/visibility.h>
00035 
00036 namespace drizzled {
00037 
00038 class Session;
00039 class Item;
00040 struct charset_info_st;
00041 
00042 /*************************************************************************
00043   Plugin API. Common for all plugin types.
00044 */
00045 
00046 
00047 class sys_var;
00048 struct option;
00049 
00050 extern boost::filesystem::path plugin_dir;
00051 
00052 namespace plugin { class StorageEngine; }
00053 
00054 /*
00055   Macros for beginning and ending plugin declarations. Between
00056   DRIZZLE_DECLARE_PLUGIN and DRIZZLE_DECLARE_PLUGIN_END there should
00057   be a module::Manifest for each plugin to be declared.
00058 */
00059 
00060 
00061 #define PANDORA_CPP_NAME(x) _drizzled_ ## x ## _plugin_
00062 #define PANDORA_PLUGIN_NAME(x) PANDORA_CPP_NAME(x)
00063 #define DRIZZLE_DECLARE_PLUGIN \
00064   DRIZZLED_API ::drizzled::module::Manifest PANDORA_PLUGIN_NAME(PANDORA_MODULE_NAME)= 
00065 
00066 
00067 #define DRIZZLE_DECLARE_PLUGIN_END
00068 #define DRIZZLE_PLUGIN(init,system,options) \
00069   DRIZZLE_DECLARE_PLUGIN \
00070   { \
00071     DRIZZLE_VERSION_ID, \
00072     STRINGIFY_ARG(PANDORA_MODULE_NAME), \
00073     STRINGIFY_ARG(PANDORA_MODULE_VERSION), \
00074     STRINGIFY_ARG(PANDORA_MODULE_AUTHOR), \
00075     STRINGIFY_ARG(PANDORA_MODULE_TITLE), \
00076     PANDORA_MODULE_LICENSE, \
00077     init, \
00078     STRINGIFY_ARG(PANDORA_MODULE_DEPENDENCIES), \
00079     options \
00080   } 
00081 
00082 
00083 /*
00084   declarations for server variables and command line options
00085 */
00086 
00087 
00088 #define PLUGIN_VAR_BOOL         0x0001
00089 #define PLUGIN_VAR_INT          0x0002
00090 #define PLUGIN_VAR_LONG         0x0003
00091 #define PLUGIN_VAR_LONGLONG     0x0004
00092 #define PLUGIN_VAR_STR          0x0005
00093 #define PLUGIN_VAR_UNSIGNED     0x0080
00094 #define PLUGIN_VAR_SessionLOCAL     0x0100 /* Variable is per-connection */
00095 #define PLUGIN_VAR_READONLY     0x0200 /* Server variable is read only */
00096 #define PLUGIN_VAR_NOSYSVAR     0x0400 /* Not a server variable */
00097 #define PLUGIN_VAR_NOCMDOPT     0x0800 /* Not a command line option */
00098 #define PLUGIN_VAR_NOCMDARG     0x1000 /* No argument for cmd line */
00099 #define PLUGIN_VAR_RQCMDARG     0x0000 /* Argument required for cmd line */
00100 #define PLUGIN_VAR_OPCMDARG     0x2000 /* Argument optional for cmd line */
00101 #define PLUGIN_VAR_MEMALLOC     0x8000 /* String needs memory allocated */
00102 
00103 struct drizzle_sys_var;
00104 struct drizzle_value;
00105 
00106 /*
00107   SYNOPSIS
00108     (*var_check_func)()
00109       session               thread handle
00110       var               dynamic variable being altered
00111       save              pointer to temporary storage
00112       value             user provided value
00113   RETURN
00114     0   user provided value is OK and the update func may be called.
00115     any other value indicates error.
00116 
00117   This function should parse the user provided value and store in the
00118   provided temporary storage any data as required by the update func.
00119   There is sufficient space in the temporary storage to store a double.
00120   Note that the update func may not be called if any other error occurs
00121   so any memory allocated should be thread-local so that it may be freed
00122   automatically at the end of the statement.
00123 */
00124 
00125 typedef int (*var_check_func)(Session *session,
00126                                     drizzle_sys_var *var,
00127                                     void *save, drizzle_value *value);
00128 
00129 /*
00130   SYNOPSIS
00131     (*var_update_func)()
00132       session               thread handle
00133       var               dynamic variable being altered
00134       var_ptr           pointer to dynamic variable
00135       save              pointer to temporary storage
00136    RETURN
00137      NONE
00138 
00139    This function should use the validated value stored in the temporary store
00140    and persist it in the provided pointer to the dynamic variable.
00141    For example, strings may require memory to be allocated.
00142 */
00143 typedef void (*var_update_func)(Session *session,
00144                                       drizzle_sys_var *var,
00145                                       void *var_ptr, const void *save);
00146 
00147 
00148 
00149 /*
00150   skeleton of a plugin variable - portion of structure common to all.
00151 */
00152 struct drizzle_sys_var
00153 {
00154 };
00155 
00156 void plugin_opt_set_limits(option *options, const drizzle_sys_var *opt);
00157 
00158 struct drizzle_value
00159 {
00160   int (*value_type)(drizzle_value *);
00161   const char *(*val_str)(drizzle_value *, char *buffer, int *length);
00162   int (*val_real)(drizzle_value *, double *realbuf);
00163   int (*val_int)(drizzle_value *, int64_t *intbuf);
00164 };
00165 
00166 
00167 /*************************************************************************
00168   Miscellaneous functions for plugin implementors
00169 */
00170 
00171 extern bool plugin_init(module::Registry &registry,
00172                         boost::program_options::options_description &long_options);
00173 extern bool plugin_finalize(module::Registry &registry);
00174 extern void plugin_startup_window(module::Registry &registry, drizzled::Session &session);
00175 extern void my_print_help_inc_plugins(option *options);
00176 extern bool plugin_is_ready(const LEX_STRING *name, int type);
00177 extern void plugin_sessionvar_init(Session *session);
00178 extern void plugin_sessionvar_cleanup(Session *session);
00179 
00180 int session_in_lock_tables(const Session *session);
00181 DRIZZLED_API int64_t session_test_options(const Session *session, int64_t test_options);
00182 void compose_plugin_add(std::vector<std::string> options);
00183 void compose_plugin_remove(std::vector<std::string> options);
00184 void notify_plugin_load(std::string in_plugin_load);
00185 
00186 
00199 DRIZZLED_API int tmpfile(const char *prefix);
00200 
00201 } /* namespace drizzled */
00202 
00203