MySQL 9.0.0
Source Code Documentation
udf_metadata.h
Go to the documentation of this file.
1/* Copyright (c) 2019, 2024, Oracle and/or its affiliates.
2
3This program is free software; you can redistribute it and/or modify
4it under the terms of the GNU General Public License, version 2.0,
5as published by the Free Software Foundation.
6
7This program is designed to work with certain software (including
8but not limited to OpenSSL) that is licensed under separate terms,
9as designated in a particular file or component or in included license
10documentation. The authors of MySQL hereby grant you an additional
11permission to link the program and your derivative works with the
12separately licensed software that they have either included with
13the program or referenced in the documentation.
14
15This program is distributed in the hope that it will be useful,
16but WITHOUT ANY WARRANTY; without even the implied warranty of
17MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18GNU General Public License, version 2.0, for more details.
19
20You should have received a copy of the GNU General Public License
21along with this program; if not, write to the Free Software
22Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef UDF_METADATA_H
25#define UDF_METADATA_H
26
27#include <mysql/components/service.h>
28#include <mysql/udf_registration_types.h>
29
30/**
31 Service for getting and setting the extension attributes of UDF arguments
32 and return value.
33*/
34BEGIN_SERVICE_DEFINITION(mysql_udf_metadata)
35
36/**
37 Retrieves extension attributes of a UDF argument. The extension attributes
38 are retrieved based on the extension_type. Following extension_type are
39 supported as of now :
40
41 (1) charset - Character set name of a UDF argument
42 (2) collation - Collation name of a UDF argument.
43
44 The method returns the requested extension attribute in the output
45 parameter. One must cast the output value to a respective data type.
46 It sets error message if it is unable to retrieve extension attribute
47
48 One could retrieve the charset of first UDF argument as following.
49
50 void *out_value = nullptr;
51 my_service<SERVICE_TYPE(mysql_udf_metadata)> service("mysql_udf_metadata",
52 mysql_plugin_registry_acquire());
53 service->argument_get(udf_args, "charset", 0, &out_value);
54 const char *charset_name = static_cast<const char *>(out_value);
55
56 @param [in] udf_args Pointer to the UDF arguments struct that contains the
57 extension pointer.
58 @param [in] extension_type Argument type to get
59 @param [in] index Index of UDF argument
60 @param [out] out_value Pointer to the character set
61
62 @return
63 true Error conditions. For instance :
64 1. invalid argument type 'extension_type'
65 2. null extension pointer
66 false Otherwise
67*/
68DECLARE_BOOL_METHOD(argument_get,
69 (UDF_ARGS * udf_args, const char *extension_type,
70 unsigned int index, void **out_value));
71
72/**
73 Retrieves the extension attribute of UDF return value.
74 a UDF argument. The extension attributes are retrieved based on the
75 extension_type. Following extension_type are supported:
76
77 (1) charset - Character set name of a UDF argument
78 (2) collation - Collation name of a UDF argument.
79
80 The method returns the requested extension attribute in the output
81 parameter. One must cast the output value to a respective data type.
82 It sets error message if it is unable to retrieve extension attribute
83
84 One could retrieve the charset of return value as following.
85
86 void *out_value = nullptr;
87 my_service<SERVICE_TYPE(mysql_udf_metadata)> service("mysql_udf_metadata",
88 mysql_plugin_registry_acquire());
89 service->result_get(udf_init, "charset", 0, &out_value);
90 const char *charset_name = static_cast<const char *>(out_value);
91
92 @param [in] udf_init Pointer to the UDF_INIT struct struct that contains
93 the extension pointer for return value
94 @param [in] extension_type Argument type to get
95 @param [out] out_value Pointer to the arguments.
96
97 @return
98 true Error conditions. For instance :
99 1. invalid argument type 'extension_type'
100 2. null extension pointer
101 false Otherwise
102*/
103DECLARE_BOOL_METHOD(result_get, (UDF_INIT * udf_init,
104 const char *extension_type, void **out_value));
105/**
106 Sets the extension attribute of a UDF argument. The extension attribute
107 could be set only for supported extension type. Following extension_type
108 are supported:
109
110 (1) charset - Character set name of a UDF argument
111 (2) collation - Collation name of a UDF argument.
112
113 The method sets the input value as the extension attribute of corresponding
114 UDF argument. It sets error message if it is unable to set the extension
115 attribute.
116
117 One could set the charset of first argument as following.
118
119 const char* name = "utf8mb4";
120 char *value = const_cast<char*>(name);
121 my_service<SERVICE_TYPE(mysql_udf_metadata)> service("mysql_udf_metadata",
122 mysql_plugin_registry_acquire());
123 service->argument_set(udf_args, "charset", 0, static_cast<void *>(value));
124
125 @param [in, out] udf_args Pointer to the UDF arguments struct that contains
126 the extension pointer.
127 @param [in] extension_type Argument type to set.
128 @param [in] arguments Pointer to input arguments to set.If it is a
129 char* then that must be null terminated.
130
131 @return
132 true Error conditions. For instance :
133 1. invalid argument type 'extension_type'
134 2. null extension pointer
135 false Otherwise
136*/
137DECLARE_BOOL_METHOD(argument_set,
138 (UDF_ARGS * udf_args, const char *extension_type,
139 unsigned int index, void *in_value));
140
141/**
142 Sets the extension attribute of the UDF return value. The extension attribute
143 could be set only for supported extension type. Following extension_type
144 are supported:
145
146 (1) charset - Character set name of a UDF argument
147 (2) collation - Collation name of a UDF argument.
148
149 The method sets the input value as the extension attribute of return value.
150 It sets error message if it is unable to set the extension attribute.
151
152 One could set the charset of return value as following.
153
154 const char* name = "utf8mb4";
155 char *value = const_cast<char*>(name);
156 my_service<SERVICE_TYPE(mysql_udf_metadata)> service("mysql_udf_metadata",
157 mysql_plugin_registry_acquire());
158 service->result_set(udf_init, "charset", 0, static_cast<void *>(value));
159
160 @param [in, out] udf_init Pointer to UDF_INIT argument that contains the
161 extension pointer.
162 @param [in] extension_type Argument type that has to be set as an extension
163 argument. If it is invalid then the method does
164 nothing.
165 @param [in] in_value Input argument that has to be read. If it is a
166 char* then that must be null terminated.
167 @return
168 true Error conditions. For instance :
169 1. invalid argument type 'extension_type'
170 2. null extension pointer
171 false Otherwise
172*/
173DECLARE_BOOL_METHOD(result_set, (UDF_INIT * udf_init,
174 const char *extension_type, void *in_value));
175
176END_SERVICE_DEFINITION(mysql_udf_metadata)
177
178#endif // UDF_METADATA_H
END_SERVICE_DEFINITION
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:91
BEGIN_SERVICE_DEFINITION
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:86
DECLARE_BOOL_METHOD
#define DECLARE_BOOL_METHOD(name, args)
Declares a method that returns bool as a part of the Service definition.
Definition: service.h:112
UDF_ARGS
Definition: udf_registration_types.h:48
UDF_INIT
Information about the result of a user defined function.
Definition: udf_registration_types.h:66
udf_registration_types.h