Włączanie funkcjonalności internetowej

Przed użyciem funkcji WinINet aplikacja powinna podjąć próbę nawiązania połączenia z Internetem przy użyciu funkcji InternetAttemptConnect. Ta funkcja wywołuje okno dialogowe połączenia dial-up, aby zainicjować połączenie z Internetem oraz sprawdzić, czy połączenie już istnieje. Jeśli ta funkcja nie powiedzie się, aplikacja może wprowadzić tryb offline, który umożliwia mu dostęp do informacji buforowanych podczas poprzednich połączeń z Internetem.

Użyj funkcji InternetCheckConnection, aby sprawdzić połączenie z Internetem. Próbuje wysłać polecenie ping do serwera wyznaczonego przez adres URL przekazany do funkcji. Jeśli flaga FLAG_ICC_FORCE_CONNECTION jest ustawiona, a adres URL ma wartość null, funkcja sprawdza, czy w bazie danych serwera znajduje się wpis dla najbliższego serwera. Jeśli taki istnieje, funkcja wysyła polecenie ping do tego serwera.

Następnie użyj funkcji InternetOtwórz, aby ustanowić charakterystykę połączenia internetowego używanego przez aplikację kliencą. InternetOpen tworzy nadrzędny uchwyt HINTERNET, który jest używany do ustanawiania sesji http ftp. InternetOtwórz nie testuje połączenia z Internetem, aby sprawdzić, czy właściwości przekazane do funkcji są poprawne.

Użyj funkcji InternetConnect, aby utworzyć określoną sesję. InternetConnect inicjuje sesję dla określonej strony przy użyciu argumentów przekazanych do niej i tworzy HINTERNET, który jest gałęzią od uchwytu głównego. InternetConnect nie próbuje uzyskać dostępu ani nawiązać połączenia z określoną lokacją, z wyjątkiem sytuacji sesji FTP. FtpFindFirstFile, FtpOpenFilei HttpOpenRequest funkcje używają dojścia utworzonego przez InternetConnect w celu nawiązania połączenia z określoną witryną.

Korzystanie z InternetuOtwórz

Aby umożliwić połączenie z Internetem, należy utworzyć uchwyt HINTERNET przy użyciu InternetOpen. Informacje o agencie użytkownika (aplikacji wywołującej funkcje internetowe), typ dostępu do Internetu, nazwy serwera proxy, hosty i adresy pomijające serwer proxy oraz zachowanie są przekazywane do InternetOtwórz.

Ustawianie agenta użytkownika

Aplikacja wywołująca powinna przekazać ciąg znaków, który zawiera nazwę aplikacji lub jednostki, która uzyskuje dostęp do Internetu, parametrowi lpszAgent funkcji InternetOpen. Ten ciąg jest używany jako agent użytkownika w protokole HTTP. Na przykład program Microsoft Internet Explorer używa programu "Microsoft Internet Explorer".

Ustawianie typów dostępu

InternetOtwórz obsługuje trzy typy dostępu:

• Użyj INTERNET_OPEN_TYPE_DIRECT, jeśli system, w którym działa aplikacja, używa bezpośredniego połączenia z Internetem. Parametry lpszProxyName i lpszProxyBypass parametrów InternetOpen nie są używane i powinny być ustawione na NULL.
• Użyj INTERNET_OPEN_TYPE_PROXY, jeśli system, w którym działa aplikacja, używa co najmniej jednego serwera proxy do uzyskiwania dostępu do Internetu. InternetOpen używa serwerów proxy wskazanych przez lpszProxyName i pomija serwer proxy dla nazw hostów lub adresów IP określonych przez lpszProxyBypass.
• Użyj INTERNET_OPEN_TYPE_PRECONFIG, aby poinstruować aplikację o pobraniu konfiguracji z rejestru. Jest to zazwyczaj najlepszy wybór, ponieważ większość aplikacji, w tym przeglądarek internetowych, używa tej opcji.

INTERNET_OPEN_TYPE_PRECONFIG analizuje wartości rejestru ProxyEnable, ProxyServeri ProxyOverride. Te wartości znajdują się w obszarze "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings".

Jeśli ProxyEnable wynosi zero, aplikacja używa INTERNET_OPEN_TYPE_DIRECT. W przeciwnym razie aplikacja używa INTERNET_OPEN_TYPE_PROXY i używa informacji ProxyServer oraz ProxyOverride.

