mozilla

Revision 127900 of mozIStorageAggregateFunction

  • Revision slug: MozIStorageAggregateFunction
  • Revision title: mozIStorageAggregateFunction
  • Revision id: 127900
  • Created:
  • Creator: sdwilsh
  • Is current revision? No
  • Comment 24 words added, 35 words removed

Revision Content

This is an interface that must be implemented by consumers.  It allows consumers to add aggregate functions that are available to SQL queries and triggers.  An aggregate function is a function that returns one value from a series of values.  There are a number of already defined aggregate functions provided by SQLite.

{{ InterfaceStatus("mozIStorageAggregateFunction", "storage/public/mozIStorageAggregateFunction.idl", "unfrozen", "Mozilla 1.9", "yes") }}

Inherits from: {{ interface("nsISupports") }}

Method overview

void onStep(in {{ interface("mozIStorageValueArray") }} aFunctionArguments);
{{ interface("nsIVariant") }} onFinal();

Methods

onStep()

This is called for each row of results returned by the query.  The implementation should store or perform some work to prepare to return a value.

{{ Storage:threadsafety_callback_warning() }}

void onStep(
  in mozIStorageValueArray aFunctionArguments
);
Parameters
aFunctionArguments
A {{ interface("mozIStorageValueArray") }} holding the arguments passed in to the function.

onFinal()

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

{{ Storage:threadsafety_callback_warning() }}

nsIVariant onFunctionCall(in mozIStorageValueArray aFunctionArguments)
Parameters
aFunctionArguments
A {{ interface("mozIStorageValueArray") }} holding the arguments passed in to the function.
Return value

An {{ interface("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 {{ interface("mozIStorageConnection") }}.

JavaScript

// 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
}

 

Revision Source

<p>This is an interface that must be implemented by consumers.  It allows consumers to add aggregate functions that are available to SQL queries and triggers.  An aggregate function is a function that returns one value from a series of values.  There are a <a class="external" href="http://www.sqlite.org/lang_aggfunc.html" title="http://www.sqlite.org/lang_corefunc.html">number of already defined aggregate functions provided by SQLite</a>.</p>
<p>{{ InterfaceStatus("mozIStorageAggregateFunction", "storage/public/mozIStorageAggregateFunction.idl", "unfrozen", "Mozilla 1.9", "yes") }}</p>
<p>Inherits from: {{ interface("nsISupports") }}</p>
<h2 name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>void <a href="#onStep()">onStep</a>(in {{ interface("mozIStorageValueArray") }} aFunctionArguments);</code></td> </tr> <tr> <td><code>{{ interface("nsIVariant") }} <a href="#onFinal()">onFinal</a>();</code></td> </tr> </tbody>
</table>
<h2 name="Methods">Methods</h2>
<h3 name="onStep()">onStep()</h3>
<p>This is called for each row of results returned by the query.  The implementation should store or perform some work to prepare to return a value.</p>
<p>{{ Storage:threadsafety_callback_warning() }}</p>
<pre class="eval">void onStep(
  in mozIStorageValueArray aFunctionArguments
);</pre>
<h6 name="Parameters">Parameters</h6>
<dl><dt><code>aFunctionArguments</code></dt><dd>A {{ interface("mozIStorageValueArray") }} holding the arguments passed in to the function.</dd></dl><h3 name="onFinal()">onFinal()</h3>
<p>The implementation of the function.  This is called by the database engine when the function registered with {{ ifmethod("mozIStorageConnection", "createFunction") }} is used in an executing SQL statement or trigger.</p>
<p>{{ Storage:threadsafety_callback_warning() }}</p>
<pre class="eval">nsIVariant onFunctionCall(in mozIStorageValueArray aFunctionArguments)</pre>
<h6 name="Parameters">Parameters</h6>
<dl><dt><code>aFunctionArguments</code></dt><dd>A {{ interface("mozIStorageValueArray") }} holding the arguments passed in to the function.</dd></dl>
<h6 name="Return">Return value</h6>
<p>An {{ interface("nsIVariant") }} this is the return value of the function.</p>
<h2>Sample Code</h2>
<p>Both of the following code samples assume that the variable dbConn is an opened {{ interface("mozIStorageConnection") }}.</p>
<h3>JavaScript</h3>
<pre class="brush: js">// 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();
}
</pre>
<h3>C++</h3>
<pre class="brush: cpp">// 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-&gt;GetInt32(&amp;value);
    NS_ENSURE_SUCCESS(rv, rv);
    
    nsCOMPtr&lt;nsIWritableVariant&gt; result =
      do_CreateInstance("@mozilla.org/variant;1");
    NS_ENSURE_TRUE(result, NS_ERROR_OUT_OF_MEMORY);
    
    rv = result-&gt;SetAsInt64(value * value);
    NS_ENSURE_SUCCESS(rv, rv);

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

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

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