## pdo_dbh_t の定義

明示的に述べられている場合を除き、ドライバからはすべてのフィールドが 読み込み専用となります。

# pdo_dbh_t

    /* データベースへの接続を表す */
    struct _pdo_dbh_t {
        /* ドライバ固有のメソッド */
        struct pdo_dbh_methods *methods;

*

    /* ドライバ固有のデータ */
        void *driver_data;

**

    /* 認証データ */
        char *username, *password;

***

    /* true の場合は、このハンドルが指すデータはすべて
         * 持続的に割り当てられる */
        unsigned is_persistent:1;

****

    /* true の場合は、ステートメントを実行するたびに COMMIT を行うかのように
         * 動作する。それ以外の場合は COMMIT を手動で実行しなければならない
         * */
        unsigned auto_commit:1;

*****

    /* true の場合は、返されるカラムのためのメモリを明示的に確保することが
         * 必要となる */
        unsigned alloc_own_columns:1;

******

    /* true の場合は、commit あるいは rollBack をコールすることができる */
        unsigned in_txn:1;

        /* しかるべきクォート処理をした後での 1 文字の長さの最大値 */
        unsigned max_escaped_char_length:3;

*******

    /* このハンドルをオープンする際に使用されるデータソース文字列 */
        const char *data_source;

********

    unsigned long data_source_len;

        /* グローバルエラーコード */
        pdo_error_type error_code;

*********

    enum pdo_case_conversion native_case

**********

    , desired_case;
    };

* | ドライバは、SKEL_handle_factory() の中で これを設定しなければなりません。
** | この項目はドライバが使用します。想定される使用法は、データベースとの 接続を保つために必要なインスタンスデータへのポインタを (SKEL_handle_factory() 内で) 格納することです。
*** | PDO のコンストラクタに渡すユーザー名およびパスワードです。 データベースとの接続を初期化する際に、ドライバはこの値を 使用しなければなりません。
**** | これが 1 に設定されている場合、dbh が参照しているすべてのデータや ドライバが割り当てた構造体はすべて持続的に 確保しなければなりません。これを実現するのは 簡単です。通常の emalloc() の代わりに pemalloc() を使用し、最後のパラメータとして このフラグの値を渡せばよいのです。メモリを適切に使用するように しないと深刻な問題を引き起こし、結果として (いちばんましな場合でも) プログラムをクラッシュさせ、最悪の場合には攻撃者が悪用可能な状態に なってしまうでしょう。 どのような理由であれ、もしドライバを持続的に実行することができないのなら SKEL_handle_factory() の中で必ず このフラグをチェックし、適切なエラーを発生させるようにしましょう。
***** | この値は、関数 SKEL_handle_doer() および SKEL_stmt_execute() の中でチェックする必要が あります。これが true の場合はクエリを実行するたびに commit しなければなりません。ほとんどのデータベースは自動コミットモードを 提供しており、これを自動的に処理してくれます。
****** | データベースクライアントライブラリの API が、呼び出し元が提供する バッファに取得したデータを格納するようになっている場合、 SKEL_handle_factory() でこのフラグを 1 に 設定する必要があります。設定しておくと、PDO は それ以外の場合より早く SKEL_stmt_describer() をコールします。このことによりバッファの大きさを知ることができ、 データベースクライアントライブラリに対して適切なコールが できるようになります。 もしデータベースクライアントライブラリの API の実装が、 ライブラリ自身の内部バッファに格納したデータへのポインタを返す 実装になっており、フェッチコールの後でそれをコピーして使用すると いうことならば、この値は 0 のままにしておきます。
******* | もしドライバがネイティブのプリペアドステートメントをサポートしない (`supports_placeholders` が `PDO_PLACEHOLDER_NONE` となっている) 場合、SKEL_handle_quoter() 関数によって 1 文字の長さが最大どれだけになるかをこの値に設定する必要があります。 この値は、PDO がステートメントを実行する際に必要なバッファの領域を 計算するために使用されます。
******** | これは、PDO のコンストラクタに渡す DSN の値を保持します。 もし何らかの理由でドライバが DSN を変更する必要がある場合は、 SKEL_handle_factory() の中で更新しなければ なりません。このメンバを変更することは避けるべきです。 もし変更する際には、`data_source_len` が正しい値であることを確かめる必要があります。
********* | ドライバのメソッドのコール中にエラーが発生した場合は、エラーの内容に 該当する SQLSTATE コードをこのメンバに設定し、エラーを返さなければ なりません。この HOW-TO では、エラーが検出された際には SKEL_handle_error() をコールし、そこでエラーコードを 設定するという手法を推奨します。
********** | この値は SKEL_handle_factory() の中で 設定しなければなりません。この値は、結果セット内のカラム名を データベースがどのように返すかを表します。クエリで指定された とおりに大文字小文字を使用する場合は、この値を `PDO_CASE_NATURAL` (デフォルト値です) に設定します。カラム名をつねに大文字で返す場合は、この値を `PDO_CASE_UPPER` に設定します。 カラム名をつねに小文字で返す場合は、この値を `PDO_CASE_LOWER` に設定します。 ここで設定した値は、ユーザーが `PDO_ATTR_CASE` 属性を設定した場合に PDO が大文字小文字変換をすべきかどうかを 決定するために使用されます。