<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="sqlite3.setauthorizer" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>SQLite3::setAuthorizer</refname>

<refpurpose>SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis role="SQLite3">

<modifier>public</modifier> <type>bool</type><methodname>SQLite3::setAuthorizer</methodname>

<methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>

</methodsynopsis>

<para>

SQLite に対して毎回アクション(読み取り、削除、更新など)

が実行される度に呼び出されるコールバックを設定します。

これは信頼できないソースがSQL文を準備する時に、

自分たちが許可していないデータにアクセスさせないとか、

データベースに損害を与える不正なSQL文を実行させないといった用途に使います。

たとえば、アプリケーションはデータベースの評価の際は

任意のSQL文の実行を許可しています。しかし、

データベースに対する変更は許可したくありません。

ユーザーが入力したSQL文が準備される間に、

authorizer が割って入り、SELECT 文以外のSQL文を許可しないようにできます。

</para>

<para>

authorizer コールバックは、

SQLite が文を準備するたびに複数回呼ばれる可能性があります。

<literal>SELECT</literal> や

<literal>UPDATE</literal> 文は

個別のカラムが読み取られたり、更新されたりするたびに

authorizer を呼び出します。

</para>

<para>

authorizer は引数を5つまで指定して呼び出すことが出来ます。

最初の引数は常に与えられます。

これは <literal>SQLite3</literal> の定数に一致する

<type>int</type> の値(アクションコード) です。

それ以外の引数は、アクションによっては与えられないことがあります。

以下の表が、アクションに応じた2番目と3番目の引数に関する説明を記しています:

<table>

<title>アクションコードと引数の一覧</title>

<tgroup cols="3">

<thead>

<row>

<entry>アクション</entry>

<entry>第2引数</entry>

<entry>第3引数</entry>

</row>

</thead>

<tbody>

<row><entry><constant>sqlite3::create_index</constant></entry><entry>インデックス名</entry><entry>テーブル名</entry></row>

<row><entry><constant>sqlite3::create_table</constant></entry><entry>テーブル名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::create_temp_index</constant></entry><entry>インデックス名</entry><entry>テーブル名</entry></row>

<row><entry><constant>sqlite3::create_temp_table</constant></entry><entry>テーブル名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::create_temp_trigger</constant></entry><entry>トリガ名</entry><entry>テーブル名</entry></row>

<row><entry><constant>sqlite3::create_temp_view</constant></entry><entry>view名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::create_trigger</constant></entry><entry>トリガ名</entry><entry>テーブル名</entry></row>

<row><entry><constant>sqlite3::create_view</constant></entry><entry>view名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::delete</constant></entry><entry>テーブル名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::drop_index</constant></entry><entry>インデックス名</entry><entry>テーブル名</entry></row>

<row><entry><constant>sqlite3::drop_table</constant></entry><entry>テーブル名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::drop_temp_index</constant></entry><entry>インデックス名</entry><entry>テーブル名</entry></row>

<row><entry><constant>sqlite3::drop_temp_table</constant></entry><entry>テーブル名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::drop_temp_trigger</constant></entry><entry>トリガ名</entry><entry>テーブル名</entry></row>

<row><entry><constant>sqlite3::drop_temp_view</constant></entry><entry>view名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::drop_trigger</constant></entry><entry>トリガ名</entry><entry>テーブル名</entry></row>

<row><entry><constant>sqlite3::drop_view</constant></entry><entry>view名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::insert</constant></entry><entry>テーブル名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::pragma</constant></entry><entry>プラグマの名前</entry><entry>プラグマに渡す最初の引数。もしくは &null;</entry></row>

<row><entry><constant>sqlite3::read</constant></entry><entry>テーブル名</entry><entry>カラム名</entry></row>

<row><entry><constant>sqlite3::select</constant></entry><entry>&null;</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::transaction</constant></entry><entry>操作</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::update</constant></entry><entry>テーブル名</entry><entry>カラム名</entry></row>

<row><entry><constant>sqlite3::attach</constant></entry><entry>ファイル名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::detach</constant></entry><entry>データベース名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::alter_table</constant></entry><entry>データベース名</entry><entry>テーブル名</entry></row>

<row><entry><constant>sqlite3::reindex</constant></entry><entry>インデックス名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::analyze</constant></entry><entry>テーブル名</entry><entry>&null;</entry></row>

