Función WinHttpConnect (winhttp.h)

Artículo
08/07/2024

La función WinHttpConnect especifica el servidor de destino inicial de una solicitud HTTP y devuelve un HINTERNET identificador de conexión a una sesión HTTP para ese destino inicial.

Sintaxis

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

Parámetros

[in] hSession

Identificador válido HINTERNET sesión winHTTP devuelto por una llamada anterior a WinHttpOpen.

[in] pswzServerName

Puntero a un cadena terminadanull que contiene el nombre de host de un servidor HTTP. Como alternativa, la cadena puede contener la dirección IP del sitio como una cadena, por ejemplo, 10.0.1.45. Tenga en cuenta que WinHttp no acepta nombres de host internacionales sin convertirlos primero en Punycode. Para obtener más información, vea control de nombres de dominio internacionalizados (IDN).

[in] nServerPort

Entero sin signo que especifica el puerto TCP/IP en el servidor al que se realiza una conexión. Este parámetro puede ser cualquier número de puerto TCP/IP válido o uno de los valores siguientes.

Valor	Significado
INTERNET_DEFAULT_HTTP_PORT	Usa el puerto predeterminado para los servidores HTTP (puerto 80).
INTERNET_DEFAULT_HTTPS_PORT	Usa el puerto predeterminado para los servidores HTTPS (puerto 443). Al seleccionar este puerto no se establece automáticamente una conexión segura. Todavía debe especificar el uso de la semántica de transacciones seguras mediante la marca WINHTTP_FLAG_SECURE con WinHttpOpenRequest.
INTERNET_DEFAULT_PORT	Usa el puerto 80 para HTTP y el puerto 443 para el protocolo seguro de transferencia de hipertexto (HTTPS).

[in] dwReserved

Este parámetro está reservado y debe ser 0.

Valor devuelto

Devuelve un identificador de conexión válido a la sesión HTTP si la conexión es correcta o NULL de lo contrario. Para recuperar información de error extendida, llame a GetLastError. Entre los códigos de error devueltos se muestran los siguientes.

Códigos de error	Descripción
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	El tipo de identificador proporcionado es incorrecto para esta operación.
ERROR_WINHTTP_INTERNAL_ERROR	Se ha producido un error interno.
ERROR_WINHTTP_INVALID_URL	La dirección URL no es válida.
ERROR_WINHTTP_OPERATION_CANCELLED	La operación se canceló, normalmente porque el identificador en el que estaba funcionando la solicitud se cerró antes de que se completara la operación.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	No se pudo reconocer el esquema de dirección URL o no se admite.
ERROR_WINHTTP_SHUTDOWN	La compatibilidad con la función WinHTTP se está apagando o descargando.
ERROR_NOT_ENOUGH_MEMORY	No había suficiente memoria disponible para completar la operación solicitada. (Código de error de Windows)

Observaciones

Incluso cuando WinHTTP se usa en modo asincrónico (es decir, cuando se ha establecido WINHTTP_FLAG_ASYNC en WinHttpOpen), esta función funciona sincrónicamente. El valor devuelto indica éxito o error. Para obtener información de error extendida, llame a GetLastError.

Una vez finalizada la aplicación que realiza la llamada mediante el identificador HINTERNET devuelto por WinHttpConnect, debe cerrarse mediante la función WinHttpCloseHandle.

WinHttpConnect especifica el servidor HTTP de destino, pero una respuesta puede proceder de otro servidor si se redirigió la solicitud. Puede determinar la dirección URL del servidor que envía la respuesta llamando a WinHttpQueryOption con la marca WINHTTP_OPTION_URL.

Nota para Windows XP y Windows 2000, consulta la sección Run-Time Requirements de la página de inicio de WinHttp.

Ejemplos

En el ejemplo siguiente se muestra cómo usar la semántica de transacciones seguras para descargar un recurso desde un servidor HTTPS. El código de ejemplo inicializa la interfaz de programación de aplicaciones (API) de Servicios HTTP de Microsoft Windows (WinHTTP), selecciona un servidor HTTPS de destino y, a continuación, abre y envía una solicitud para este recurso seguro.
winHttpQueryDataAvailable se usa con el identificador de solicitud para determinar la cantidad de datos disponibles para su descarga y, a continuación, se usa winHttpReadData para leer esos datos. Este proceso se repite hasta que se haya recuperado y mostrado todo el documento.


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

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP, Windows 2000 Professional con SP3 [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003, Windows 2000 Server con SP3 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winhttp.h
biblioteca de	Winhttp.lib
DLL de	Winhttp.dll
redistribuible	WinHTTP 5.0 e Internet Explorer 5.01 o posterior en Windows XP y Windows 2000.