Prepares a connection over which a cancel request can be sent. キャンセル要求を送信できる接続を準備します。

PGcancelConn *PQcancelCreate(PGconn *conn);

<xref linkend="libpq-PQcancelCreate"/> creates a <structname>PGcancelConn</structname><indexterm><primary>PGcancelConn</primary></indexterm> object, but it won't instantly start sending a cancel request over this connection. A cancel request can be sent over this connection in a blocking manner using <xref linkend="libpq-PQcancelBlocking"/> and in a non-blocking manner using <xref linkend="libpq-PQcancelStart"/>. The return value can be passed to <xref linkend="libpq-PQcancelStatus"/> to check if the <structname>PGcancelConn</structname> object was created successfully. The <structname>PGcancelConn</structname> object is an opaque structure that is not meant to be accessed directly by the application. This <structname>PGcancelConn</structname> object can be used to cancel the query that's running on the original connection in a thread-safe way. PQcancelCreateはPGcancelConnオブジェクトを作成しますが、この接続を介して直ちにキャンセルリクエストを送信し始めることはありません。 キャンセル要求は、PQcancelBlockingを使用してブロッキング方式で、あるいはPQcancelStartを使用して非ブロッキング方式でこの接続を介して送信できます。 返り値はPQcancelStatusに渡して、PGcancelConnオブジェクトが正常に作成されたかどうかを調べることができます。 PGcancelConnオブジェクトは、アプリケーションが直接アクセスすることを意図していない不透明な構造体です。 このPGcancelConnオブジェクトは、スレッドセーフな方法で元の接続で実行中の問い合わせをキャンセルするために使用できます。

Many connection parameters of the original client will be reused when setting up the connection for the cancel request. Importantly, if the original connection requires encryption of the connection and/or verification of the target host (using <literal>sslmode</literal> or <literal>gssencmode</literal>), then the connection for the cancel request is made with these same requirements. Any connection options that are only used during authentication or after authentication of the client are ignored though, because cancellation requests do not require authentication and the connection is closed right after the cancellation request is submitted. 元のクライアントの多くの接続パラメータは、キャンセル要求の接続を設定するときに再利用されます。 重要な点として、元の接続が接続の暗号化とターゲットホストの検証（sslmodeまたはgssencmodeを使用）を必要とする場合、キャンセル要求の接続はこれらの同じ要件を使用して作成されます。 ただし、クライアントの認証中または認証後にのみ使用される接続オプションは無視されます。取り消し要求では認証は必要なく、接続は取り消し要求が送信された直後に閉じられるためです。

Note that when <function>PQcancelCreate</function> returns a non-null pointer, you must call <xref linkend="libpq-PQcancelFinish"/> when you are finished with it, in order to dispose of the structure and any associated memory blocks. This must be done even if the cancel request failed or was abandoned. PQcancelCreateがNULL以外のポインタを返した場合、構造体と関連するメモリブロックを始末するために、PQcancelFinishを呼び出す必要があります。 これは、キャンセル要求が失敗したか、あるいは放棄された場合でも必要です。

Requests that the server abandons processing of the current command in a blocking manner. サーバがブロック方式で現在のコマンドの処理を中止するように要求します。

int PQcancelBlocking(PGcancelConn *cancelConn);

The request is made over the given <structname>PGcancelConn</structname>, which needs to be created with <xref linkend="libpq-PQcancelCreate"/>. The return value of <xref linkend="libpq-PQcancelBlocking"/> is 1 if the cancel request was successfully dispatched and 0 if not. If it was unsuccessful, the error message can be retrieved using <xref linkend="libpq-PQcancelErrorMessage"/>. この要求は、PQcancelCreateで作成する必要がある指定されたPGcancelを介して行われます。 取り消し要求が正常にディスパッチされた場合、PQcancelBlockingの返却値は1です。 失敗した場合、エラーメッセージは PQcancelErrorMessage を使用して取得できます。

Successful dispatch of the cancellation is no guarantee that the request will have any effect, however. If the cancellation is effective, the command being canceled will terminate early and return an error result. If the cancellation fails (say, because the server was already done processing the command), then there will be no visible result at all. キャンセルの送信が成功しても、要求が有効になるとは限りません。 キャンセルが有効な場合、キャンセルされるコマンドは早期に終了し、エラー結果を返します。 キャンセルが失敗した場合 （サーバがコマンドの処理をすでに完了していた場合など）、目に見える結果はまったくありません。

