📄 create_function.html

📁 sqlite3源码,适合作为嵌入式（embedded）
💻 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 aggregates or to redefine the behaviorof existing SQL functions or aggregates.  The only difference between thetwo is that the second parameter, the name of the (scalar) function oraggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16for 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 single program uses more than one databaseconnection internally, then SQL functions must be added individually toeach database connection.</p><p>The second parameter is the name of the SQL function to be created orredefined.  The length of the name is limited to 255 bytes, exclusive ofthe zero-terminator.  Note that the name length limit is in bytes, notcharacters.  Any attempt to create a function with a longer namewill result in <a href="../c3ref/c_abort.html">SQLITE_ERROR</a> being returned.</p><p>The third parameter (nArg)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 what textencoding 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 implementation of thefunction 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 SQL function oraggregate. A scalar SQL function requires an implementation of the xFunccallback only, NULL pointers should be passed as the xStep and xFinalparameters. An aggregate SQL function requires an implementation of xStepand xFinal and NULL should be passed for xFunc. To delete an existingSQL function or aggregate, pass NULL for all three function callbacks.</p><p>It is permitted to register multiple implementations of the samefunctions with the same name but with either differing numbers ofarguments or differing preferred text encodings.  SQLite will usethe implementation most closely matches the way in which theSQL function is used.  A function implementation with a non-negativenArg parameter is a better match than a function implementation witha negative nArg.  A function where the preferred text encodingmatches the database encoding is a bettermatch than a function where the encoding is different.A function where the encoding difference is between UTF16le and UTF16beis a closer match than a function where the encoding difference isbetween UTF8 and UTF16.</p><p>Built-in functions may be overloaded by new application-defined functions.The first application-defined function with a given name overrides allbuilt-in functions in the same <a href="../c3ref/sqlite3.html">database connection</a> with the same name.Subsequent application-defined functions of the same name only overrideprior application-defined functions that are an exact match for thenumber of parameters and preferred encoding.</p><p>An application-defined function is permitted to call otherSQLite interfaces.  However, such calls must notclose the database connection nor finalize or reset the preparedstatement in which the function is running.</p><p><h3>Invariants:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">H16103</td> <td valign="top">The <a href="../c3ref/create_function.html">sqlite3_create_function16(D,X,...)</a> interface shall behaveas <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,...)</a> in every way except that itinterprets the X argument as zero-terminated UTF-16native byte order instead of as zero-terminated UTF-8.</td></tr><tr><td valign="top">H16106</td> <td valign="top">A successful invocation of the<a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,E,...)</a> interface shall registeror replaces callback functions in the <a href="../c3ref/sqlite3.html">database connection</a> Dused to implement the SQL function named X with N parametersand having a preferred text encoding of E.</td></tr><tr><td valign="top">H16109</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>shall replace 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">H16112</td> <td valign="top">The <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,...)</a> interface shall failif the SQL function name X islonger than 255 bytes exclusive of the zero terminator.</td></tr><tr><td valign="top">H16118</td> <td valign="top">The <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,E,P,F,S,L)</a> interfaceshall fail unless either F is NULL and S and L are non-NULL orF is non-NULL and S and L are NULL.</td></tr><tr><td valign="top">H16121</td> <td valign="top">The <a href="../c3ref/create_function.html">sqlite3_create_function(D,...)</a> interface shall 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">H16124</td> <td valign="top">The <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,...)</a> interface shall fail withan error code of <a href="../c3ref/c_abort.html">SQLITE_ERROR</a> if parameter N is lessthan -1 or greater than 127.</td></tr><tr><td valign="top">H16127</td> <td valign="top">When N is non-negative, the <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,...)</a>interface shall register callbacks to be invoked for theSQL functionnamed X when the number of arguments to the SQL function isexactly N.</td></tr><tr><td valign="top">H16130</td> <td valign="top">When N is -1, the <a href="../c3ref/create_function.html">sqlite3_create_function(D,X,N,...)</a>interface shall register callbacks to be invoked for the SQLfunction named X with any number of arguments.</td></tr><tr><td valign="top">H16133</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 shall be preferred.</td></tr><tr><td valign="top">H16136</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 shall preferred.</td></tr><tr><td valign="top">H16139</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 finalizerfunction L shall always be invoked exactly once if thestep function S is called one or more times.</td></tr><tr><td valign="top">H16142</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 shall be <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/12/09 18:44:04 UTC</i></small></div></body></html>
⌨️ 快捷键说明

复制代码 Ctrl + C
搜索代码 Ctrl + F
全屏模式 F11
切换主题 Ctrl + Shift + D
显示快捷键 ?
增大字号 Ctrl + =
减小字号 Ctrl + -