Funkcje WinINet zapewniają obsługę serwerów proxy typu SOCKS tylko wtedy, gdy jest zainstalowany program Internet Explorer. Instalacja programu Internet Explorer zawiera plik Wsock32n.dll, który jest wymagany do obsługi serwerów proxy SOCKS. Wsock32n.dll nie jest redystrybuowalny.

Wyświetlanie listy serwerów proxy

WinINet rozpoznaje dwa typy serwerów proxy: serwery proxy typu CERN (tylko HTTP) i serwery proxy FTP TIS (tylko FTP). Jeśli program Internet Explorer jest zainstalowany, platforma WinINet obsługuje również serwery proxy typu SOCKS. InternetConnect zakłada domyślnie, że określony serwer proxy jest serwerem proxy CERN. Jeśli typ dostępu jest ustawiony na INTERNET_OPEN_TYPE_DIRECT lub INTERNET_OPEN_TYPE_PRECONFIG, parametr lpszProxyNameInternetOpen powinien być ustawiony na wartość NULL. W przeciwnym razie wartość przekazana do lpszProxyName musi zawierać serwery proxy w ciągu znaków oddzielonym spacjami. Listy serwerów proxy mogą zawierać numer portu używany do uzyskiwania dostępu do serwera proxy.

Aby wyświetlić proxy dla określonego protokołu, ciąg znaków musi być zgodny z formatem ""<protocol><protocol>://<nazwa_proxya>"". Prawidłowe protokoły to HTTP, HTTPS i FTP. Na przykład aby wyświetlić serwer proxy FTP, prawidłowy ciąg to ""ftp=ftp://ftp_proxy_name:21", gdzie ftp_proxy_name jest nazwą serwera proxy FTP, a 21 to numer portu, który musi być używany do uzyskiwania dostępu do serwera proxy. Jeśli serwer proxy używa domyślnego numeru portu dla tego protokołu, numer portu można pominąć. Jeśli nazwa serwera proxy jest wyświetlana samodzielnie, jest używana jako domyślny serwer proxy dla wszystkich protokołów, które nie mają określonego serwera proxy. Na przykład ""http=https://http_proxy inne", będzie używać http_proxy dla wszystkich operacji HTTP, podczas gdy wszystkie inne protokoły będą używać innych.

Domyślnie funkcja zakłada, że serwer proxy określony przez lpszProxyName jest serwerem proxy CERN. Aplikacja może określić więcej niż jeden serwer proxy, w tym różne serwery proxy dla różnych protokołów. Jeśli na przykład określisz ""ftp=ftp://ftp-gw HTTP=https://jericho:99 proxy", żądania FTP są wysyłane za pośrednictwem serwera proxy ftp-gw, który nasłuchuje na porcie 21, a żądania HTTP są wysyłane za pośrednictwem serwera proxy CERN o nazwie jericho, który nasłuchuje na porcie 99. W przeciwnym razie żądania HTTP będą wykonywane za pośrednictwem serwera proxy CERN o nazwie proxy, który nasłuchuje na porcie 80. Należy pamiętać, że jeśli aplikacja korzysta tylko z protokołu FTP, nie musi na przykład określać ciągu ""ftp=ftp://ftp-gw:21"". Może określać tylko „ftp-gw”. Aplikacja musi określić nazwy protokołów tylko wtedy, gdy używa więcej niż jednego protokołu na dojście zwrócone przez InternetOpen.

Wyświetlanie listy obejścia serwera proxy

Nazwy hostów lub adresy IP, które nie powinny być wysyłane do serwera proxy, można wyświetlić na liście obejść serwera proxy. Ta lista może zawierać symbole wieloznaczne "*", co powoduje obejście serwera proxy dla adresów pasujących do określonego wzorca. Aby wyświetlić listę wielu adresów i nazw hostów, rozdziel je średnikami w ciągu obejścia serwera proxy. Jeśli określono makro "<local>", funkcja pomija serwer proxy dla każdej nazwy hosta, która nie zawiera kropki.

Domyślnie usługa WinINet pomija serwer proxy dla żądań używających nazw hostów "localhost", "loopback", "127.0.0.1" lub "[::1]". To zachowanie istnieje, ponieważ zdalny serwer proxy zazwyczaj nie rozwiąże tych adresów prawidłowo.

