libcurl の easy handle に明示的なプロキシを設定する

特定のプロキシ用に libcurl の easy handle を設定し、オプションのエラー、転送の失敗、HTTP ステータスを区別します。

libcurl はプロキシ設定を、転送を実行する easy handle に結び付けます。中間サーバーのアドレスをその handle に設定し、CURLOPT_URL は宛先 URL のままにします。

次の断片は、libcurl が初期化済みで、handle が有効な easy handle であることを前提としています。

char error[CURL_ERROR_SIZE] = {0};
CURLcode result;

result = curl_easy_setopt(handle, CURLOPT_ERRORBUFFER, error);
if (result == CURLE_OK)
    result = curl_easy_setopt(handle, CURLOPT_URL,
                              "https://example.com/");
if (result == CURLE_OK)
    result = curl_easy_setopt(handle, CURLOPT_PROXY,
                              "http://proxy.example:8080");
if (result == CURLE_OK)
    result = curl_easy_perform(handle);

if (result != CURLE_OK)
    fprintf(stderr, "%s\n", error[0] ? error
                                  : curl_easy_strerror(result));

handle が参照している間は、エラーバッファを有効なまま保ちます。スコープを抜ける前に、handle を後始末するか、CURLOPT_ERRORBUFFER ポインターを置き換えるかクリアします。プロキシのホスト名はプレースホルダーです。HTTP プロキシ一覧の未認証の候補が、この公開サイトのテスト用アドレスを提供できます。実際のスキームとポートを使い、HTTPS トンネルを許可するか確認してください。

HTTPS の宛先でも HTTP プロキシを使えます。libcurl がその HTTPS 転送のトンネルを処理します。プロキシオプションの http:// は中間サーバーへの接続を表します。TLS を実際に受け付けるプロキシエンドポイントで、かつそれをサポートする libcurl ビルドの場合に限り、https:// に変更してください。

実際の経路を意図的に決める

明示的なプロキシオプションは、対応するプロキシ環境設定を上書きします。バイパスは別の判断です。継承された no_proxy は依然として宛先を除外できます。この handle が与えられたすべての宛先で選択したプロキシを使う必要があるなら、そのポリシーの一部として CURLOPT_NOPROXY を空文字列に設定します。

逆に、CURLOPT_PROXY を空文字列に設定するとプロキシの使用を明示的に無効にします。NULL に設定すると明示的な割り当てが解除され、環境に基づく動作が再び許可されます。この 2 つの値は異なる目的を持ちます。

Content-Type: text/xml のような宛先固有のヘッダーはプロキシを選択しません。実際のリクエスト本文と宛先 API がそのメディアタイプを必要とする場合にのみ追加してください。

HTTP の結果も読む

curl_easy_perform の成功は、Web サイトが成功の HTTP ステータスを返したことを意味しません。CURLINFO_RESPONSE_CODE を読み、アプリケーションのステータス処理を適用します。プロキシの CONNECT 応答には独自の値 CURLINFO_HTTP_CONNECTCODE があり、トンネルの拒否は Web サイトの応答より前に起こります。

CURLOPT_FAILONERROR は多くの HTTP エラーを失敗として扱えますが、そのドキュメントは認証の例外を明記しています。プロキシの 407 チャレンジは宛先のステータスと分けて扱ってください。

関連記事