WinHttpConnect-Funktion (winhttp.h)
Die WinHttpConnect--Funktion gibt den ursprünglichen Zielserver einer HTTP-Anforderung an und gibt ein HINTERNET- Verbindungshandle mit einer HTTP-Sitzung für dieses anfängliche Ziel zurück.
Syntax
WINHTTPAPI HINTERNET WinHttpConnect(
[in] HINTERNET hSession,
[in] LPCWSTR pswzServerName,
[in] INTERNET_PORT nServerPort,
[in] DWORD dwReserved
);
Parameter
[in] hSession
Gültige HINTERNET- WinHTTP-Sitzungshandle, das von einem vorherigen Aufruf an WinHttpOpenzurückgegeben wird.
[in] pswzServerName
Zeigen Sie auf eine NULL--terminated-Zeichenfolge, die den Hostnamen eines HTTP-Servers enthält. Alternativ kann die Zeichenfolge die IP-Adresse der Website als Zeichenfolge enthalten, z. B. 10.0.1.45. Beachten Sie, dass WinHttp internationale Hostnamen nicht akzeptiert, ohne sie zuerst in Punycode-zu konvertieren. Weitere Informationen finden Sie unter Handling Internationalized Domain Names (IDNs).
[in] nServerPort
Nicht signierte ganze Zahl, die den TCP/IP-Port auf dem Server angibt, mit dem eine Verbindung hergestellt wird. Dieser Parameter kann eine beliebige gültige TCP/IP-Portnummer oder einer der folgenden Werte sein.
| Wert | Bedeutung |
|---|---|
|
Verwendet den Standardport für HTTP-Server (Port 80). |
|
Verwendet den Standardport für HTTPS-Server (Port 443). Wenn Sie diesen Port auswählen, wird keine sichere Verbindung hergestellt. Sie müssen weiterhin die Verwendung der sicheren Transaktionssemantik mithilfe des WINHTTP_FLAG_SECURE Flags mit WinHttpOpenRequest-angeben. |
|
Verwendet Port 80 für HTTP und Port 443 für secure Hypertext Transfer Protocol (HTTPS). |
[in] dwReserved
Dieser Parameter ist reserviert und muss 0 sein.
Rückgabewert
Gibt ein gültiges Verbindungshandle an die HTTP-Sitzung zurück, wenn die Verbindung erfolgreich ist, oder NULL- andernfalls. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen abzurufen. Zu den zurückgegebenen Fehlercodes gehören die folgenden.
| Fehlercodes | Beschreibung |
|---|---|
|
Der typ des bereitgestellten Handles ist für diesen Vorgang falsch. |
|
Interner Fehler. |
|
Die URL ist ungültig. |
|
Der Vorgang wurde abgebrochen, in der Regel weil der Handle, für den die Anforderung ausgeführt wurde, vor Abschluss des Vorgangs geschlossen wurde. |
|
Das URL-Schema konnte nicht erkannt werden oder wird nicht unterstützt. |
|
Die WinHTTP-Funktionsunterstützung wird heruntergefahren oder entladen. |
|
Nicht genügend Arbeitsspeicher war verfügbar, um den angeforderten Vorgang abzuschließen. (Windows-Fehlercode) |
Bemerkungen
Auch wenn WinHTTP im asynchronen Modus verwendet wird (d. h. wenn WINHTTP_FLAG_ASYNC in WinHttpOpenfestgelegt wurde), wird diese Funktion synchron ausgeführt. Der Rückgabewert gibt Erfolg oder Fehler an. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Nachdem die aufrufende Anwendung mit dem
WinHttpConnect- gibt den Ziel-HTTP-Server an, eine Antwort kann jedoch von einem anderen Server stammen, wenn die Anforderung umgeleitet wurde. Sie können die URL des Servers bestimmen, der die Antwort sendet, indem Sie WinHttpQueryOption- mit dem WINHTTP_OPTION_URL-Flag aufrufen.
Beispiele
Das folgende Beispiel zeigt, wie Sie sichere Transaktionssemantik verwenden, um eine Ressource von einem HTTPS-Server herunterzuladen. Der Beispielcode initialisiert die Microsoft Windows HTTP Services (WinHTTP)-Anwendungsprogrammierschnittstelle (API), wählt einen ZIEL-HTTPS-Server aus, öffnet und sendet eine Anforderung für diese sichere Ressource.
WinHttpQueryDataAvailable wird mit dem Anforderungshandle verwendet, um zu bestimmen, wie viele Daten zum Herunterladen verfügbar sind, und WinHttpReadData zum Lesen dieser Daten verwendet wird. Dieser Vorgang wird wiederholt, bis das gesamte Dokument abgerufen und angezeigt wurde.
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);
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP, Windows 2000 Professional mit SP3 [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2003, Windows 2000 Server mit SP3 [nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | winhttp.h |
| Library | Winhttp.lib |
| DLL- | Winhttp.dll |
| redistributable | WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000. |