Requests that the server abandons processing of the current command in a non-blocking manner. サーバが非ブロッキング方式で現在のコマンドの処理を中止するように要求します。

int PQcancelStart(PGcancelConn *cancelConn);

PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn);

The request is made over the given <structname>PGcancelConn</structname>, which needs to be created with <xref linkend="libpq-PQcancelCreate"/>. The return value of <xref linkend="libpq-PQcancelStart"/> is 1 if the cancellation request could be started and 0 if not. If it was unsuccessful, the error message can be retrieved using <xref linkend="libpq-PQcancelErrorMessage"/>. この要求は、PQcancelCreateを使用して作成する必要がある指定されたPGcancelを介して行われます。 取り消し要求が開始できた場合、PQcancelStartの返却値は1です。 開始できなかった場合、エラーメッセージは PQcancelErrorMessage を使用して取得できます。

If <function>PQcancelStart</function> succeeds, the next stage is to poll <application>libpq</application> so that it can proceed with the cancel connection sequence. Use <xref linkend="libpq-PQcancelSocket"/> to obtain the descriptor of the socket underlying the database connection. (Caution: do not assume that the socket remains the same across <function>PQcancelPoll</function> calls.) Loop thus: If <function>PQcancelPoll(cancelConn)</function> last returned <symbol>PGRES_POLLING_READING</symbol>, wait until the socket is ready to read (as indicated by <function>select()</function>, <function>poll()</function>, or similar system function). Then call <function>PQcancelPoll(cancelConn)</function> again. Conversely, if <function>PQcancelPoll(cancelConn)</function> last returned <symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready to write, then call <function>PQcancelPoll(cancelConn)</function> again. On the first iteration, i.e., if you have yet to call <function>PQcancelPoll(cancelConn)</function>, behave as if it last returned <symbol>PGRES_POLLING_WRITING</symbol>. Continue this loop until <function>PQcancelPoll(cancelConn)</function> returns <symbol>PGRES_POLLING_FAILED</symbol>, indicating the connection procedure has failed, or <symbol>PGRES_POLLING_OK</symbol>, indicating cancel request was successfully dispatched. PQcancelStartが成功した場合、次の段階はlibpqをポーリングして、接続解除シーケンスを続行できるようにすることです。 データベース接続の基礎となるソケットの記述子を取得するには、PQcancelSocketを使用します。 （注意: ソケットはPQcancelPoll呼び出しの間は同じままだと仮定しないでください）。 ループを次のように実行します。 PQcancelPoll(cancelConn)が最後にPGRES_POLLING_READINGを返した場合、ソケットが読み込みの準備ができるまで待ちます（select()やpoll()などのシステム関数で指定します）。 その後、再度PQcancelPoll(cancelConn)を呼び出します。 逆に、PQcancelPoll(cancelConn)が最後にPGRES_POLLING_WRITINGを返した場合、ソケットが書き込み可能になるまで待ってから、再度PQcancelPoll(cancelConn)を呼び出します。 最初の反復では、つまりPQcancelPoll(cancelConn)をまだ呼び出していない場合は、最後にPGRES_POLLING_WRITINGを返したかのように振る舞います。 接続手続きが失敗したことを示すPGRES_POLLING_FAILEDを返すか、または、PGRES_POLLING_OKを返して、キャンセル要求が正常にディスパッチされたことを示すまで、このループを続けます。

Successful dispatch of the cancellation is no guarantee that the request will have any effect, however. If the cancellation is effective, the command being canceled will terminate early and return an error result. If the cancellation fails (say, because the server was already done processing the command), then there will be no visible result at all. キャンセルの送信が成功しても、要求が有効になるとは限りません。 キャンセルが有効な場合、キャンセルされるコマンドは早期に終了し、エラー結果を返します。 キャンセルが失敗した場合 （サーバがコマンドの処理をすでに完了していた場合など）、目に見える結果はまったくありません。

