hcq/MaxScale
hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MXS-2205 Combine maxscale/filter.h with maxscale/filter.hh

Browse Source
This commit is contained in:
Esa Korhonen 2018-12-03 13:25:52 +02:00
parent 8a570eb6a1
commit 5f7211aac5
17 changed files with 264 additions and 280 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

264
include/maxscale/filter.h
View File

@ -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 <maxscale/cdefs.h>
#include <stdint.h>
#include <maxbase/jansson.h>
#include <maxscale/buffer.h>
#include <maxscale/config.hh>
#include <maxscale/dcb.h>
#include <maxscale/routing.h>
#include <maxscale/session.h>
/**
* 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;

250
include/maxscale/filter.hh
View File

@ -12,8 +12,256 @@
*/
#pragma once
/**
* @file include/maxscale/filter.hh - The public filter interface
*/
#include <maxscale/ccdefs.hh>
#include <maxscale/filter.h>
#include <stdint.h>
#include <maxbase/jansson.h>
#include <maxscale/buffer.hh>
#include <maxscale/config.hh>
#include <maxscale/dcb.h>
#include <maxscale/routing.h>
#include <maxscale/session.hh>
/**
* 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
{

2
include/maxscale/service.hh
View File

@ -26,7 +26,7 @@
#include <maxscale/protocol.h>
#include <maxscale/dcb.h>
#include <maxscale/listener.hh>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/server.h>
struct server;

2
server/core/internal/filter.hh
View File

@ -16,7 +16,7 @@
* @file core/maxscale/filter.h - The private filter interface
*/
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <memory>
#include <mutex>

2
server/core/load_utils.cc
View File

@ -33,7 +33,7 @@
#include <maxscale/modulecmd.hh>
#include <maxscale/protocol.h>
#include <maxscale/router.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/authenticator.h>
#include <maxscale/monitor.hh>
#include <maxscale/query_classifier.h>

2
server/modules/filter/hintfilter/hintfilter.cc
View File

@ -14,7 +14,7 @@
#define MXS_MODULE_NAME "hintfilter"
#include <stdio.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/alloc.h>
#include <maxscale/modinfo.h>
#include <maxscale/modutil.hh>

2
server/modules/filter/hintfilter/hintparser.cc
View File

@ -17,7 +17,7 @@
#include <ctype.h>
#include <string.h>
#include <maxscale/log.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/modinfo.h>
#include <maxscale/modutil.hh>
#include "mysqlhint.h"

2
server/modules/filter/insertstream/insertstream.cc
View File

@ -18,7 +18,7 @@
#include <strings.h>
#include <maxscale/alloc.h>
#include <maxscale/buffer.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/log.h>
#include <maxscale/modinfo.h>
#include <maxscale/modutil.hh>

2
server/modules/filter/luafilter/luafilter.cc
View File

@ -52,7 +52,7 @@ extern "C"
#include <mutex>
#include <maxscale/alloc.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/log.h>
#include <maxscale/modutil.hh>
#include <maxscale/query_classifier.h>

2
server/modules/filter/maxrows/maxrows.cc
View File

@ -25,7 +25,7 @@
#include <maxbase/assert.h>
#include <maxscale/alloc.h>
#include <maxscale/buffer.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/log.h>
#include <maxscale/modinfo.h>
#include <maxscale/modutil.hh>

2
server/modules/filter/mqfilter/mqfilter.cc
View File

@ -61,7 +61,7 @@
#include <stdio.h>
#include <fcntl.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/modinfo.h>
#include <maxscale/modutil.hh>
#include <string.h>

2
server/modules/filter/qlafilter/qlafilter.cc
View File

@ -39,7 +39,7 @@
#include <maxscale/alloc.h>
#include <maxbase/atomic.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/log.h>
#include <maxscale/modinfo.h>
#include <maxscale/modutil.hh>

2
server/modules/filter/regexfilter/regexfilter.cc
View File

@ -19,7 +19,7 @@
#include <maxscale/alloc.h>
#include <maxbase/atomic.h>
#include <maxscale/config.hh>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/log.h>
#include <maxscale/modinfo.h>
#include <maxscale/modutil.hh>

2
server/modules/filter/test/maxscale/mock/client.hh
View File

@ -15,7 +15,7 @@
#include <maxscale/ccdefs.hh>
#include <memory>
#include <string>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include "../filtermodule.hh"
#include "dcb.hh"

2
server/modules/filter/topfilter/topfilter.cc
View File

@ -36,7 +36,7 @@
#include <stdio.h>
#include <fcntl.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/modinfo.h>
#include <maxscale/modutil.hh>
#include <maxscale/log.h>

2
server/modules/filter/tpmfilter/tpmfilter.cc
View File

@ -56,7 +56,7 @@
#include <thread>
#include <maxscale/alloc.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/modinfo.h>
#include <maxscale/modutil.hh>
#include <maxscale/log.h>

2
server/modules/routing/debugcli/debugcmd.cc
View File

@ -41,7 +41,7 @@
#include <maxscale/buffer.h>
#include <maxscale/config.hh>
#include <maxscale/dcb.h>
#include <maxscale/filter.h>
#include <maxscale/filter.hh>
#include <maxscale/housekeeper.h>
#include <maxscale/log.h>
#include <maxscale/maxscale.h>