Debian Codegraph @

www/c3ref/result_blob.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>Setting The Result Of An SQL Function</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- keywords: sqlite3_result_blob sqlite3_result_blob64 sqlite3_result_double sqlite3_result_error sqlite3_result_error16 sqlite3_result_error_code sqlite3_result_error_nomem sqlite3_result_error_toobig sqlite3_result_int sqlite3_result_int64 sqlite3_result_null sqlite3_result_pointer sqlite3_result_text sqlite3_result_text16 sqlite3_result_text16be sqlite3_result_text16le sqlite3_result_text64 sqlite3_result_value sqlite3_result_zeroblob sqlite3_result_zeroblob64 -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Setting The Result Of An SQL Function</h2>
122 </div>
123 <blockquote><pre>
124 void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
125 void sqlite3_result_blob64(sqlite3_context*,const void*,
126 sqlite3_uint64,void(*)(void*));
127 void sqlite3_result_double(sqlite3_context*, double);
128 void sqlite3_result_error(sqlite3_context*, const char*, int);
129 void sqlite3_result_error16(sqlite3_context*, const void*, int);
130 void sqlite3_result_error_toobig(sqlite3_context*);
131 void sqlite3_result_error_nomem(sqlite3_context*);
132 void sqlite3_result_error_code(sqlite3_context*, int);
133 void sqlite3_result_int(sqlite3_context*, int);
134 void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
135 void sqlite3_result_null(sqlite3_context*);
136 void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
137 void sqlite3_result_text64(sqlite3_context*, const char *z, sqlite3_uint64 n,
138 void(*)(void*), unsigned char encoding);
139 void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
140 void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
141 void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
142 void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
143 void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
144 void sqlite3_result_zeroblob(sqlite3_context*, int n);
145 int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
146 </pre></blockquote>
147 <p>
148 These routines are used by the xFunc or xFinal callbacks that
149 implement SQL functions and aggregates. See
150 <a href="../c3ref/create_function.html">sqlite3_create_function()</a> and <a href="../c3ref/create_function.html">sqlite3_create_function16()</a>
151 for additional information.</p>
152
153 <p>These functions work very much like the <a href="../c3ref/bind_blob.html">parameter binding</a> family of
154 functions used to bind values to host parameters in prepared statements.
155 Refer to the <a href="../c3ref/bind_blob.html">SQL parameter</a> documentation for additional information.</p>
156
157 <p>The sqlite3_result_blob() interface sets the result from
158 an application-defined function to be the BLOB whose content is pointed
159 to by the second parameter and which is N bytes long where N is the
160 third parameter.</p>
161
162 <p>The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
163 interfaces set the result of the application-defined function to be
164 a BLOB containing all zero bytes and N bytes in size.</p>
165
166 <p>The sqlite3_result_double() interface sets the result from
167 an application-defined function to be a floating point value specified
168 by its 2nd argument.</p>
169
170 <p>The sqlite3_result_error() and sqlite3_result_error16() functions
171 cause the implemented SQL function to throw an exception.
172 SQLite uses the string pointed to by the
173 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
174 as the text of an error message. SQLite interprets the error
175 message string from sqlite3_result_error() as UTF-8. SQLite
176 interprets the string from sqlite3_result_error16() as UTF-16 using
177 the same <a href="../c3ref/bind_blob.html#byteorderdeterminationrules">byte-order determination rules</a> as <a href="../c3ref/bind_blob.html">sqlite3_bind_text16()</a>.
178 If the third parameter to sqlite3_result_error()
179 or sqlite3_result_error16() is negative then SQLite takes as the error
180 message all text up through the first zero character.
181 If the third parameter to sqlite3_result_error() or
182 sqlite3_result_error16() is non-negative then SQLite takes that many
183 bytes (not characters) from the 2nd parameter as the error message.
184 The sqlite3_result_error() and sqlite3_result_error16()
185 routines make a private copy of the error message text before
186 they return. Hence, the calling function can deallocate or
187 modify the text after they return without harm.
188 The sqlite3_result_error_code() function changes the error code
189 returned by SQLite as a result of an error in a function. By default,
190 the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error()
191 or sqlite3_result_error16() resets the error code to SQLITE_ERROR.</p>
192
193 <p>The sqlite3_result_error_toobig() interface causes SQLite to throw an
194 error indicating that a string or BLOB is too long to represent.</p>
195
196 <p>The sqlite3_result_error_nomem() interface causes SQLite to throw an
197 error indicating that a memory allocation failed.</p>
198
199 <p>The sqlite3_result_int() interface sets the return value
200 of the application-defined function to be the 32-bit signed integer
201 value given in the 2nd argument.
202 The sqlite3_result_int64() interface sets the return value
203 of the application-defined function to be the 64-bit signed integer
204 value given in the 2nd argument.</p>
205
206 <p>The sqlite3_result_null() interface sets the return value
207 of the application-defined function to be NULL.</p>
208
209 <p>The sqlite3_result_text(), sqlite3_result_text16(),
210 sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
211 set the return value of the application-defined function to be
212 a text string which is represented as UTF-8, UTF-16 native byte order,
213 UTF-16 little endian, or UTF-16 big endian, respectively.
214 The sqlite3_result_text64(C,Z,N,D,E) interface sets the return value of an
215 application-defined function to be a text string in an encoding
216 specified the E parameter, which must be one
217 of <a href="../c3ref/c_any.html#sqliteutf8">SQLITE_UTF8</a>, <a href="../c3ref/c_any.html#sqliteutf8zt">SQLITE_UTF8_ZT</a>, <a href="../c3ref/c_any.html#sqliteutf16">SQLITE_UTF16</a>, <a href="../c3ref/c_any.html#sqliteutf16be">SQLITE_UTF16BE</a>,
218 or <a href="../c3ref/c_any.html#sqliteutf16le">SQLITE_UTF16LE</a>. The special value <a href="../c3ref/c_any.html#sqliteutf8zt">SQLITE_UTF8_ZT</a> means that
219 the result text is both UTF-8 and zero-terminated. In other words,
220 SQLITE_UTF8_ZT means that the Z array holds at least N+1 bytes and that
221 the Z&#91;N&#93; is zero.
222 SQLite takes the text result from the application from
223 the 2nd parameter of the sqlite3_result_text* interfaces.
224 If the 3rd parameter to any of the sqlite3_result_text* interfaces
225 other than sqlite3_result_text64() is negative, then SQLite computes
226 the string length itself by searching the 2nd parameter for the first
227 zero character.
228 If the 3rd parameter to the sqlite3_result_text* interfaces
229 is non-negative, then as many bytes (not characters) of the text
230 pointed to by the 2nd parameter are taken as the application-defined
231 function result. If the 3rd parameter is non-negative, then it
232 must be the byte offset into the string where the NUL terminator would
233 appear if the string were NUL terminated. If any NUL characters occur
234 in the string at a byte offset that is less than the value of the 3rd
235 parameter, then the resulting string will contain embedded NULs and the
236 result of expressions operating on strings with embedded NULs is undefined.
237 If the 4th parameter to the sqlite3_result_text* interfaces
238 or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
239 function as the destructor on the text or BLOB result when it has
240 finished using that result.
241 If the 4th parameter to the sqlite3_result_text* interfaces or to
242 sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
243 assumes that the text or BLOB result is in constant space and does not
244 copy the content of the parameter nor call a destructor on the content
245 when it has finished using that result.
246 If the 4th parameter to the sqlite3_result_text* interfaces
247 or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
248 then SQLite makes a copy of the result into space obtained
249 from <a href="../c3ref/free.html">sqlite3_malloc()</a> before it returns.</p>
250
251 <p>For the sqlite3_result_text16(), sqlite3_result_text16le(), and
252 sqlite3_result_text16be() routines, and for sqlite3_result_text64()
253 when the encoding is not UTF8, if the input UTF16 begins with a
254 byte-order mark (BOM, U+FEFF) then the BOM is removed from the
255 string and the rest of the string is interpreted according to the
256 byte-order specified by the BOM. The byte-order specified by
257 the BOM at the beginning of the text overrides the byte-order
258 specified by the interface procedure. So, for example, if
259 sqlite3_result_text16le() is invoked with text that begins
260 with bytes 0xfe, 0xff (a big-endian byte-order mark) then the
261 first two bytes of input are skipped and the remaining input
262 is interpreted as UTF16BE text.</p>
263
264 <p>For UTF16 input text to the sqlite3_result_text16(),
265 sqlite3_result_text16be(), sqlite3_result_text16le(), and
266 sqlite3_result_text64() routines, if the text contains invalid
267 UTF16 characters, the invalid characters might be converted
268 into the unicode replacement character, U+FFFD.</p>
269
270 <p>The sqlite3_result_value() interface sets the result of
271 the application-defined function to be a copy of the
272 <a href="../c3ref/value.html">unprotected sqlite3_value</a> object specified by the 2nd parameter. The
273 sqlite3_result_value() interface makes a copy of the <a href="../c3ref/value.html">sqlite3_value</a>
274 so that the <a href="../c3ref/value.html">sqlite3_value</a> specified in the parameter may change or
275 be deallocated after sqlite3_result_value() returns without harm.
276 A <a href="../c3ref/value.html">protected sqlite3_value</a> object may always be used where an
277 <a href="../c3ref/value.html">unprotected sqlite3_value</a> object is required, so either
278 kind of <a href="../c3ref/value.html">sqlite3_value</a> object can be used with this interface.</p>
279
280 <p>The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
281 SQL NULL value, just like <a href="../c3ref/result_blob.html">sqlite3_result_null(C)</a>, except that it
282 also associates the host-language pointer P or type T with that
283 NULL value such that the pointer can be retrieved within an
284 <a href="../appfunc.html">application-defined SQL function</a> using <a href="../c3ref/value_blob.html">sqlite3_value_pointer()</a>.
285 If the D parameter is not NULL, then it is a pointer to a destructor
286 for the P parameter. SQLite invokes D with P as its only argument
287 when SQLite is finished with P. The T parameter should be a static
288 string and preferably a string literal. The sqlite3_result_pointer()
289 routine is part of the <a href="../bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p>
290
291 <p>If these routines are called from within a different thread
292 than the one containing the application-defined function that received
293 the <a href="../c3ref/context.html">sqlite3_context</a> pointer, the results are undefined.
294 </p><p>See also lists of
295 <a href="../c3ref/objlist.html">Objects</a>,
296 <a href="../c3ref/constlist.html">Constants</a>, and
297 <a href="../c3ref/funclist.html">Functions</a>.</p>
298