啟用網際網路功能

發行項
06/13/2023

使用 WinINet 函式之前，應用程式應該嘗試使用 InternetAttemptConnect 函式來連線到網際網路。此函式會呼叫撥號對話方塊來起始與網際網路的連線，或檢查連線是否已存在。如果此函式失敗，應用程式可以進入離線模式，以便存取先前連線到網際網路期間快取的資訊。

使用 InternetCheckConnection 函式來檢查網際網路的連線。它會嘗試 Ping 傳遞至函式的 URL 所指定的伺服器。如果已設定FLAG_ICC_FORCE_CONNECTION旗標，且 URL 為 Null，函式會檢查伺服器資料庫中是否有最接近伺服器的專案。如果存在，函式會 Ping 該伺服器。

接下來，使用 InternetOpen 函式來建立用戶端應用程式正在使用的網際網路連線特性。 InternetOpen會建立用來建立HTTP ftp會話的根HINTERNET控制碼。 InternetOpen 不會測試與網際網路的連線，以確認傳遞至函式的特性是否正確。

使用 InternetConnect 函式來建立特定的會話。 InternetConnect 會使用傳遞給它的引數來初始化指定網站的會話，並建立一個與根控制碼關閉的 分支的 HINTERNET 控制碼。 InternetConnect 不會嘗試存取或建立與指定網站的連線，但 FTP 會話除外。 FtpFindFirstFile、 FtpOpenFile和 HttpOpenRequest 函式會使用 InternetConnect 所建立的控制碼來建立與指定網站的連線。

使用 InternetOpen

若要啟用網際網路的連線，必須使用InternetOpen建立根HINTERNET控制碼。使用者代理程式的相關資訊 (呼叫網際網路函式的應用程式) 、網際網路的存取類型、Proxy 名稱、略過 Proxy 的主機和位址，以及將行為傳遞至 InternetOpen。

設定使用者代理程式

呼叫的應用程式應該會提供字串，其中包含存取網際網路的應用程式名稱或實體，以存取InternetOpen的lpszAgent參數。此字串會當做 HTTP 通訊協定中的使用者代理程式使用。例如，Microsoft Internet Explorer 使用「Microsoft Internet Explorer」。

設定存取類型

InternetOpen 支援三種存取類型：

如果應用程式執行所在的系統使用直接連線到網際網路，請使用INTERNET_OPEN_TYPE_DIRECT。不會使用InternetOpen的lpszProxyName和lpszProxyBypass參數，而且應該設定為Null。
如果應用程式執行所在的系統使用一或多個 Proxy 伺服器來存取網際網路，請使用INTERNET_OPEN_TYPE_PROXY。 InternetOpen 會使用 lpszProxyName 所指示的 Proxy 伺服器，並略過 lpszProxyBypass所指定之任何主機名稱或 IP 位址的 Proxy。
使用INTERNET_OPEN_TYPE_PRECONFIG指示您的應用程式從登錄擷取組態。這通常是最佳選擇，因為包含網頁瀏覽器的大部分應用程式都會使用此選項。

INTERNET_OPEN_TYPE_PRECONFIG查看 ProxyEnable、 ProxyServer和 ProxyOverride 的登錄值。這些值位於「HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings」。

如果 ProxyEnable 為零，應用程式會使用 INTERNET_OPEN_TYPE_DIRECT。否則，應用程式會使用 INTERNET_OPEN_TYPE_PROXY，並使用 ProxyServer 和 ProxyOverride 資訊。

只有在安裝 Internet Explorer 時，WinINet 函式才支援 SOCKS 類型 Proxy。 Internet Explorer 的安裝包含支援 SOCKS Proxy 所需的 Wsock32n.dll 檔案。 Wsock32n.dll 無法轉散發。

列出 Proxy 伺服器