At any time during connection, the status of the connection can be checked by calling <xref linkend="libpq-PQcancelStatus"/>. If this call returns <symbol>CONNECTION_BAD</symbol>, then the cancel procedure has failed; if the call returns <function>CONNECTION_OK</function>, then cancel request was successfully dispatched. Both of these states are equally detectable from the return value of <function>PQcancelPoll</function>, described above. Other states might also occur during (and only during) an asynchronous connection procedure. These indicate the current stage of the connection procedure and might be useful to provide feedback to the user for example. These statuses are: 接続中はいつでも、PQcancelStatusを呼び出すことで接続の状態を確認できます。 この呼び出しがCONNECTION_BADを返した場合、キャンセル手続きは失敗です。 この呼び出しがCONNECTION_OKを返した場合、キャンセル要求は正常にディスパッチされました。 これらの状態はどちらも、上記のPQcancelPollの戻り値から等しく検出できます。 他の状態は、非同期接続手順の間（およびその間のみ）に発生することもあります。 これらは、接続手順の現在の段階を示し、例えばユーザにフィードバックを提供するのに有用です。 これらのステータスは次のとおりです。

Note that, although these constants will remain (in order to maintain compatibility), an application should never rely upon these occurring in a particular order, or at all, or on the status always being one of these documented values. An application might do something like this: これらの定数は（互換性を保つため）なくなることはありませんが、アプリケーションは、これらが特定の順で出現したり、本書に書いてある値のどれかに必ずステータス値が該当するということを決して当てにしてはいけません。 アプリケーションは、以下に示すようにするべきです。

switch(PQcancelStatus(conn))
{
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
}

The <literal>connect_timeout</literal> connection parameter is ignored when using <function>PQcancelPoll</function>; it is the application's responsibility to decide whether an excessive amount of time has elapsed. Otherwise, <function>PQcancelStart</function> followed by a <function>PQcancelPoll</function> loop is equivalent to <xref linkend="libpq-PQcancelBlocking"/>. PQcancelPollを使用する場合、connect_timeout接続パラメータは無視されます。 経過時間が長過ぎるかどうかの判定はアプリケーションの責任で行ないます。 そうでない場合、PQcancelStartとそれに続くPQcancelPollループはPQcancelBlockingと同等です。

Returns the status of the cancel connection. キャンセル接続の状態を返します。

ConnStatusType PQcancelStatus(const PGcancelConn *cancelConn);

The status can be one of a number of values. However, only three of these are seen outside of an asynchronous cancel procedure: <literal>CONNECTION_ALLOCATED</literal>, <literal>CONNECTION_OK</literal> and <literal>CONNECTION_BAD</literal>. The initial state of a <function>PGcancelConn</function> that's successfully created using <xref linkend="libpq-PQcancelCreate"/> is <literal>CONNECTION_ALLOCATED</literal>. A cancel request that was successfully dispatched has the status <literal>CONNECTION_OK</literal>. A failed cancel attempt is signaled by status <literal>CONNECTION_BAD</literal>. An OK status will remain so until <xref linkend="libpq-PQcancelFinish"/> or <xref linkend="libpq-PQcancelReset"/> is called. ステータスは、いくつかの値のいずれかになります。 しかし、非同期キャンセル手続きの外で見られるのは、CONNECTION_ALLOCATED、CONNECTION_OK、CONNECTION_BADの3つだけです。 PQcancelCreateを使用して正常に作成されたPGcancelConnの初期状態はCONNECTION_ALLOCATEDです。 正常にディスパッチされたキャンセル要求はCONNECTION_OKの状態になります。 キャンセルが失敗した場合、状態CONNECTION_BADが通知されます。 PQcancelFinishまたはPQcancelResetが呼び出されるまで、OK状態はそのまま残ります。

See the entry for <xref linkend="libpq-PQcancelStart"/> with regards to other status codes that might be returned. 返される可能性がある他の状態コードについてはPQcancelStartの項目を参照してください。

Successful dispatch of the cancellation is no guarantee that the request will have any effect, however. If the cancellation is effective, the command being canceled will terminate early and return an error result. If the cancellation fails (say, because the server was already done processing the command), then there will be no visible result at all. キャンセルの送信が成功しても、要求が有効になるとは限りません。 キャンセルが有効な場合、キャンセルされるコマンドは早期に終了し、エラー結果を返します。 キャンセルが失敗した場合 （サーバがコマンドの処理をすでに完了していた場合など）、目に見える結果はまったくありません。

Obtains the file descriptor number of the cancel connection socket to the server. サーバへのキャンセル接続ソケットのファイル記述子番号を取得する。

int PQcancelSocket(const PGcancelConn *cancelConn);

A valid descriptor will be greater than or equal to 0; a result of -1 indicates that no server connection is currently open. This might change as a result of calling any of the functions in this section on the <structname>PGcancelConn</structname> (except for <xref linkend="libpq-PQcancelErrorMessage"/> and <function>PQcancelSocket</function> itself). 有効なディスクリプタは0以上です。 -1 の結果は、現在オープンしているサーバ接続がないことを示します。 このセクションの関数をPGcancelConn（ PQcancelErrorMessage とPQcancelSocket自身を除く）で呼び出すと、この値が変わる可能性があります。

