📄 create_function.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><html><head><title>Create Or Redefine SQL Functions</title><style type="text/css">body { margin: auto; font-family: "Verdana" "sans-serif"; padding: 8px 1%;}a { color: #45735f }a:visited { color: #734559 }.logo { position:absolute; margin:3px; }.tagline { float:right; text-align:right; font-style:italic; width:240px; margin:12px; margin-top:58px;}.toolbar { font-variant: small-caps; text-align: center; line-height: 1.6em; margin: 0; padding:1px 8px;}.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }.toolbar a:visited { color: white; }.toolbar a:hover { color: #80a796; background: white; }.content { margin: 5%; }.content dt { font-weight:bold; }.content dd { margin-bottom: 25px; margin-left:20%; }.content ul { padding:0px; padding-left: 15px; margin:0px; }/* rounded corners */.se { background: url(../images/se.png) 100% 100% no-repeat #80a796}.sw { background: url(../images/sw.png) 0% 100% no-repeat }.ne { background: url(../images/ne.png) 100% 0% no-repeat }.nw { background: url(../images/nw.png) 0% 0% no-repeat }</style><meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head><body><div><!-- container div to satisfy validator --><a href="../index.html"><img class="logo" src="../images/SQLite.gif" alt="SQLite Logo" border="0"></a><div><!-- IE hack to prevent disappearing logo--></div><div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div><table width=100% style="clear:both"><tr><td> <div class="se"><div class="sw"><div class="ne"><div class="nw"> <div class="toolbar"> <a href="../about.html">About</a> <a href="../sitemap.html">Sitemap</a> <a href="../docs.html">Documentation</a> <a href="../download.html">Download</a> <a href="../copyright.html">License</a> <a href="../news.html">News</a> <a href="http://www.sqlite.org/cvstrac/index">Developers</a> <a href="../support.html">Support</a> </div></div></div></div></div></td></tr></table> <a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Create Or Redefine SQL Functions</h2><blockquote><pre>int sqlite3_create_function( sqlite3 *db, const char *zFunctionName, int nArg, int eTextRep, void *pApp, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*));int sqlite3_create_function16( sqlite3 *db, const void *zFunctionName, int nArg, int eTextRep, void *pApp, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*));</pre></blockquote><p>These two functions (collectively known as"function creation routines") are used to add SQL functions or aggregatesor to redefine the behavior of existing SQL functions or aggregates. Thedifference only between the two is that the second parameter, thename of the (scalar) function or aggregate, is encoded in UTF-8 forsqlite3_create_function() and UTF-16 for sqlite3_create_function16().</p><p>The first parameter is the <a href="../c3ref/sqlite3.html">database connection</a> to which the SQLfunction is to be added. If a singleprogram uses more than one <a href="../c3ref/sqlite3.html">database connection</a> internally, then SQLfunctions must be added individually to each <a href="../c3ref/sqlite3.html">database connection</a>.</p><p>The second parameter is the name of the SQL function to be createdor redefined.The length of the name is limited to 255 bytes, exclusive of thezero-terminator. Note that the name length limit is in bytes, notcharacters. Any attempt to create a function with a longer namewill result in an SQLITE_ERROR error.</p><p>The third parameter is the number of arguments that the SQL function oraggregate takes. If this parameter is negative, then the SQL function oraggregate may take any number of arguments.</p><p>The fourth parameter, eTextRep, specifies what<a href="../c3ref/c_any.html">text encoding</a> this SQL function prefers forits parameters. Any SQL function implementation should be able to workwork with UTF-8, UTF-16le, or UTF-16be. But some implementations may bemore efficient with one encoding than another. It is allowed toinvoke sqlite3_create_function() or sqlite3_create_function16() multipletimes with the same function but with different values of eTextRep.When multiple implementations of the same function are available, SQLitewill pick the one that involves the least amount of data conversion.If there is only a single implementation which does not care whattext encoding is used, then the fourth argument should be<a href="../c3ref/c_any.html">SQLITE_ANY</a>.</p><p>The fifth parameter is an arbitrary pointer. The implementationof the function can gain access to this pointer using<a href="../c3ref/user_data.html">sqlite3_user_data()</a>.</p><p>The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, arepointers to C-language functions that implement the SQLfunction or aggregate. A scalar SQL function requires an implementation ofthe xFunc callback only, NULL pointers should be passed as the xStepand xFinal parameters. An aggregate SQL function requires an implementationof xStep and xFinal and NULL should be passed for xFunc. To delete anexisting SQL function or aggregate, pass NULL for all three functioncallback.</p><p>It is permitted to register multiple implementations of the samefunctions with the same name but with either differing numbers ofarguments or differing perferred text encodings. SQLite will usethe implementation most closely matches the way in which theSQL function is used.</p><p><h3>Invariants:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">F16103</td> <td valign="top">The <a href="../c3ref/create_function.html">sqlite3_create_function16()</a> interface behaves exactlylike <a href="../c3ref/create_function.html">sqlite3_create_function()</a> in every way except that itinterprets the zFunctionName argument aszero-terminated UTF-16 native byte order instead of as azero-terminated UTF-8.</td></tr><tr><td valign="top">F16106</td> <td valign="top">A successful invocation ofthe <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,E,...)</a> interface registersor replaces callback functions in <a href="../c3ref/sqlite3.html">database connection</a> Dused to implement the SQL function named X with N parametersand having a perferred text encoding of E.</td></tr><tr><td valign="top">F16109</td> <td valign="top">A successful call to <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,E,P,F,S,L)</a>replaces the P, F, S, and L values from any prior calls withthe same D, X, N, and E values.</td></tr><tr><td valign="top">F16112</td> <td valign="top">The <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,...)</a> interface fails witha return code of <a href="../c3ref/c_abort.html">SQLITE_ERROR</a> if the SQL function name X islonger than 255 bytes exclusive of the zero terminator.</td></tr><tr><td valign="top">F16118</td> <td valign="top">Either F must be NULL and S and L are non-NULL or else Fis non-NULL and S and L are NULL, otherwise<a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,E,P,F,S,L)</a> returns <a href="../c3ref/c_abort.html">SQLITE_ERROR</a>.</td></tr><tr><td valign="top">F16121</td> <td valign="top">The <a href="../c3ref/create_function.html">sqlite3_create_function(D,...)</a> interface fails with anerror code of <a href="../c3ref/c_abort.html">SQLITE_BUSY</a> if there exist <a href="../c3ref/stmt.html">prepared statements</a>associated with the <a href="../c3ref/sqlite3.html">database connection</a> D.</td></tr><tr><td valign="top">F16124</td> <td valign="top">The <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,...)</a> interface fails with anerror code of <a href="../c3ref/c_abort.html">SQLITE_ERROR</a> if parameter N (specifying the numberof arguments to the SQL function being registered) is lessthan -1 or greater than 127.</td></tr><tr><td valign="top">F16127</td> <td valign="top">When N is non-negative, the <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,...)</a>interface causes callbacks to be invoked for the SQL functionnamed X when the number of arguments to the SQL function isexactly N.</td></tr><tr><td valign="top">F16130</td> <td valign="top">When N is -1, the <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,...)</a>interface causes callbacks to be invoked for the SQL functionnamed X with any number of arguments.</td></tr><tr><td valign="top">F16133</td> <td valign="top">When calls to <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,...)</a>specify multiple implementations of the same function Xand when one implementation has N>=0 and the other has N=(-1)the implementation with a non-zero N is preferred.</td></tr><tr><td valign="top">F16136</td> <td valign="top">When calls to <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,E,...)</a>specify multiple implementations of the same function X withthe same number of arguments N but with differentencodings E, then the implementation where E matches thedatabase encoding is preferred.</td></tr><tr><td valign="top">F16139</td> <td valign="top">For an aggregate SQL function created using<a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,E,P,0,S,L)</a> the finializerfunction L will always be invoked exactly once if thestep function S is called one or more times.</td></tr><tr><td valign="top">F16142</td> <td valign="top">When SQLite invokes either the xFunc or xStep function ofan application-defined SQL function or aggregate createdby <a href="../c3ref/create_function.html">sqlite3_create_function()</a> or <a href="../c3ref/create_function.html">sqlite3_create_function16()</a>,then the array of <a href="../c3ref/value.html">sqlite3_value</a> objects passed as thethird parameter are always <a href="../c3ref/value.html">protected sqlite3_value</a> objects.</td></tr></table></p><p>See also lists of <a href="objlist.html">Objects</a>, <a href="constlist.html">Constants</a>, and <a href="funclist.html">Functions</a>.</p><hr><small><i>This page last modified 2008/05/12 13:08:44 UTC</i></small></div></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -