/* * 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_BEGIN_DECLS /** * 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; MXS_END_DECLS