Returns the error message most recently generated by an operation on the cancel connection. 接続解除操作で最後に生成されたエラーメッセージを返します。

char *PQcancelErrorMessage(const PGcancelConn *cancelconn);

Nearly all <application>libpq</application> functions that take a <structname>PGcancelConn</structname> will set a message for <xref linkend="libpq-PQcancelErrorMessage"/> if they fail. Note that by <application>libpq</application> convention, a nonempty <xref linkend="libpq-PQcancelErrorMessage"/> result can consist of multiple lines, and will include a trailing newline. The caller should not free the result directly. It will be freed when the associated <structname>PGcancelConn</structname> handle is passed to <xref linkend="libpq-PQcancelFinish"/>. The result string should not be expected to remain the same across operations on the <literal>PGcancelConn</literal> structure. PGcancelConnを取得するlibpq関数のほとんどは、失敗した場合に PQcancelErrorMessage にメッセージを設定します。 libpqの規則では、空でない PQcancelErrorMessage 結果は複数行からなる可能性があり、最後に改行を含むことに注意してください。 呼び出し元は、結果を直接解放しないでください。 関連するPGcancelConnハンドルがPQcancelFinishに渡されると解放されます。 結果の文字列はPGcancelConn構造体に対する操作を通じて同じままになることは期待されません。

Closes the cancel connection (if it did not finish sending the cancel request yet). Also frees memory used by the <structname>PGcancelConn</structname> object. キャンセル接続を閉じます（キャンセル要求の送信がまだ完了していない場合）。 また、PGcancelConnオブジェクトが使用するメモリを解放します。

void PQcancelFinish(PGcancelConn *cancelConn);

Note that even if the cancel attempt fails (as indicated by <xref linkend="libpq-PQcancelStatus"/>), the application should call <xref linkend="libpq-PQcancelFinish"/> to free the memory used by the <structname>PGcancelConn</structname> object. The <structname>PGcancelConn</structname> pointer must not be used again after <xref linkend="libpq-PQcancelFinish"/> has been called. 取り消しの試みが失敗した場合（PQcancelStatusで示されるように）でも、アプリケーションはPQcancelFinishを呼び出してPGcancelConnオブジェクトが使用したメモリを解放するようにしてください。 PGcancelConnポインタはPQcancelFinishが呼び出された後は再度使用してはなりません。

Resets the <symbol>PGcancelConn</symbol> so it can be reused for a new cancel connection. 新しいキャンセル接続で再利用できるようにPGcancelConnをリセットします。

void PQcancelReset(PGcancelConn *cancelConn);

If the <symbol>PGcancelConn</symbol> is currently used to send a cancel request, then this connection is closed. It will then prepare the <symbol>PGcancelConn</symbol> object such that it can be used to send a new cancel request. PGcancelConnが現在キャンセル要求を送信するために使用されている場合、この接続は閉じられます。 次に、新しいキャンセル要求を送信するために使用できるようにPGcancelConnオブジェクトを準備します。

This can be used to create one <structname>PGcancelConn</structname> for a <structname>PGconn</structname> and reuse it multiple times throughout the lifetime of the original <structname>PGconn</structname>. これはPGconnに対して1つのPGcancelConnを作成し、元のPGconnの存続期間中に何度も再利用することができます。

Creates a data structure containing the information needed to cancel a command using <xref linkend="libpq-PQcancel"/>. PQcancelを使用してコマンドをキャンセルするために必要な情報を含むデータ構造体を作成します。

PGcancel *PQgetCancel(PGconn *conn);

<xref linkend="libpq-PQgetCancel"/> creates a <structname>PGcancel</structname><indexterm><primary>PGcancel</primary></indexterm> object given a <structname>PGconn</structname> connection object. It will return <symbol>NULL</symbol> if the given <parameter>conn</parameter> is <symbol>NULL</symbol> or an invalid connection. The <structname>PGcancel</structname> object is an opaque structure that is not meant to be accessed directly by the application; it can only be passed to <xref linkend="libpq-PQcancel"/> or <xref linkend="libpq-PQfreeCancel"/>. PQgetCancelはPGconn接続オブジェクトを与えられたPGcancelオブジェクトを作成します。 指定されたconnがNULLか、または無効な接続である場合、NULLを返します。 PGcancelオブジェクトは不透明な構造体で、アプリケーションが直接アクセスするためのものではありません。これはPQcancelまたはPQfreeCancelに渡すことができるだけです。

