Funzione WinHttpCrackUrl (winhttp.h)

Articolo
11/20/2024

La funzione winHttpCrackUrl separa un URL nelle parti del componente, ad esempio il nome host e il percorso.

Sintassi

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

Parametri

[in] pwszUrl

Puntatore a una stringa contenente l'URL canonico da separare. winHttpCrackUrl non controlla questo URL per la validità o il formato corretto prima di tentare di violarlo.

[in] dwUrlLength

Lunghezza della stringa pwszUrl, espressa in caratteri. Se dwUrlLength è impostato su zero, WinHttpCrackUrl presuppone che la stringa pwszUrl sia null terminata e determina la lunghezza della stringa pwszUrl in base a tale presupposto.

[in] dwFlags

Flag che controllano l'operazione. Questo parametro può essere una combinazione di uno o più dei flag seguenti (i valori possono essere or bit per bit). In alternativa, il parametro può essere 0, che non esegue operazioni speciali.

Valore	Significato
ICU_DECODE	Converte i caratteri "codificati con escape" (%xx) nel formato non preceduto da escape. Questa operazione non decodifica altre codifiche, ad esempio UTF-8. Questa funzionalità può essere usata solo se l'utente fornisce buffer nella struttura URL_COMPONENTS in cui copiare i componenti.
ICU_ESCAPE	Esegue l'escape di determinati caratteri nelle sequenze di escape (%xx). I caratteri di escape sono caratteri non ASCII o caratteri ASCII di cui è necessario eseguire l'escape per essere rappresentati in una richiesta HTTP. Questa funzionalità può essere usata solo se l'utente fornisce buffer nella struttura URL_COMPONENTS in cui copiare i componenti.
ICU_REJECT_USERPWD	Rifiuta gli URL come input che contengono credenziali incorporate (un nome utente, una password o entrambi). Se la funzione non riesce a causa di un URL non valido, le chiamate successive a GetLastError restituiscono ERROR_WINHTTP_INVALID_URL.

[in, out] lpUrlComponents

Puntatore a una struttura URL_COMPONENTS che riceve i componenti URL.

Valore restituito

Restituisce TRUE se la funzione ha esito positivo o false in caso contrario. Per ottenere informazioni estese sull'errore, chiamare GetLastError. Tra i codici di errore restituiti sono riportati di seguito.

Codici di errore	Descrizione
ERROR_WINHTTP_INTERNAL_ERROR	Si è verificato un errore interno.
ERROR_WINHTTP_INVALID_URL	L'URL non è valido.
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	Non è stato possibile riconoscere lo schema URL o non è supportato.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l'operazione richiesta. (Codice errore di Windows)

Osservazioni

Anche quando WinHTTP viene usato in modalità asincrona ( ovvero quando WINHTTP_FLAG_ASYNC è stato impostato in WinHttpOpen), questa funzione funziona in modo sincrono. Il valore restituito indica l'esito positivo o negativo. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

I componenti necessari sono indicati dai membri della struttura URL_COMPONENTS. Ogni componente ha un puntatore al valore e ha un membro che archivia la lunghezza del valore archiviato. Se sia il valore che la lunghezza di un componente sono uguali a zero, tale componente non viene restituito. Se il puntatore al valore del componente è NULL e il valore del membro di lunghezza corrispondente è diverso da zero, l'indirizzo del primo carattere del componente corrispondente nella pwszUrl stringa viene archiviata nel puntatore e la lunghezza del componente viene archiviata nel membro di lunghezza.

Se il puntatore contiene l'indirizzo del buffer fornito dall'utente, il membro length deve contenere le dimensioni del buffer. La funzione WinHttpCrackUrl copia il componente nel buffer e il membro length viene impostato sulla lunghezza del componente copiato, meno 1 per il carattere di terminazione della stringa finale. Se un buffer fornito dall'utente non è sufficientemente grande, WinHttpCrackUrl restituisce FALSEe GetLastError restituisce ERROR_INSUFFICIENT_BUFFER.

Affinché WinHttpCrackUrl funzioni correttamente, le dimensioni della struttura URL_COMPONENTS devono essere archiviate nel membro dwStructSize di tale struttura.

Se il protocollo Internet dell'URL passato per pwszUrl non è HTTP o HTTPS, winHttpCrackUrl restituisce false e GetLastError indica
ERROR_WINHTTP_UNRECOGNIZED_SCHEME.

winHttpCrackUrl non controlla la validità o il formato di un URL prima di tentare di violarlo. Di conseguenza, se viene passata una stringa come ""http://server?Bad=URL"", la funzione restituisce risultati non corretti.

Nota Per Windows XP e Windows 2000, vedi la sezione Requisiti Run-Time della pagina iniziale di WinHttp.

Esempi

In questo esempio viene illustrato come suddividere un URL nei relativi componenti, aggiornare un componente e quindi ricostruire l'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;
    }

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP, Windows 2000 Professional con SP3 [solo app desktop]
server minimo supportato	Windows Server 2003, Windows 2000 Server con SP3 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winhttp.h
libreria	Winhttp.lib
dll	Winhttp.dll
Ridistribuibile	WinHTTP 5.0 e Internet Explorer 5.01 o versione successiva in Windows XP e Windows 2000.

Vedere anche

Informazioni sui servizi HTTP Di Microsoft Windows (WinHTTP)

la gestione di localizzatori di risorse uniformi

versioni winHTTP

WinHttpCreateUrl

Condividi tramite