7.26.3. Plugin#

7.26.3.1. 概要#

Groonga supports plugin. You can create a new plugin with the following API.

TOOD: Describe about how to create the minimum plugin here or create a tutorial about it.

GRN_PLUGIN_MALLOC(ctx, size)#: GRN_PLUGIN_MALLOC() allocates size bytes and returns a pointer to the allocated memory space. Note that the memory space is associated with ctx.

GRN_PLUGIN_REALLOC(ctx, ptr, size)#: GRN_PLUGIN_REALLOC() resizes the memory space pointed to by ptr or allocates a new memory space of size bytes. GRN_PLUGIN_REALLOC() returns a pointer to the memory space. The contents is unchanged or copied from the old memory space to the new memory space.

GRN_PLUGIN_FREE(ctx, ptr)#: GRN_PLUGIN_FREE() frees a memory space allocated by GRN_PLUGIN_MALLOC() or GRN_PLUGIN_REALLOC(). This means that ptr must be a pointer returned by GRN_PLUGIN_MALLOC() or GRN_PLUGIN_REALLOC().

GRN_PLUGIN_LOG(ctx, level, ...)#: GRN_PLUGIN_LOG() reports a log of level. Its error message is generated from the varying number of arguments, in which the first one is the format string and the rest are its arguments. See grn_log_level in "groonga.h" for more details of level.

GRN_PLUGIN_ERROR(ctx, error_code, ...)#: GRN_PLUGIN_ERROR() reports an error of error_code. Its error message is generated from the varying number of arguments, in which the first one is the format string and the rest are its arguments. See grn_rc in "groonga.h" for more details of error_code.

type grn_plugin_mutex#: grn_plugin_mutex is available to make a critical section. See the following functions.

grn_plugin_mutex *grn_plugin_mutex_open(grn_ctx *ctx)#: grn_plugin_mutex_open() returns a pointer to a new object of grn_plugin_mutex. Memory for the new object is obtained with GRN_PLUGIN_MALLOC(). grn_plugin_mutex_open() returns NULL if sufficient memory is not available.

void grn_plugin_mutex_close(grn_ctx *ctx, grn_plugin_mutex *mutex)#: grn_plugin_mutex_close() finalizes an object of grn_plugin_mutex and then frees memory allocated for that object.

void grn_plugin_mutex_lock(grn_ctx *ctx, grn_plugin_mutex *mutex)#: grn_plugin_mutex_lock() locks a mutex object. If the object is already locked, the calling thread waits until the object will be unlocked.

void grn_plugin_mutex_unlock(grn_ctx *ctx, grn_plugin_mutex *mutex)#: grn_plugin_mutex_unlock() unlocks a mutex object. grn_plugin_mutex_unlock() should not be called for an unlocked object.

grn_obj *grn_plugin_proc_alloc(grn_ctx *ctx, grn_user_data *user_data, grn_id domain, grn_obj_flags flags)#: grn_plugin_proc_alloc() allocates a grn_obj object. You can use it in function that is registered as GRN_PROC_FUNCTION.

grn_obj grn_plugin_proc_get_var(grn_ctx *ctx, grn_user_data *user_data, const char *name, int name_size)#

It gets a variable value from grn_user_data by specifying the variable name.

パラメータ:

name -- 変数名。
name_size -- The number of bytes of name. If name_size is negative, name must be NUL-terminated. name_size is computed by strlen(name) for the case.

戻り値:

成功すると変数の値を返します。失敗するとNULLを返します。

grn_obj *grn_plugin_proc_get_var_by_offset(grn_ctx *ctx, grn_user_data *user_data, unsigned int offset)#

It gets a variable value from grn_user_data by specifying the offset position of the variable.

パラメータ:

戻り値:

成功すると変数の値を返します。失敗するとNULLを返します。

const char *grn_plugin_win32_base_dir(void)#: バージョン 5.0.9. で非推奨: Use grn_plugin_windows_base_dir() instead.

It returns the Groonga install directory. The install directory is computed from the directory that has groonga.dll. You can use the directory to generate install directory aware path. It only works on Windows. It returns NULL on other platforms.

const char *grn_plugin_windows_base_dir(void)#: Added in version 5.0.9.

It returns the Groonga install directory. The install directory is computed from the directory that has groonga.dll. You can use the directory to generate install directory aware path. It only works on Windows. It returns NULL on other platforms.

int grn_plugin_charlen(grn_ctx *ctx, const char *str_ptr, unsigned int str_length, grn_encoding encoding)#: grn_plugin_charlen() returns the length (#bytes) of the first character in the string specified by str_ptr and str_length. If the starting bytes are invalid as a character, grn_plugin_charlen() returns 0. See grn_encoding in "groonga.h" for more details of encoding.

int grn_plugin_isspace(grn_ctx *ctx, const char *str_ptr, unsigned int str_length, grn_encoding encoding)#: grn_plugin_isspace() returns the length (#bytes) of the first character in the string specified by str_ptr and str_length if it is a space character. Otherwise, grn_plugin_isspace() returns 0.

grn_rc grn_plugin_expr_var_init(grn_ctx *ctx, grn_expr_var *var, const char *name, int name_size)#

It initializes a grn_expr_var.

パラメータ:

var -- The pointer of grn_expr_var object to be initialized.
name -- The name of grn_expr_var object to be initialized.
name_size -- The number of bytes of name. If name_size is negative, name must be NUL-terminated. name_size is computed by strlen(name) for the case.

戻り値:

GRN_SUCCESS 。この関数は失敗しません。

grn_obj *grn_plugin_command_create(grn_ctx *ctx, const char *name, int name_size, grn_proc_func func, unsigned int n_vars, grn_expr_var *vars)#

It creates a command.

パラメータ:

name -- The proc name of the command to be created.
name_size -- The number of bytes of name. If name_size is negative, name must be NUL-terminated. name_size is computed by strlen(name) for the case.
func -- The function name to be called by the created command.
n_vars -- The number of the variables of the command to create.
vars -- The pointer of initialized grn_expr_var object.

戻り値:

The created command object if it creates a command successfully, NULL otherwise. See ctx for error details.