Frees a data structure created by <xref linkend="libpq-PQgetCancel"/>. PQgetCancelで作成されたデータ構造を解放します。

void PQfreeCancel(PGcancel *cancel);

<xref linkend="libpq-PQfreeCancel"/> frees a data object previously created by <xref linkend="libpq-PQgetCancel"/>. PQfreeCancelは事前にPQgetCancelで作成されたデータオブジェクトを解放します。

<xref linkend="libpq-PQcancel"/> is a deprecated and insecure variant of <xref linkend="libpq-PQcancelBlocking"/>, but one that can be used safely from within a signal handler. PQcancelは、PQcancelBlockingの非推奨で安全でない変種ですが、シグナルハンドラ内から安全に使用できます。

int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);

<xref linkend="libpq-PQcancel"/> only exists because of backwards compatibility reasons. <xref linkend="libpq-PQcancelBlocking"/> should be used instead. The only benefit that <xref linkend="libpq-PQcancel"/> has is that it can be safely invoked from a signal handler, if the <parameter>errbuf</parameter> is a local variable in the signal handler. However, this is generally not considered a big enough benefit to be worth the security issues that this function has. PQcancelが存在するのは、下位互換性のためだけです。 代わりにPQcancelBlockingを使用してください。 PQcancelの唯一の利点は、errbufがシグナルハンドラ内のローカル変数である場合に、シグナルハンドラから安全に呼び出すことができることです。 しかし、一般的には、この関数が持つセキュリティ問題に見合うほど大きな利点とは考えられていません。

The <structname>PGcancel</structname> object is read-only as far as <xref linkend="libpq-PQcancel"/> is concerned, so it can also be invoked from a thread that is separate from the one manipulating the <structname>PGconn</structname> object. PGcancelオブジェクトはPQcancelに関しては読み取り専用であるため、PGconnオブジェクトを操作するスレッドとは別のスレッドからも呼び出すことができます。

The return value of <xref linkend="libpq-PQcancel"/> is 1 if the cancel request was successfully dispatched and 0 if not. If not, <parameter>errbuf</parameter> is filled with an explanatory error message. <parameter>errbuf</parameter> must be a char array of size <parameter>errbufsize</parameter> (the recommended size is 256 bytes). 取り消し要求が正常にディスパッチされた場合、PQcancelの戻り値は1で、そうでなければ0です。 ディスパッチされなかった場合、errbufに説明的なエラーメッセージが入ります。 errbufはerrbufsizeのサイズ（推奨サイズは256バイト）の文字配列でなければなりません。

<xref linkend="libpq-PQrequestCancel"/> is a deprecated and insecure variant of <xref linkend="libpq-PQcancelBlocking"/>. PQrequestCancelは、PQcancelBlockingの非推奨で安全でない変種です。

int PQrequestCancel(PGconn *conn);

<xref linkend="libpq-PQrequestCancel"/> only exists because of backwards compatibility reasons. <xref linkend="libpq-PQcancelBlocking"/> should be used instead. There is no benefit to using <xref linkend="libpq-PQrequestCancel"/> over <xref linkend="libpq-PQcancelBlocking"/>. PQrequestCancelは下位互換性のために存在します。 代わりにPQcancelBlockingを使用してください。 PQrequestCancelをPQcancelBlockingよりも使用する利益はありません。

Requests that the server abandon processing of the current command. It operates directly on the <structname>PGconn</structname> object, and in case of failure stores the error message in the <structname>PGconn</structname> object (whence it can be retrieved by <xref linkend="libpq-PQerrorMessage"/>). Although the functionality is the same, this approach is not safe within multiple-thread programs or signal handlers, since it is possible that overwriting the <structname>PGconn</structname>'s error message will mess up the operation currently in progress on the connection. サーバに現在のコマンドの廃棄処理を要求します。 これはPGconnオブジェクトを直接扱い、また、失敗した場合エラーメッセージはPGconnオブジェクト内に収納されます。 ( PQerrorMessage により取り出すことができます。) 機能的には同一ですが、この方法は複数スレッドプログラムやシグナルハンドラでは安全ではありません。PGconnのエラーメッセージが上書きされることにより、その接続で現在進行中の操作を台無しにする可能性があるからです。