Fungsi WinHttpConnect (winhttp.h)

Artikel
08/07/2024

Fungsi WinHttpConnect menentukan server target awal permintaan HTTP dan mengembalikan handel koneksi HINTERNET ke sesi HTTP untuk target awal tersebut.

Sintaksis

WINHTTPAPI HINTERNET WinHttpConnect(
  [in] HINTERNET     hSession,
  [in] LPCWSTR       pswzServerName,
  [in] INTERNET_PORT nServerPort,
  [in] DWORD         dwReserved
);

Parameter

[in] hSession

Handel sesi HINTERNET WinHTTP valid yang dikembalikan oleh panggilan sebelumnya untuk WinHttpOpen.

[in] pswzServerName

Penunjuk ke stringnull yang dihentikan yang berisi nama host server HTTP. Secara bergantian, string dapat berisi alamat IP situs sebagai string, misalnya, 10.0.1.45. Perhatikan bahwa WinHttp tidak menerima nama host internasional tanpa mengonversinya terlebih dahulu ke Punycode. Untuk informasi selengkapnya, lihat Menangani Nama Domain Internasional (IDN).

[in] nServerPort

Bilangan bulat yang tidak ditandatangani yang menentukan port TCP/IP pada server tempat koneksi dibuat. Parameter ini dapat berupa nomor port TCP/IP yang valid, atau salah satu nilai berikut.

Nilai	Arti
INTERNET_DEFAULT_HTTP_PORT	Menggunakan port default untuk server HTTP (port 80).
INTERNET_DEFAULT_HTTPS_PORT	Menggunakan port default untuk server HTTPS (port 443). Memilih port ini tidak otomatis membuat sambungan aman. Anda masih harus menentukan penggunaan semantik transaksi aman dengan menggunakan bendera WINHTTP_FLAG_SECURE dengan WinHttpOpenRequest.
INTERNET_DEFAULT_PORT	Menggunakan port 80 untuk HTTP dan port 443 untuk Secure Hypertext Transfer Protocol (HTTPS).

[in] dwReserved

Parameter ini dicadangkan dan harus 0.

Mengembalikan nilai

Mengembalikan handel koneksi yang valid ke sesi HTTP jika koneksi berhasil, atau NULL sebaliknya. Untuk mengambil informasi kesalahan yang diperluas, panggil GetLastError. Di antara kode kesalahan yang dikembalikan adalah sebagai berikut.

Kode Kesalahan	Deskripsi
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Jenis handel yang disediakan salah untuk operasi ini.
ERROR_WINHTTP_INTERNAL_ERROR	Terjadi kesalahan internal.
ERROR_WINHTTP_INVALID_URL	URL tidak valid.
ERROR_WINHTTP_OPERATION_CANCELLED	Operasi dibatalkan, biasanya karena handel tempat permintaan beroperasi ditutup sebelum operasi selesai.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	Skema URL tidak dapat dikenali, atau tidak didukung.
ERROR_WINHTTP_SHUTDOWN	Dukungan fungsi WinHTTP sedang dimatikan atau dibongkar.
ERROR_NOT_ENOUGH_MEMORY	Memori tidak cukup tersedia untuk menyelesaikan operasi yang diminta. (Kode galat Windows)

Komentar

Bahkan ketika WinHTTP digunakan dalam mode asinkron (yaitu, ketika WINHTTP_FLAG_ASYNC telah diatur dalam WinHttpOpen), fungsi ini beroperasi secara sinkron. Nilai pengembalian menunjukkan keberhasilan atau kegagalan. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Setelah aplikasi panggilan selesai menggunakan handel HINTERNET yang dikembalikan oleh WinHttpConnect, aplikasi harus ditutup menggunakan fungsi WinHttpCloseHandle .

WinHttpConnect menentukan server HTTP target, namun respons dapat berasal dari server lain jika permintaan dialihkan. Anda bisa menentukan URL server yang mengirim respons dengan memanggil WinHttpQueryOption dengan bendera WINHTTP_OPTION_URL.

Catatan Untuk Windows XP dan Windows 2000, lihat bagian persyaratan Run-Time halaman mulai WinHttp.

Contoh

Contoh berikut menunjukkan cara menggunakan semantik transaksi aman untuk mengunduh sumber daya dari server HTTPS. Kode sampel menginisialisasi antarmuka pemrograman aplikasi (API) Microsoft Windows HTTP Services (WinHTTP), memilih server HTTPS target, lalu membuka dan mengirim permintaan untuk sumber daya aman ini.
WinHttpQueryDataAvailable digunakan dengan handel permintaan untuk menentukan berapa banyak data yang tersedia untuk diunduh, lalu WinHttpReadData digunakan untuk membaca data tersebut. Proses ini berulang hingga seluruh dokumen diambil dan ditampilkan.


    DWORD dwSize = 0;
    DWORD dwDownloaded = 0;
    LPSTR pszOutBuffer;
    BOOL  bResults = FALSE;
    HINTERNET  hSession = NULL, 
               hConnect = NULL,
               hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen( L"WinHTTP Example/1.0",  
                            WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                            WINHTTP_NO_PROXY_NAME, 
                            WINHTTP_NO_PROXY_BYPASS, 0);

    // Specify an HTTP server.
    if (hSession)
        hConnect = WinHttpConnect( hSession, L"www.microsoft.com",
                                   INTERNET_DEFAULT_HTTPS_PORT, 0);

    // Create an HTTP request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
                                       NULL, WINHTTP_NO_REFERER, 
                                       WINHTTP_DEFAULT_ACCEPT_TYPES, 
                                       WINHTTP_FLAG_SECURE);

    // Send a request.
    if (hRequest)
        bResults = WinHttpSendRequest( hRequest,
                                       WINHTTP_NO_ADDITIONAL_HEADERS,
                                       0, WINHTTP_NO_REQUEST_DATA, 0, 
                                       0, 0);

 
    // End the request.
    if (bResults)
        bResults = WinHttpReceiveResponse( hRequest, NULL);

    // Keep checking for data until there is nothing left.
    if (bResults)
        do 
        {
            // Check for available data.
            dwSize = 0;
            if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
                printf("Error %u in WinHttpQueryDataAvailable.\n", GetLastError());

            // Allocate space for the buffer.
            pszOutBuffer = new char[dwSize+1];
            if (!pszOutBuffer)
            {
                printf("Out of memory\n");
                dwSize=0;
            }
            else
            {
                // Read the Data.
                ZeroMemory(pszOutBuffer, dwSize+1);

                if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer, 
                                      dwSize, &dwDownloaded))
                    printf( "Error %u in WinHttpReadData.\n", GetLastError());
                else
                    printf( "%s\n", pszOutBuffer);
            
                // Free the memory allocated to the buffer.
                delete [] pszOutBuffer;
            }

        } while (dwSize > 0);


    // Report any errors.
    if (!bResults)
        printf("Error %d has occurred.\n", GetLastError());

    // Close any open handles.
    if (hRequest) WinHttpCloseHandle(hRequest);
    if (hConnect) WinHttpCloseHandle(hConnect);
    if (hSession) WinHttpCloseHandle(hSession);

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows XP, Windows 2000 Professional dengan SP3 [hanya aplikasi desktop]
server minimum yang didukung	Windows Server 2003, Windows 2000 Server dengan SP3 [hanya aplikasi desktop]
Platform Target	Windows
Header	winhttp.h
Pustaka	Winhttp.lib
DLL	Winhttp.dll
Redistributable	WinHTTP 5.0 dan Internet Explorer 5.01 atau yang lebih baru di Windows XP dan Windows 2000.