WinINet 可辨識兩種類型的 Proxy：CERN 類型 Proxy (HTTP 僅) 和 TIS FTP Proxy (FTP 僅) 。如果已安裝 Internet Explorer，WinINet 也支援 SOCKS 類型 Proxy。 InternetConnect 預設會假設指定的 Proxy 是 CERN Proxy。如果存取類型設定為 INTERNET_OPEN_TYPE_DIRECT 或 INTERNET_OPEN_TYPE_PRECONFIG，則 InternetOpen的lpszProxyName參數應該設定為Null。否則，傳遞至 lpszProxyName 的值必須包含空格分隔字串中的 Proxy。 Proxy 清單可以包含用來存取 Proxy 的埠號碼。

若要列出特定通訊協定的 Proxy，字串必須遵循「」 < protocol protocol ><> ：// < proxy_name > 「格式。有效的通訊協定為 HTTP、HTTPS 和 FTP。例如，若要列出 FTP Proxy，有效的字串會是「」ftp=ftp：//ftp_proxy_name：21「，其中 ftp_proxy_name 是 FTP Proxy 的名稱，而 21 是必須用來存取 Proxy 的埠號碼。如果 Proxy 使用該通訊協定的預設埠號碼，則可以省略埠號碼。如果 Proxy 名稱本身列出，則會作為未指定特定 Proxy 之任何通訊協定的預設 Proxy。例如，「」HTTP= https://http_proxy other「」會針對任何 HTTP 作業使用HTTP_proxy，而所有其他通訊協定則會使用其他通訊協定。

根據預設，函式會假設 lpszProxyName 指定的 Proxy 是 CERN Proxy。應用程式可以指定多個 Proxy，包括不同通訊協定的不同 Proxy。例如，如果您指定「」ftp=ftp：//ftp-gw HTTP= https://jericho:99 proxy「」，則 FTP 要求是透過 ftp-gw Proxy 進行，它會在埠 21 接聽，而 HTTP 要求是透過名為 jericho 的 CERN Proxy 進行，它會接聽埠 99。否則，HTTP 要求會透過名為 proxy 的 CERN Proxy 進行，其會接聽埠 80。請注意，如果應用程式只使用 FTP，則不需要指定「」ftp=ftp：//ftp-gw：21」。它只能指定「」ftp-gw」。只有在每個 InternetOpen所傳回的控制碼使用一個以上的通訊協定時，才需要應用程式指定通訊協定名稱。

列出 Proxy 略過

不應該傳送至 Proxy 的主機名稱或 IP 位址可以列在 Proxy 略過清單中。此清單可以包含萬用字元「*」，這會導致應用程式略過符合指定模式之位址的 Proxy 伺服器。若要列出多個位址和主機名稱，請在 Proxy 略過字串中以分號分隔這些位址和主機名稱。如果指定了「 < local > 」宏，此函式會略過任何不包含句點的主機名稱 Proxy。

根據預設，WinINet 會略過使用主機名稱「localhost」、「loopback」、「127.0.0.1」或「[：：1]」的要求 Proxy。此行為存在，因為遠端 Proxy 伺服器通常不會正確解析這些位址。

Internet Explorer 9： 您可以使用「 < -loopback > 」宏，從 Proxy 略過清單中移除本機電腦。

下列範例示範使用不同的 Proxy 略過字串呼叫 InternetOpen 的範例。上述批註會描述略過字串對從 其建立之 HINTERNET 控制碼存取的主機名稱有何影響。

HINTERNET hInternetRoot;

/* bypass the proxy for any host name that does not 
    contain a period */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("<local>"), 0);

/* bypass the proxy for any host name that starts with the 
    letters "ms" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("ms*"), 0);

/* bypass the proxy for any host name that contains "int", 
    such as "internet" and "painter" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("*int*"), 0);

/* bypass the proxy for the host name "example" and any 
    host name that contains "test" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("example *test*"), 0);

/* Disable the loopback proxy bypass for localhost */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("127.0.0.1:8888"),TEXT("<-loopback>"), 0);

使用 InternetConnect

若要開始會話， InternetConnect 函式必須從 InternetOpen 函式傳回的根控制碼建立控制碼。 InternetConnect 會設定伺服器位址、埠號碼、使用者名稱、密碼和服務類型。

