Funzione WinHttpCrackUrl (winhttp.h)

La funzione WinHttpCrackUrl separa un URL nelle parti del componente, ad esempio nome host e 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 romperlo.

[in] dwUrlLength

Lunghezza della stringa pwszUrl , in caratteri. Se dwUrlLength è impostato su zero, WinHttpCrackUrl presuppone che la stringa pwszUrl sia terminata con valore Null 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 bit per or insieme). In alternativa, il parametro può essere 0, che non esegue operazioni speciali.

[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 informazioni dettagliate sull'errore, chiamare GetLastError. Tra i codici di errore restituiti sono i seguenti.

Commenti

Anche quando WinHTTP viene usato in modalità asincrona, ovvero quando WINHTTP_FLAG_ASYNC è stato impostato in WinHttpOpen, questa funzione opera in modo sincrono. Il valore restituito indica l'esito positivo o negativo. Per informazioni dettagliate 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 per un componente sono uguali a zero, tale componente non viene restituito. Se il puntatore al valore del componente non è NULL e il valore del membro di lunghezza corrispondente è diverso da zero, l'indirizzo del primo carattere del componente corrispondente nella stringa pwszUrl viene archiviato 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 di lunghezza deve contenere le dimensioni del buffer. La funzione WinHttpCrackUrl copia il componente nel buffer e il membro di lunghezza viene impostato sulla lunghezza del componente copiato, meno 1 per il terminatore della stringa finale. Se un buffer fornito dall'utente non è sufficiente, WinHttpCrackUrl restituisce FALSE e GetLastError restituisce ERROR_INSUFFICIENT_BUFFER.

Per il corretto funzionamento di WinHttpCrackUrl , 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 romperlo. Di conseguenza, se una stringa come ""http://server?Bad=URL"" viene passata, la funzione restituisce risultati non corretti.

Esempio

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

Requisiti

Vedi anche

Informazioni su Microsoft Windows HTTP Services (WinHTTP)

Gestione di localizzatori di risorse uniformi

Versioni WinHTTP

WinHttpCreateUrl