Función WinHttpCrackUrl (winhttp.h)

Artículo
11/20/2024

La función WinHttpCrackUrl separa una dirección URL en sus partes de componente, como el nombre de host y la ruta de acceso.

Sintaxis

WINHTTPAPI BOOL WinHttpCrackUrl(
  [in]      LPCWSTR          pwszUrl,
  [in]      DWORD            dwUrlLength,
  [in]      DWORD            dwFlags,
  [in, out] LPURL_COMPONENTS lpUrlComponents
);

Parámetros

[in] pwszUrl

Puntero a una cadena que contiene la dirección URL canónica que se va a separar. WinHttpCrackUrl no comprueba esta dirección URL si hay validez ni formato correcto antes de intentar descifrarla.

[in] dwUrlLength

Longitud de la cadena de pwszUrl, en caracteres. Si dwUrlLength se establece en cero, WinHttpCrackUrl supone que la cadena de pwszUrl es null terminada y determina la longitud de la cadena pwszUrl basada en esa suposición.

[in] dwFlags

Marcas que controlan la operación. Este parámetro puede ser una combinación de una o varias de las marcas siguientes (los valores pueden ser OR bit a bit). O bien, el parámetro puede ser 0, que no realiza ninguna operación especial.

Valor	Significado
ICU_DECODE	Convierte los caracteres que son "escape codificados" (%xx) en su forma sin escape. Esto no descodifica otras codificaciones, como UTF-8. Esta característica solo se puede usar si el usuario proporciona búferes en la estructura URL_COMPONENTS para copiar los componentes en.
ICU_ESCAPE	Escape de determinados caracteres a sus secuencias de escape (%xx). Los caracteres que se van a escapen son caracteres no ASCII o los caracteres ASCII que se deben escapar para representarse en una solicitud HTTP. Esta característica solo se puede usar si el usuario proporciona búferes en la estructura URL_COMPONENTS para copiar los componentes en.
ICU_REJECT_USERPWD	Rechaza las direcciones URL como entrada que contienen credenciales incrustadas (un nombre de usuario, una contraseña o ambas). Si se produce un error en la función debido a una dirección URL no válida, las llamadas posteriores a GetLastError devuelven ERROR_WINHTTP_INVALID_URL.

[in, out] lpUrlComponents

Puntero a una estructura de URL_COMPONENTS que recibe los componentes de la dirección URL.

Valor devuelto

Devuelve TRUE si la función se ejecuta correctamente o FALSE de lo contrario. Para obtener 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_INTERNAL_ERROR	Se ha producido un error interno.
ERROR_WINHTTP_INVALID_URL	La dirección URL no es válida.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	No se pudo reconocer el esquema de dirección URL o no se admite.
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.

Los componentes necesarios se indican mediante miembros de la estructura URL_COMPONENTS. Cada componente tiene un puntero al valor y tiene un miembro que almacena la longitud del valor almacenado. Si el valor y la longitud de un componente son iguales a cero, no se devuelve ese componente. Si el puntero al valor del componente es NULL y el valor de su miembro de longitud correspondiente es distinto de cero, la dirección del primer carácter del componente correspondiente en la cadena de pwszUrl se almacena en el puntero y la longitud del componente se almacena en el miembro length.

Si el puntero contiene la dirección del búfer proporcionado por el usuario, el miembro de longitud debe contener el tamaño del búfer. La función WinHttpCrackUrl copia el componente en el búfer y el miembro de longitud se establece en la longitud del componente copiado, menos 1 para el terminador de cadena final. Si un búfer proporcionado por el usuario no es lo suficientemente grande, WinHttpCrackUrl devuelve FALSEy GetLastError devuelve ERROR_INSUFFICIENT_BUFFER.

Para que WinHttpCrackUrl funcione correctamente, el tamaño de la estructura de URL_COMPONENTS debe almacenarse en el miembro dwStructSize de esa estructura.

Si el protocolo de Internet de la dirección URL pasada para pwszUrl no es HTTP o HTTPS, WinHttpCrackUrl devuelve FALSE y GetLastError indica
ERROR_WINHTTP_UNRECOGNIZED_SCHEME.

WinHttpCrackUrl no comprueba la validez ni el formato de una dirección URL antes de intentar descifrarla. Como resultado, si se pasa una cadena como ""http://server?Bad=URL"", la función devuelve resultados incorrectos.

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

Ejemplos

En este ejemplo se muestra cómo dividir una dirección URL en sus componentes, actualizar un componente y, a continuación, reconstruir la dirección URL.

    URL_COMPONENTS urlComp;
    LPCWSTR pwszUrl1 = 
      L"http://search.msn.com/results.asp?RS=CHECKED&FORM=MSNH&v=1&q=wininet";
    DWORD dwUrlLen = 0;

    // Initialize the URL_COMPONENTS structure.
    ZeroMemory(&urlComp, sizeof(urlComp));
    urlComp.dwStructSize = sizeof(urlComp);

    // Set required component lengths to non-zero 
    // so that they are cracked.
    urlComp.dwSchemeLength    = (DWORD)-1;
    urlComp.dwHostNameLength  = (DWORD)-1;
    urlComp.dwUrlPathLength   = (DWORD)-1;
    urlComp.dwExtraInfoLength = (DWORD)-1;

    // Crack the URL.
    if (!WinHttpCrackUrl( pwszUrl1, (DWORD)wcslen(pwszUrl1), 0, &urlComp))
    {
        printf("Error %u in WinHttpCrackUrl.\n", GetLastError());
    }
    else
    {
        // Change the search information.  
        // New info is the same length.
        urlComp.lpszExtraInfo = L"?RS=CHECKED&FORM=MSNH&v=1&q=winhttp";

        // Obtain the size of the new URL and allocate memory.
        WinHttpCreateUrl( &urlComp, 0, NULL, &dwUrlLen);
        LPWSTR pwszUrl2 = new WCHAR[dwUrlLen];

        // Create a new URL.
        if(!WinHttpCreateUrl( &urlComp, 0, pwszUrl2, &dwUrlLen))
        {
            printf("Error %u in WinHttpCreateUrl.\n", GetLastError());
        }
        else
        {
            // Show both URLs.
            printf("Old URL:  %S\nNew URL:  %S\n", pwszUrl1, pwszUrl2);
        }

        // Free allocated memory.
        delete [] pwszUrl2;
    }

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.

Consulte también

acerca de los servicios HTTP de Microsoft Windows (WinHTTP)

control de localizadores uniformes de recursos

versiones winHTTP

WinHttpCreateUrl

Compartir a través de