インターネット オプションの設定と取得
このトピックでは、 InternetSetOption 関数と InternetQueryOption 関数を使用してインターネット オプションを設定および取得する方法について説明します。
インターネット オプションは、指定した HINTERNET ハンドル、または Microsoft Internet エクスプローラーの現在の設定で設定するか、そこから取得できます。
実装手順
インターネット オプションを設定または取得するには、次の手順を実行します。
インターネット オプションの選択
インターネット オプションは非常に多いので、適切なオプションを選択することが重要です。 多くのインターネット オプションは、WinINet 関数とインターネット エクスプローラーの動作に影響します。
たとえば、次のようなことができます。
- ユーザー名とパスワードを設定して、基本的なサーバーとプロキシの認証を処理します。
- クライアント アプリケーションまたはブラウザーの機能を識別するためにサーバーによって使用されるユーザー エージェント文字列を設定または取得します。
- 指定した HINTERNET ハンドルのハンドルの種類を取得します。
インターネット オプションの詳細と一覧については、「 オプション フラグ」を参照してください。
インターネット エクスプローラー 5 以降では、INTERNET_PER_CONN_OPTION_LISTおよびINTERNET_PER_CONN_OPTION構造を使用して、特定のインターネット接続から一部のオプションを設定または取得できます。 特定のインターネット接続から設定または取得できるオプションの詳細と一覧については、INTERNET_PER_CONN_OPTION構造体の dwOptions メンバーを参照してください。
HINTERNET ハンドルの選択
インターネット オプションの設定または取得に使用される HINTERNET ハンドルによって、操作のスコープが決まります。 このハンドルを介して作成されたすべてのハンドルは、このハンドルに設定されたオプションを継承します。
たとえば、認証付きのプロキシを必要とするクライアント アプリケーションでは、アプリケーションがインターネット リソースにアクセスするたびにプロキシ ユーザー名とパスワードを設定する必要がない可能性があります。 特定の接続のすべての要求が同じプロキシによって処理される場合、接続の種類 HINTERNET ハンドル ( InternetConnect の呼び出しによって作成されたハンドル) にプロキシ ユーザー名とパスワードを設定すると、この HINTERNET ハンドルから派生した呼び出しで同じプロキシ ユーザー名とパスワードを使用できるようになります。 HTTPOpenRequest によって HINTERNET ハンドルが作成されるたびにプロキシ ユーザー名とパスワードを設定するには、余分で不要なオーバーヘッドが必要になります。 アプリケーションが認証を必要とするプロキシを使用する場合は、新しい接続ごとにプロキシ資格情報を設定する必要があることに注意してください。
オプションの設定または取得
使用するインターネット オプションと HINTERNET ハンドルを決定したら、それらのインターネット オプションを取得します。 オプションを設定または取得するには、 InternetQueryOption または InternetSetOption を呼び出します。
HINTERNET ハンドルのスコープ
インターネット オプションの設定または取得に使用される HINTERNET ハンドルによって、オプションが有効なアクションが決まります。
これらのハンドルには、次の 3 つのレベルがあります。
- ルート HINTERNET ハンドル ( InternetOpen の呼び出しによって作成) には、WinINet のこのインスタンスに影響するすべてのインターネット オプションが含まれます。
- サーバーに接続する HINTERNET ハンドル (InternetConnect の呼び出しによって作成)
- HINTERNET ハンドルは、特定のサーバー上のリソースまたはリソースの列挙に関連付けられています。
アプリケーションでは、さまざまな HINTERNET ハンドルに加えて、NULL を使用して、インターネット エクスプローラーおよび WinINet 関数で使用されるインターネット オプションの既定値を設定または取得することもできます。 ハンドルとして NULL を 使用する場合にインターネット オプションを設定すると、現在レジストリに格納されているオプションの既定値が変更されます。 オプションの格納方法の実装は将来変更される可能性があるため、クライアント アプリケーションはレジストリ関数を使用してインターネット オプションの既定値を変更しないでください。
次の表に、 HINTERNET ハンドルの種類と、それらに関連付けられているインターネット オプションのスコープを示します。
| ハンドルの種類 | Scope |
|---|---|
| NULL | インターネット エクスプローラーの既定のオプション設定。 |
| INTERNET_HANDLE_TYPE_CONNECT_FTP | FTP サーバーへのこの接続のオプション設定。 これらのオプションは、ファイルのダウンロードなど、この HINTERNET ハンドルから開始されたすべての操作に影響します。 |
| INTERNET_HANDLE_TYPE_CONNECT_GOPHER | Gopher サーバーへのこの接続のオプション設定。 これらのオプションは、ファイルのダウンロードなど、この HINTERNET ハンドルから開始されたすべての操作に影響します。
メモ： Windows XP および Windows Server 2003 R2 以前のみ。 |
| INTERNET_HANDLE_TYPE_CONNECT_HTTP | HTTP サーバーへのこの接続のオプション設定。 これらのオプションは、ファイルのダウンロードなど、この HINTERNET ハンドルから開始されたすべての操作に影響します。 |
| INTERNET_HANDLE_TYPE_FILE_REQUEST | このファイル要求に関連付けられているオプション設定。 |
| INTERNET_HANDLE_TYPE_FTP_FILE | この FTP リソースのダウンロードに関連付けられているオプション設定。 |
| INTERNET_HANDLE_TYPE_FTP_FILE_HTML | HTML 形式のこの FTP リソースダウンロードに関連付けられているオプション設定。 |
| INTERNET_HANDLE_TYPE_FTP_FIND | FTP サーバー上のファイルのこの検索に関連付けられているオプション設定。 |
| INTERNET_HANDLE_TYPE_FTP_FIND_HTML | HTML 形式の FTP サーバー上のファイルのこの検索に関連付けられているオプション設定。 |
| INTERNET_HANDLE_TYPE_GOPHER_FILE | この Gopher リソースのダウンロードに関連付けられているオプション設定。
メモ： Windows XP および Windows Server 2003 R2 以前のみ。 |
| INTERNET_HANDLE_TYPE_GOPHER_FILE_HTML | HTML 形式のこの Gopher リソースダウンロードに関連付けられているオプション設定。
メモ： Windows XP および Windows Server 2003 R2 以前のみ。 |
| INTERNET_HANDLE_TYPE_GOPHER_FIND | Gopher サーバー上のファイルのこの検索に関連付けられているオプション設定。
メモ： Windows XP および Windows Server 2003 R2 以前のみ。 |
| INTERNET_HANDLE_TYPE_GOPHER_FIND_HTML | HTML 形式の Gopher サーバー上のファイルのこの検索に関連付けられているオプション設定。
メモ： Windows XP および Windows Server 2003 R2 以前のみ。 |
| INTERNET_HANDLE_TYPE_HTTP_REQUEST | この HTTP 要求に関連付けられているオプション設定。 |
| INTERNET_HANDLE_TYPE_INTERNET | WinINet 関数のこのインスタンスに関連付けられているオプション設定。 |
個々のオプションの設定
設定するインターネット オプションと、これらのオプションの影響を受ける範囲を決定した後、インターネット オプションの設定は複雑ではありません。 必要なのは、必要な HINTERNET ハンドル、インターネット オプション フラグ、および設定する情報を含むバッファーを使用して InternetSetOption 関数を呼び出す必要があります。
次の例は、指定した HINTERNET ハンドルでプロキシ ユーザー名とパスワードを設定する方法を示しています。
// strUsername is a string buffer of cchMax characters or less.
// It contains the proxy user name.
size_t cchMax = 80;
size_t cchUserLength, cchPasswordLength;
HRESULT hr = StringCchLength(strUsername, cchMax, &cchUserLength);
if (SUCCEEDED(hr))
{
// hOpen is the HINTERNET handle created by InternetConnect.
InternetSetOption(hConnect, INTERNET_OPTION_PROXY_USERNAME,
strUsername, DWORD(cchUserLength)+1);
}
else
{
// Insert error handling code here.
}
// strPassword is the string buffer that contains the proxy password.
hr = StringCchLength(strPassword, cchMax, &cchPasswordLength);
InternetSetOption(hOpen, INTERNET_OPTION_PROXY_PASSWORD,
strPassword, DWORD(cchPasswordLength)+1);
個々のオプションの取得
インターネット オプションは、 InternetQueryOption 関数を使用して取得できます。 インターネット オプションを取得するには:
インターネット オプション情報を取得するために必要なバッファー サイズを決定します。
バッファー サイズは、バッファーのアドレスに NULL を 使用し、バッファー サイズ 0 を渡すことによって決定できます。
DWORD dwSize; InternetQueryOption(NULL, INTERNET_OPTION_USER_AGENT, NULL, &dwSize);InternetQueryOption によって返される値は、情報を取得するために必要なメモリの量 (バイト単位) です。
バッファーにメモリを割り当てます。
char *lpszData; lpszData = new char[dwSize];データを取得します。
InternetQueryOption( NULL, INTERNET_OPTION_USER_AGENT, lpszData, &dwSize );メモリを解放します。
delete [] lpszData;
完全なサンプル
前のセクションで使用した完全なサンプルを次に示します。 このサンプルでは、既定のユーザー エージェント文字列を取得する方法を示します。
// This call determines the required buffer size.
DWORD dwSize;
InternetQueryOption(NULL, INTERNET_OPTION_USER_AGENT, NULL, &dwSize);
// Allocate the necessary memory.
char *lpszData;
lpszData = new char[dwSize];
// Call InternetQueryOption again with the provided buffer.
InternetQueryOption( NULL,
INTERNET_OPTION_USER_AGENT,
lpszData, &dwSize );
// Insert code here to use the user agent string data.
// Free the allocated memory.
delete [] lpszData;
接続オプションの設定
インターネット エクスプローラー 5 以降では、特定の接続で インターネット オプションを に設定できます。 以前は、すべての接続で同じインターネット オプション設定が共有されていました。 特定の接続のオプションを設定するには:
- INTERNET_PER_CONN_OPTION_LIST構造体を作成します。
- 接続に設定する個々のインターネット オプションにメモリを割り当てます。
- INTERNET_PER_CONN_OPTION構造体のオプションを設定します。
- InternetSetOption を使用してオプションを設定します。
次のコード例は、LAN 接続のプロキシ データを設定する方法を示しています。
BOOL SetConnectionOptions()
{
INTERNET_PER_CONN_OPTION_LIST list;
BOOL bReturn;
DWORD dwBufSize = sizeof(list);
// Fill the list structure.
list.dwSize = sizeof(list);
// NULL == LAN, otherwise connectoid name.
list.pszConnection = NULL;
// Set three options.
list.dwOptionCount = 3;
list.pOptions = new INTERNET_PER_CONN_OPTION[3];
// Ensure that the memory was allocated.
if(NULL == list.pOptions)
{
// Return FALSE if the memory wasn't allocated.
return FALSE;
}
// Set flags.
list.pOptions[0].dwOption = INTERNET_PER_CONN_FLAGS;
list.pOptions[0].Value.dwValue = PROXY_TYPE_DIRECT |
PROXY_TYPE_PROXY;
// Set proxy name.
list.pOptions[1].dwOption = INTERNET_PER_CONN_PROXY_SERVER;
list.pOptions[1].Value.pszValue = TEXT("https://proxy:80");
// Set proxy override.
list.pOptions[2].dwOption = INTERNET_PER_CONN_PROXY_BYPASS;
list.pOptions[2].Value.pszValue = TEXT("local");
// Set the options on the connection.
bReturn = InternetSetOption(NULL,
INTERNET_OPTION_PER_CONNECTION_OPTION, &list, dwBufSize);
// Free the allocated memory.
delete [] list.pOptions;
return bReturn;
}
接続オプションの取得
インターネット エクスプローラー 5 以降では、インターネット オプションを特定の接続から取得できます。 特定の接続からオプションを取得するには:
- INTERNET_PER_CONN_OPTION_LIST構造体を作成します。
- 接続から取得する個々のインターネット オプションのメモリを割り当てます。
- INTERNET_PER_CONN_OPTION構造体を使用してオプションを指定します。
- InternetQueryOption を使用してオプションを取得します。
- オプション データを利用します。
- GlobalFree 関数を使用して、オプション データを保持するために割り当てられたメモリを解放します。
注意
WinINet では、サーバーの実装はサポートされていません。 また、サービスから使用しないでください。 サーバーの実装またはサービスの場合は、 Microsoft Windows HTTP サービス (WinHTTP) を使用します。