<row><entry><constant>sqlite3::create_vtable</constant></entry><entry>テーブル名</entry><entry>モジュール名</entry></row>

<row><entry><constant>sqlite3::drop_vtable</constant></entry><entry>テーブル名</entry><entry>モジュール名</entry></row>

<row><entry><constant>sqlite3::function</constant></entry><entry>&null;</entry><entry>ファンクション名</entry></row>

<row><entry><constant>sqlite3::savepoint</constant></entry><entry>操作</entry><entry>セーブポイントの名前</entry></row>

<row><entry><constant>sqlite3::recursive</constant></entry><entry>&null;</entry><entry>&null;</entry></row>

</tbody>

</tgroup>

</table>

</para>

<para>

4番目の引数は、適切な場合にだけ指定する(<literal>"main"</literal>,

<literal>"temp"</literal>, などの) データベースの名前です。

</para>

<para>

authorizer コールバックに与える5番目の引数は、

トップレベルのSQLコードから直接アクセスが行われる場合に、

アクセスを試みる責任を持つ一番奥の view やトリガの名前です。

</para>

<para>

コールバックが <constant>SQLite3::OK</constant>

を返すと、操作のリクエストが承認されたことになります。

コールバックが <constant>SQLite3::DENY</constant>

を返すと、authorizer を動かした呼び出しは失敗し、

なぜアクセスが失敗したのかを説明するメッセージが残ります。

</para>

<para>

アクションが <constant>SQLite3::READ</constant> で、

さらにコールバックが

<constant>SQLite3::IGNORE</constant> を返す場合、

準備されたSQL文は、

<constant>SQLite3::OK</constant> が返された場合に読まれていたテーブルのカラムを &null; で置き換えるように文を組み立てます。

<constant>SQLite3::IGNORE</constant> は、

信頼できないユーザーのアクセスが、

テーブルの個別のカラムへのアクセスを拒否する場合に使うことが出来ます。

</para>

<para>

テーブルを <literal>SELECT</literal> 文で参照しているが、

そのテーブルからカラムの値を抜き出さない場合

(たとえば、<literal>"SELECT count(*) FROM table"</literal>

のようなクエリの場合)、

<constant>SQLite3::READ</constant> の authorizer コールバックは

カラムの情報が空文字列になった状態で一度だけ呼び出されます。

</para>

<para>

アクションコードが <constant>SQLite3::DELETE</constant> で、

さらにコールバックが

<constant>SQLite3::IGNORE</constant> を返した場合、

DELETE の操作は継続しますが、truncate による最適化は無効になります。

この場合、全ての行は個別に削除されます。

</para>

<para>

接続ひとつにつき、authorizer ひとつだけがデータベースに存在できます。

<methodname>SQLite3::setAuthorizer</methodname> が呼び出されるたびに、

以前の呼び出しは上書きされます。

&null; をコールバックに指定することで、

authorizer を無効に出来ます。authorizer はデフォルトで無効になっています。

</para>

<para>

authorizer コールバックは、コールバックを呼び出すデータベース接続に対していかなる変更もしてはいけません。

</para>

<para>

authorizer はSQL文が準備される時にだけ呼び出されることに注意して下さい。

実行時ではありません。

</para>

<para>

さらなる詳細は

<link xlink:href="&url.sqlite;c3ref/set_authorizer.html">SQLite3 のドキュメント</link> を参照ください。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>callback</parameter></term>

<listitem>

<para>

呼び出される <type>callable</type>。

</para>

<para>

&null; が渡されると、

現在の authorizer のコールバックが無効になります。

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

&return.success;

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

このメソッドは例外をスローしません。

しかし、いったん authorizer が有効になり、不正な値を返すと、

SQL文の準備がエラー

(または例外。

<methodname>SQLite3::enableExceptions</methodname> の使い方によります)

を発生させるようになります。

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<example>

<title><methodname>SQLite3::setAuthorizer</methodname> の例</title>

<para>

この例は、読み取りだけを許可します。

さらに、<literal>users</literal> テーブルのいくつかのカラムだけを返します。

他のカラムは &null; で置き換えられます。

</para>

<programlisting role="php">

</programlisting>

&example.outputs;

<screen>

</screen>

</example>

</refsect1>

</refentry>