InternetConnect會使用InternetOpen所建立的根HINTERNET控制碼來建立會話控制碼。如果在對InternetOpen的呼叫中設定了INTERNET_FLAG_ASYNC旗標，則對 InternetConnect的呼叫應該包含非零的內容值。

伺服器名稱可以包含主機名稱 (，例如「www.servername.com」) 或以 ASCII 虛線十進位格式 (網站 IP 編號，例如「10.0.1.45」) 。

伺服器埠是傳輸控制通訊協定/網際網路通訊協定 (TCP/IP) 埠號碼，可連線到伺服器上。如果使用 INTERNET_INVALID_PORT_NUMBER 值，InternetConnect會針對選取的服務類型使用預設埠。下表包含 WinINet 的伺服器埠預設值。

值	意義
INTERNET_DEFAULT_FTP_PORT	使用 ftp 伺服器的預設埠， (埠 21) 。
INTERNET_DEFAULT_GOPHER_PORT	使用 Gopher 伺服器的預設埠， (埠 70) 。注意：僅限 Windows XP 和 Windows Server 2003 R2 和更早版本。
INTERNET_DEFAULT_HTTP_PORT	使用 HTTP 伺服器的預設埠， (埠 80) 。
INTERNET_DEFAULT_HTTPS_PORT	使用 HTTPs 伺服器的預設埠， (埠 443) 。
INTERNET_DEFAULT_SOCKS_PORT	使用 SOCKS 防火牆伺服器的預設埠， (埠 1080) 。

定義使用者名稱和密碼

lpszUsername的值是Null終止字串的位址，其中包含登入的使用者名稱。如果此參數為 Null，則函式會使用適當的預設值，但 HTTP 除外。 HTTP 中的 Null 參數會導致伺服器傳回錯誤。針對 FTP 通訊協定，預設值為匿名。

lpszPassword的值是包含登入密碼之Null終止字串的位址。如果 lpszUsername 和 lpszPassword 都是 Null，則函式會使用預設的匿名密碼。在 FTP 的情況下，預設匿名密碼是使用者的電子郵件名稱。如果 lpszUsername 不是 Null 且 lpszPassword 為 Null，則函式會使用空白密碼。 lpszUsername和lpszPassword有四個可能設定，這會產生下表所示的行為。

lpszUsername	lpszPassword	傳送至 FTP 伺服器的使用者名稱	傳送至 FTP 伺服器的密碼
NULL	NULL	「anonymous」	使用者的電子郵件名稱
非Null 字串	NULL	lpszUsername	""
NULL	非Null 字串	ERROR	ERROR
非Null 字串	非Null 字串	lpszUsername	lpszPassword

您可以使用 InternetSetOption 和 InternetErrorDlg 函式來變更此資訊。 InternetSetOption 會變更使用者名稱和密碼值，而 InternetErrorDlg 會顯示要求適當使用者名稱和密碼的對話方塊。

定義會話

若要定義所建立的會話，請設定 InternetConnect的服務類型、旗標和內容值。

InternetConnect有兩種服務類型可供使用：INTERNET_SERVICE_FTP和INTERNET_SERVICE_HTTP。 INTERNET_SERVICE_HTTP同時用於 HTTP 和 HTTPS 會話。

INTERNET_FLAG_PASSIVE 是 WinINet 函式所使用的唯一服務特定旗標。當服務類型INTERNET_SERVICE_FTP以使用被動 FTP 語意時，可以設定此旗標。

針對所有同步作業， dwCoNtext 的值應該設定為零。如果在呼叫InternetOpen中設定INTERNET_FLAG_ASYNC旗標來建立異步操作，則應該為dwCoNtext提供非零值。如需非同步作業的詳細資訊，請參閱設定非同步作業。

對於 FTP 會話， InternetConnect 會嘗試建立網際網路上伺服器的連線。針對 HTTP 會話， InternetConnect 不會建立連線，直到另一個函式嘗試從伺服器取得資訊為止。

注意

WinINet 不支援伺服器實作。此外，它不應該從服務使用。對於伺服器實作或服務，請使用 Microsoft Windows HTTP 服務 (WinHTTP) 。

共用方式為