Internet Explorer 9: Możesz usunąć komputer lokalny z listy obejść serwera proxy przy użyciu makra "<-loopback>".

W poniższym przykładzie przedstawiono przykładowe wywołania InternetOpen przy użyciu różnych ciągów obejścia proxy. Komentarze powyżej każdego wywołania opisują, jaki wpływ ma ciąg znaków obejścia na nazwy hostów, do których uzyskuje się dostęp z uchwytu HINTERNET, który tworzy.

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);

Korzystanie z programu InternetConnect

Aby rozpocząć sesję, funkcja InternetConnect musi utworzyć uchwyt z głównego uchwytu zwróconego przez funkcję InternetOpen. InternetConnect ustawia adres serwera, numer portu, nazwę użytkownika, hasło i typ usługi.

InternetConnect używa głównego dojścia HINTERNET utworzonego przez InternetOpen do ustanowienia dojścia sesji. Jeśli flaga INTERNET_FLAG_ASYNC została ustawiona w wywołaniu InternetOpen, wywołanie InternetConnect powinno zawierać niezerową wartość kontekstu.

Nazwa serwera może zawierać nazwę hosta (na przykład "www.servername.com") lub numer IP witryny w formacie dziesiętnym ASCII (na przykład "10.0.1.45").

Port serwera to numer portu protokołu TCP/IP (Transmission Control Protocol/Internet Protocol) do nawiązania połączenia z serwerem. InternetConnect używa portu domyślnego dla wybranego typu usługi, jeśli jest używana wartość INTERNET_INVALID_PORT_NUMBER. Poniższe tabele zawierają wartości domyślne portów serwera dla usługi WinINet.

Definiowanie nazwy użytkownika i hasła

Wartość lpszUsername jest adresem null-terminated ciąg zawierający nazwę użytkownika, który loguje się. Jeśli ten parametr ma wartość null, funkcja używa odpowiedniego domyślnego ustawienia, z wyjątkiem protokołu HTTP. Parametr NULL w HTTP powoduje zwrócenie błędu przez serwer. W przypadku protokołu FTP wartość domyślna to anonimowy.

Wartość lpszPassword jest adresem ciągu kończącego się znakiem null, który zawiera hasło logowania. Jeśli zarówno lpszUsername, jak i lpszPassword są NULL, funkcja używa domyślnego hasła anonimowego. W przypadku protokołu FTP domyślne hasło anonimowe to nazwa e-mail użytkownika. Jeśli lpszUsername nie jest NULL oraz lpszPassword jest NULL, funkcja używa pustego hasła. Istnieją cztery możliwe ustawienia lpszUsername i lpszPassword, które generują zachowania pokazane w poniższej tabeli.

Te informacje można zmienić przy użyciu funkcji InternetSetOption i InternetErrorDlg. InternetSetOption zmienia wartości nazwy użytkownika i hasła, a InternetErrorDlg wyświetla okno dialogowe, które żąda prawidłowej nazwy użytkownika i hasła.

Definiowanie sesji

Aby zdefiniować ustanowioną sesję, ustaw typ usługi, flagi i wartość kontekstu dla InternetConnect.

Dostępne są dwa typy usług InternetConnect: INTERNET_SERVICE_FTP i INTERNET_SERVICE_HTTP. INTERNET_SERVICE_HTTP jest używany zarówno w przypadku sesji HTTP, jak i HTTPS.

INTERNET_FLAG_PASSIVE jest jedyną flagą specyficzną dla usługi używaną przez funkcje WinINet. Tę flagę można ustawić, gdy typ usługi jest INTERNET_SERVICE_FTP w celu używania pasywnej semantyki FTP.

Dla wszystkich operacji synchronicznych wartość dwContext powinna być ustawiona na zero. Jeśli operacje asynchroniczne zostały ustanowione przez ustawienie flagi INTERNET_FLAG_ASYNC w wywołaniu do InternetOpen, należy podać wartość niezerową dla dwContext. Aby uzyskać więcej informacji na temat operacji asynchronicznych, zobacz Konfigurowanie operacji asynchronicznych.

W przypadku sesji FTP InternetConnect próbuje nawiązać połączenie z serwerem w Internecie. W przypadku sesji HTTP InternetConnect nie ustanawia połączenia, dopóki inna funkcja nie spróbuje uzyskać informacji z serwera.