MySQL  8.0.27
Source Code Documentation
udf_metadata.h
Go to the documentation of this file.
1 /* Copyright (c) 2019, 2021, Oracle and/or its affiliates.
2 
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6 
7 This program is also distributed with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have included with MySQL.
13 
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License, version 2.0, for more details.
18 
19 You should have received a copy of the GNU General Public License
20 along with this program; if not, write to the Free Software
21 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 #ifndef UDF_METADATA_H
24 #define UDF_METADATA_H
25 
28 
29 /**
30  Service for getting and setting the extension attributes of UDF arguments
31  and return value.
32 */
33 BEGIN_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 */
67 DECLARE_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 */
102 DECLARE_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 */
136 DECLARE_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 */
172 DECLARE_BOOL_METHOD(result_set, (UDF_INIT * udf_init,
173  const char *extension_type, void *in_value));
174 
175 END_SERVICE_DEFINITION(mysql_udf_metadata)
176 
177 #endif // UDF_METADATA_H
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:90
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:85
#define DECLARE_BOOL_METHOD(name, args)
Declares a method that returns bool as a part of the Service definition.
Definition: service.h:111
Definition: udf_registration_types.h:47
Information about the result of a user defined function.
Definition: udf_registration_types.h:65