|
void *sqlite3_get_auxdata(sqlite3_context*, int N); void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
The following two functions may be used by scalar SQL functions to associate metadata with argument values. If the same value is passed to multiple invocations of the same SQL function during query execution, under some circumstances the associated metadata may be preserved. This may be used, for example, to add a regular-expression matching scalar function. The compiled version of the regular expression is stored as metadata associated with the SQL value passed as the regular expression pattern. The compiled regular expression can be reused on multiple invocations of the same function so that the original pattern string does not need to be recompiled on each invocation.
The sqlite3_get_auxdata() interface returns a pointer to the metadata associated by the sqlite3_set_auxdata() function with the Nth argument value to the application-defined function. If no metadata has been ever been set for the Nth argument of the function, or if the corresponding function parameter has changed since the meta-data was set, then sqlite3_get_auxdata() returns a NULL pointer.
The sqlite3_set_auxdata() interface saves the metadata pointed to by its 3rd parameter as the metadata for the N-th argument of the application-defined function. Subsequent calls to sqlite3_get_auxdata() might return this data, if it has not been destroyed. If it is not NULL, SQLite will invoke the destructor function given by the 4th parameter to sqlite3_set_auxdata() on the metadata when the corresponding function parameter changes or when the SQL statement completes, whichever comes first.
SQLite is free to call the destructor and drop metadata on any parameter of any function at any time. The only guarantee is that the destructor will be called before the metadata is dropped.
In practice, metadata is preserved between function calls for expressions that are constant at compile time. This includes literal values and SQL variables.
These routines must be called from the same thread in which the SQL function is running.
H16272 | The sqlite3_get_auxdata(C,N) interface returns a pointer to metadata associated with the Nth parameter of the SQL function whose context is C, or NULL if there is no metadata associated with that parameter. |
H16274 | The sqlite3_set_auxdata(C,N,P,D) interface assigns a metadata pointer P to the Nth parameter of the SQL function with context C. |
H16276 | SQLite will invoke the destructor D with a single argument which is the metadata pointer P following a call to sqlite3_set_auxdata(C,N,P,D) when SQLite ceases to hold the metadata. |
H16277 | SQLite ceases to hold metadata for an SQL function parameter when the value of that parameter changes. |
H16278 | When sqlite3_set_auxdata(C,N,P,D) is invoked, the destructor is called for any prior metadata associated with the same function context C and parameter N. |
H16279 | SQLite will call destructors for any metadata it is holding in a particular prepared statement S when either sqlite3_reset(S) or sqlite3_finalize(S) is called. |
See also lists of Objects, Constants, and Functions.