MXS-2205 Combine maxscale/filter.h with maxscale/filter.hh
This commit is contained in:
Esa Korhonen
@ -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;
|
||||
@ -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
|
||||
{
|
||||
|
||||
@ -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;
|
||||
|
||||
Reference in New Issue
Block a user