diff --git a/include/maxscale/filter.h b/include/maxscale/filter.h deleted file mode 100644 index cc30093eb..000000000 --- a/include/maxscale/filter.h +++ /dev/null @@ -1,264 +0,0 @@ -/* - * Copyright (c) 2018 MariaDB Corporation Ab - * - * Use of this software is governed by the Business Source License included - * in the LICENSE.TXT file and at www.mariadb.com/bsl11. - * - * Change Date: 2022-01-01 - * - * On the date above, in accordance with the Business Source License, use - * of this software will be governed by version 2 or later of the General - * Public License. - */ -#pragma once - -/** - * @file include/maxscale/filter.h - The public filter interface - */ - -#include -#include -#include -#include -#include -#include -#include -#include - -/** - * MXS_FILTER is an opaque type representing a particular filter instance. - * - * MaxScale itself does not do anything with it, except for receiving it - * from the @c createInstance function of a filter module and subsequently - * passing it back to the API functions of the filter. - */ -typedef struct mxs_filter -{ -} MXS_FILTER; - -/** - * MXS_FILTER_SESSION is an opaque type representing the session related - * data of a particular filter instance. - * - * MaxScale itself does not do anything with it, except for receiving it - * from the @c newSession function of a filter module and subsequently - * passing it back to the API functions of the filter. - */ -typedef struct mxs_filter_session -{ -} MXS_FILTER_SESSION; - -/** - * @verbatim - * The "module object" structure for a filter module. All entry points - * marked with `(optional)` are optional entry points which can be set to NULL - * if no implementation is required. - * - * The entry points are: - * createInstance Called by the service to create a new instance of the filter - * newSession Called to create a new user session within the filter - * closeSession Called when a session is closed - * freeSession Called when a session is freed - * setDownstream Sets the downstream component of the filter pipline - * setUpstream Sets the upstream component of the filter pipline - * routeQuery Called on each query that requires routing - * clientReply Called for each reply packet (optional) - * diagnostics Called for diagnostic output - * getCapabilities Called to obtain the capabilities of the filter (optional) - * destroyInstance Called for destroying a filter instance (optional) - * - * @endverbatim - * - * @see load_module - */ -typedef struct mxs_filter_object -{ - - /** - * @brief Create a new instance of the filter - * - * This function is called when a new filter instance is created. The return - * value of this function will be passed as the first parameter to the - * other API functions. - * - * @param name Name of the filter instance - * @param params Filter parameters - * - * @return New filter instance on NULL on error - */ - MXS_FILTER*(*createInstance)(const char* name, MXS_CONFIG_PARAMETER* params); - - /** - * Called to create a new user session within the filter - * - * This function is called when a new filter session is created for a client. - * The return value of this function will be passed as the second parameter - * to the @c routeQuery, @c clientReply, @c closeSession, @c freeSession, - * @c setDownstream and @c setUpstream functions. - * - * @param instance Filter instance - * @param session Client MXS_SESSION object - * - * @return New filter session or NULL on error - */ - MXS_FILTER_SESSION*(*newSession)(MXS_FILTER * instance, MXS_SESSION* session); - - /** - * @brief Called when a session is closed - * - * The filter should close all objects but not free any memory. - * - * @param instance Filter instance - * @param fsession Filter session - */ - void (* closeSession)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession); - - /** - * @brief Called when a session is freed - * - * The session should free all allocated memory in this function. - * - * @param instance Filter instance - * @param fsession Filter session - */ - void (* freeSession)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession); - - /** - * @brief Sets the downstream component of the filter pipeline - * - * @param instance Filter instance - * @param fsession Filter session - */ - void (* setDownstream)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession, MXS_DOWNSTREAM* downstream); - - /** - * @brief Sets the upstream component of the filter pipeline - * - * @param instance Filter instance - * @param fsession Filter session - */ - void (* setUpstream)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession, MXS_UPSTREAM* downstream); - - /** - * @brief Called on each query that requires routing - * - * TODO: Document how routeQuery should be used - * - * @param instance Filter instance - * @param fsession Filter session - * @param queue Request from the client - * - * @return If successful, the function returns 1. If an error occurs - * and the session should be closed, the function returns 0. - */ - int32_t (* routeQuery)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession, GWBUF* queue); - - /** - * @brief Called for each reply packet - * - * TODO: Document how clientReply should be used - * - * @param instance Filter instance - * @param fsession Filter session - * @param queue Response from the server - * - * @return If successful, the function returns 1. If an error occurs - * and the session should be closed, the function returns 0. - */ - int32_t (* clientReply)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession, GWBUF* queue); - - /** - * @brief Called for diagnostic output - * - * @param instance Filter instance - * @param fsession Filter session, NULL if general information about the filter is queried - * @param dcb DCB where the diagnostic information should be written - */ - void (* diagnostics)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession, DCB* dcb); - - /** - * @brief Called for diagnostic output - * - * @param instance Filter instance - * @param fsession Filter session, NULL if general information about the filter is queried - * - * @return JSON formatted information about the filter - * - * @see jansson.h - */ - json_t* (*diagnostics_json)(const MXS_FILTER * instance, const MXS_FILTER_SESSION* fsession); - - /** - * @brief Called to obtain the capabilities of the filter - * - * @return Zero or more bitwise-or'd values from the mxs_routing_capability_t enum - * - * @see routing.h - */ - uint64_t (* getCapabilities)(MXS_FILTER* instance); - - /** - * @brief Called for destroying a filter instance - * - * @param instance Filter instance - */ - void (* destroyInstance)(MXS_FILTER* instance); -} MXS_FILTER_OBJECT; - -/** - * The filter API version. If the MXS_FILTER_OBJECT structure or the filter API - * is changed these values must be updated in line with the rules in the - * file modinfo.h. - */ -#define MXS_FILTER_VERSION {4, 0, 0} - -/** - * MXS_FILTER_DEF represents a filter definition from the configuration file. - * Its exact definition is private to MaxScale. - */ -struct mxs_filter_def; - -typedef struct mxs_filter_def -{ -} MXS_FILTER_DEF; - -/** - * Get the name of a filter definition. This corresponds to - * to a filter section in the configuration file. - * - * @param filter_def A filter definition. - * - * @return The filter name. - */ -const char* filter_def_get_name(const MXS_FILTER_DEF* filter_def); - -/** - * Get module name of a filter definition. - * - * @param filter_def A filter definition. - * - * @return The module name. - */ -const char* filter_def_get_module_name(const MXS_FILTER_DEF* filter_def); - -/** - * Get the filter instance of a particular filter definition. - * - * @return A filter instance. - */ -MXS_FILTER* filter_def_get_instance(const MXS_FILTER_DEF* filter_def); - -/** - * Specifies capabilities specific for filters. Common capabilities - * are defined by @c routing_capability_t. - * - * @see enum routing_capability - * - * @note The values of the capabilities here *must* be between 0x80000000 - * and 0x01000000, that is, bits 24 to 31. - */ - -typedef enum filter_capability -{ - FCAP_TYPE_NONE = 0x0 // TODO: remove once filter capabilities are defined -} filter_capability_t; diff --git a/include/maxscale/filter.hh b/include/maxscale/filter.hh index 0b6c3c92e..3858fd63e 100644 --- a/include/maxscale/filter.hh +++ b/include/maxscale/filter.hh @@ -12,8 +12,256 @@ */ #pragma once +/** + * @file include/maxscale/filter.hh - The public filter interface + */ + #include -#include +#include +#include +#include +#include +#include +#include +#include + +/** + * MXS_FILTER is an opaque type representing a particular filter instance. + * + * MaxScale itself does not do anything with it, except for receiving it + * from the @c createInstance function of a filter module and subsequently + * passing it back to the API functions of the filter. + */ +typedef struct mxs_filter +{ +} MXS_FILTER; + +/** + * MXS_FILTER_SESSION is an opaque type representing the session related + * data of a particular filter instance. + * + * MaxScale itself does not do anything with it, except for receiving it + * from the @c newSession function of a filter module and subsequently + * passing it back to the API functions of the filter. + */ +typedef struct mxs_filter_session +{ +} MXS_FILTER_SESSION; + +/** + * @verbatim + * The "module object" structure for a filter module. All entry points + * marked with `(optional)` are optional entry points which can be set to NULL + * if no implementation is required. + * + * The entry points are: + * createInstance Called by the service to create a new instance of the filter + * newSession Called to create a new user session within the filter + * closeSession Called when a session is closed + * freeSession Called when a session is freed + * setDownstream Sets the downstream component of the filter pipline + * setUpstream Sets the upstream component of the filter pipline + * routeQuery Called on each query that requires routing + * clientReply Called for each reply packet (optional) + * diagnostics Called for diagnostic output + * getCapabilities Called to obtain the capabilities of the filter (optional) + * destroyInstance Called for destroying a filter instance (optional) + * + * @endverbatim + * + * @see load_module + */ +typedef struct mxs_filter_object +{ + + /** + * @brief Create a new instance of the filter + * + * This function is called when a new filter instance is created. The return + * value of this function will be passed as the first parameter to the + * other API functions. + * + * @param name Name of the filter instance + * @param params Filter parameters + * + * @return New filter instance on NULL on error + */ + MXS_FILTER*(*createInstance)(const char* name, MXS_CONFIG_PARAMETER* params); + + /** + * Called to create a new user session within the filter + * + * This function is called when a new filter session is created for a client. + * The return value of this function will be passed as the second parameter + * to the @c routeQuery, @c clientReply, @c closeSession, @c freeSession, + * @c setDownstream and @c setUpstream functions. + * + * @param instance Filter instance + * @param session Client MXS_SESSION object + * + * @return New filter session or NULL on error + */ + MXS_FILTER_SESSION*(*newSession)(MXS_FILTER * instance, MXS_SESSION* session); + + /** + * @brief Called when a session is closed + * + * The filter should close all objects but not free any memory. + * + * @param instance Filter instance + * @param fsession Filter session + */ + void (* closeSession)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession); + + /** + * @brief Called when a session is freed + * + * The session should free all allocated memory in this function. + * + * @param instance Filter instance + * @param fsession Filter session + */ + void (* freeSession)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession); + + /** + * @brief Sets the downstream component of the filter pipeline + * + * @param instance Filter instance + * @param fsession Filter session + */ + void (* setDownstream)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession, MXS_DOWNSTREAM* downstream); + + /** + * @brief Sets the upstream component of the filter pipeline + * + * @param instance Filter instance + * @param fsession Filter session + */ + void (* setUpstream)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession, MXS_UPSTREAM* downstream); + + /** + * @brief Called on each query that requires routing + * + * TODO: Document how routeQuery should be used + * + * @param instance Filter instance + * @param fsession Filter session + * @param queue Request from the client + * + * @return If successful, the function returns 1. If an error occurs + * and the session should be closed, the function returns 0. + */ + int32_t (* routeQuery)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession, GWBUF* queue); + + /** + * @brief Called for each reply packet + * + * TODO: Document how clientReply should be used + * + * @param instance Filter instance + * @param fsession Filter session + * @param queue Response from the server + * + * @return If successful, the function returns 1. If an error occurs + * and the session should be closed, the function returns 0. + */ + int32_t (* clientReply)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession, GWBUF* queue); + + /** + * @brief Called for diagnostic output + * + * @param instance Filter instance + * @param fsession Filter session, NULL if general information about the filter is queried + * @param dcb DCB where the diagnostic information should be written + */ + void (* diagnostics)(MXS_FILTER* instance, MXS_FILTER_SESSION* fsession, DCB* dcb); + + /** + * @brief Called for diagnostic output + * + * @param instance Filter instance + * @param fsession Filter session, NULL if general information about the filter is queried + * + * @return JSON formatted information about the filter + * + * @see jansson.h + */ + json_t* (*diagnostics_json)(const MXS_FILTER * instance, const MXS_FILTER_SESSION* fsession); + + /** + * @brief Called to obtain the capabilities of the filter + * + * @return Zero or more bitwise-or'd values from the mxs_routing_capability_t enum + * + * @see routing.h + */ + uint64_t (* getCapabilities)(MXS_FILTER* instance); + + /** + * @brief Called for destroying a filter instance + * + * @param instance Filter instance + */ + void (* destroyInstance)(MXS_FILTER* instance); +} MXS_FILTER_OBJECT; + +/** + * The filter API version. If the MXS_FILTER_OBJECT structure or the filter API + * is changed these values must be updated in line with the rules in the + * file modinfo.h. + */ +#define MXS_FILTER_VERSION {4, 0, 0} + +/** + * MXS_FILTER_DEF represents a filter definition from the configuration file. + * Its exact definition is private to MaxScale. + */ +struct mxs_filter_def; + +typedef struct mxs_filter_def +{ +} MXS_FILTER_DEF; + +/** + * Get the name of a filter definition. This corresponds to + * to a filter section in the configuration file. + * + * @param filter_def A filter definition. + * + * @return The filter name. + */ +const char* filter_def_get_name(const MXS_FILTER_DEF* filter_def); + +/** + * Get module name of a filter definition. + * + * @param filter_def A filter definition. + * + * @return The module name. + */ +const char* filter_def_get_module_name(const MXS_FILTER_DEF* filter_def); + +/** + * Get the filter instance of a particular filter definition. + * + * @return A filter instance. + */ +MXS_FILTER* filter_def_get_instance(const MXS_FILTER_DEF* filter_def); + +/** + * Specifies capabilities specific for filters. Common capabilities + * are defined by @c routing_capability_t. + * + * @see enum routing_capability + * + * @note The values of the capabilities here *must* be between 0x80000000 + * and 0x01000000, that is, bits 24 to 31. + */ + +typedef enum filter_capability +{ + FCAP_TYPE_NONE = 0x0 // TODO: remove once filter capabilities are defined +} filter_capability_t; namespace maxscale { diff --git a/include/maxscale/service.hh b/include/maxscale/service.hh index c127fdee3..b5d81ba86 100644 --- a/include/maxscale/service.hh +++ b/include/maxscale/service.hh @@ -26,7 +26,7 @@ #include #include #include -#include +#include #include struct server; diff --git a/server/core/internal/filter.hh b/server/core/internal/filter.hh index 339df3622..043b2f7d5 100644 --- a/server/core/internal/filter.hh +++ b/server/core/internal/filter.hh @@ -16,7 +16,7 @@ * @file core/maxscale/filter.h - The private filter interface */ -#include +#include #include #include diff --git a/server/core/load_utils.cc b/server/core/load_utils.cc index 3838c4be6..4d9d136bd 100644 --- a/server/core/load_utils.cc +++ b/server/core/load_utils.cc @@ -33,7 +33,7 @@ #include #include #include -#include +#include #include #include #include diff --git a/server/modules/filter/hintfilter/hintfilter.cc b/server/modules/filter/hintfilter/hintfilter.cc index 19cc1624c..4c43548b5 100644 --- a/server/modules/filter/hintfilter/hintfilter.cc +++ b/server/modules/filter/hintfilter/hintfilter.cc @@ -14,7 +14,7 @@ #define MXS_MODULE_NAME "hintfilter" #include -#include +#include #include #include #include diff --git a/server/modules/filter/hintfilter/hintparser.cc b/server/modules/filter/hintfilter/hintparser.cc index 83ab99c8a..d56e699d0 100644 --- a/server/modules/filter/hintfilter/hintparser.cc +++ b/server/modules/filter/hintfilter/hintparser.cc @@ -17,7 +17,7 @@ #include #include #include -#include +#include #include #include #include "mysqlhint.h" diff --git a/server/modules/filter/insertstream/insertstream.cc b/server/modules/filter/insertstream/insertstream.cc index 63902fe31..4b435e1d9 100644 --- a/server/modules/filter/insertstream/insertstream.cc +++ b/server/modules/filter/insertstream/insertstream.cc @@ -18,7 +18,7 @@ #include #include #include -#include +#include #include #include #include diff --git a/server/modules/filter/luafilter/luafilter.cc b/server/modules/filter/luafilter/luafilter.cc index 6be2520de..dd9031405 100644 --- a/server/modules/filter/luafilter/luafilter.cc +++ b/server/modules/filter/luafilter/luafilter.cc @@ -52,7 +52,7 @@ extern "C" #include #include -#include +#include #include #include #include diff --git a/server/modules/filter/maxrows/maxrows.cc b/server/modules/filter/maxrows/maxrows.cc index 8c62275b2..31a32119c 100644 --- a/server/modules/filter/maxrows/maxrows.cc +++ b/server/modules/filter/maxrows/maxrows.cc @@ -25,7 +25,7 @@ #include #include #include -#include +#include #include #include #include diff --git a/server/modules/filter/mqfilter/mqfilter.cc b/server/modules/filter/mqfilter/mqfilter.cc index d32d2bb8e..a8c2147de 100644 --- a/server/modules/filter/mqfilter/mqfilter.cc +++ b/server/modules/filter/mqfilter/mqfilter.cc @@ -61,7 +61,7 @@ #include #include -#include +#include #include #include #include diff --git a/server/modules/filter/qlafilter/qlafilter.cc b/server/modules/filter/qlafilter/qlafilter.cc index 0ca586e29..feb7f91ec 100644 --- a/server/modules/filter/qlafilter/qlafilter.cc +++ b/server/modules/filter/qlafilter/qlafilter.cc @@ -39,7 +39,7 @@ #include #include -#include +#include #include #include #include diff --git a/server/modules/filter/regexfilter/regexfilter.cc b/server/modules/filter/regexfilter/regexfilter.cc index d04768d2c..407430d67 100644 --- a/server/modules/filter/regexfilter/regexfilter.cc +++ b/server/modules/filter/regexfilter/regexfilter.cc @@ -19,7 +19,7 @@ #include #include #include -#include +#include #include #include #include diff --git a/server/modules/filter/test/maxscale/mock/client.hh b/server/modules/filter/test/maxscale/mock/client.hh index 3d9170f52..887562062 100644 --- a/server/modules/filter/test/maxscale/mock/client.hh +++ b/server/modules/filter/test/maxscale/mock/client.hh @@ -15,7 +15,7 @@ #include #include #include -#include +#include #include "../filtermodule.hh" #include "dcb.hh" diff --git a/server/modules/filter/topfilter/topfilter.cc b/server/modules/filter/topfilter/topfilter.cc index feed2779d..e9c70c1fc 100644 --- a/server/modules/filter/topfilter/topfilter.cc +++ b/server/modules/filter/topfilter/topfilter.cc @@ -36,7 +36,7 @@ #include #include -#include +#include #include #include #include diff --git a/server/modules/filter/tpmfilter/tpmfilter.cc b/server/modules/filter/tpmfilter/tpmfilter.cc index 1a99be49c..8c0c0b70f 100644 --- a/server/modules/filter/tpmfilter/tpmfilter.cc +++ b/server/modules/filter/tpmfilter/tpmfilter.cc @@ -56,7 +56,7 @@ #include #include -#include +#include #include #include #include diff --git a/server/modules/routing/debugcli/debugcmd.cc b/server/modules/routing/debugcli/debugcmd.cc index 8ccf95b54..f3469435b 100644 --- a/server/modules/routing/debugcli/debugcmd.cc +++ b/server/modules/routing/debugcli/debugcmd.cc @@ -41,7 +41,7 @@ #include #include #include -#include +#include #include #include #include