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