This is an interface that must be implemented by consumers.  It allows consumers to add functions that are available to SQL queries and triggers. There are a number of already defined functions provided by SQLite. Objects implementing this interface can be registered with mozIStorageConnection.createFunction().

storage/public/mozIStorageFunction.idlScriptable
Please add a summary to this article.
  Last changed in Gecko 1.9.1.4 (Firefox 3.5.4)

Inherits from: nsISupports

Method overview

nsIVariant onFunctionCall(in mozIStorageValueArray aFunctionArguments);

Methods

onFunctionCall()

The implementation of the function. This is called by the database engine when the function registered with mozIStorageConnection.createFunction() is used in an executing SQL statement or trigger.

Note This callback is executed on the thread that the statement or trigger is executing on. If you use mozIStorageConnection.executeAsync() or, mozIStorageStatement.executeAsync() this callback will run on a different thread from the rest of your code. Likewise, if you execute SQL on a different thread, this callback will be executed on that thread. This callback should be reentrant if any of the above applies to your use of the storage APIs!


nsIVariant onFunctionCall(
  in mozIStorageValueArray aFunctionArguments
);
Parameters
aFunctionArguments
A mozIStorageValueArray holding the arguments passed in to the function.
Return value

An nsIVariant this is the return value of the function.

Sample Code

Both of the following code samples assume that the variable dbConn is an opened mozIStorageConnection.

JavaScript

Starting in Gecko 1.9.1.4 (Firefox 3.0.15), you can directly pass your function into the mozIStorageConnection method mozIStorageConnection, like this:

dbConn.createFunction("square", 1, function(aArguments) {
    let value = aArguments.getInt32(0);
    return value * value;
});

// Run some query that uses the function.
let stmt = dbConn.createStatement("SELECT square(value) FROM some_table");
try {
  while (stmt.executeStep()) {
    // handle the results
  }
}
finally {
  stmt.reset();
}

In earlier versions of Gecko, however, you'll need to actually create an object containing the onFunctionCall method. This still works in Gecko 1.9.1.4 and later, so you may wish to do it this way for compatibility for the time being.

// First, create our object that will represent our function.
var squareFunction = {
  onFunctionCall: function(aArguments) {
    let value = aArguments.getInt32(0);
    return value * value;
  }
};

// Now, register our function with the database connection.
dbConn.createFunction("square", 1, squareFunction);

// Run some query that uses the function.
let stmt = dbConn.createStatement("SELECT square(value) FROM some_table");
try {
  while (stmt.executeStep()) {
    // handle the results
  }
}
finally {
  stmt.reset();
}

C++

// First, create our class that will represent our function.
class squareFunction : public mozIStorageFunction
{
public:
  NS_IMETHOD OnFunctionCall(mozIStorageValueArray *aArguments,
                            nsIVariant **_result)
  {
    PRInt32 value;
    nsresult rv = aArguments->GetInt32(&value);
    NS_ENSURE_SUCCESS(rv, rv);

    nsCOMPtr<nsIWritableVariant> result =
      do_CreateInstance("@mozilla.org/variant;1");
    NS_ENSURE_TRUE(result, NS_ERROR_OUT_OF_MEMORY);

    rv = result->SetAsInt64(value * value);
    NS_ENSURE_SUCCESS(rv, rv);

    NS_ADDREF(*_result = result);
    return NS_OK;
  }
};

// Now, register our function with the database connection.
nsCOMPtr<mozIStorageFunction> func = new squareFunction();
NS_ENSURE_TRUE(func, NS_ERROR_OUT_OF_MEMORY);
nsresult rv = dbConn->CreateFunction(
  NS_LITERAL_CSTRING("square"),
  1,
  func
);
NS_ENSURE_SUCCESS(rv, rv);

// Run some query that uses the function.
nsCOMPtr<mozIStorageStatement> stmt;
rv = dbConn->CreateStatement(NS_LITERAL_CSTRING(
  "SELECT square(value) FROM some_table"),
  getter_AddRefs(stmt)
);
NS_ENSURE_SUCCESS(rv, rv);
PRBool hasMore;
while (NS_SUCCEEDED(stmt->ExecuteStep(&hasMore)) && hasMore) {
  // handle the results
}

See also