WinHttpCrackUrl, fonction (winhttp.h)
La fonction WinHttpCrackUrl sépare une URL en ses composants, comme le nom d’hôte et le chemin d’accès.
Syntaxe
WINHTTPAPI BOOL WinHttpCrackUrl(
[in] LPCWSTR pwszUrl,
[in] DWORD dwUrlLength,
[in] DWORD dwFlags,
[in, out] LPURL_COMPONENTS lpUrlComponents
);
Paramètres
[in] pwszUrl
Pointeur vers une chaîne qui contient l’URL canonique à séparer. WinHttpCrackUrl ne vérifie pas cette URL pour la validité ou le format correct avant de tenter de le fissurer.
[in] dwUrlLength
Longueur de la chaîne pwszUrl, en caractères. Si dwUrlLength est défini sur zéro, WinHttpCrackUrl suppose que la chaîne pwszUrl est null terminée et détermine la longueur de la chaîne pwszUrl en fonction de cette hypothèse.
[in] dwFlags
Indicateurs qui contrôlent l’opération. Ce paramètre peut être une combinaison d’un ou plusieurs indicateurs suivants (les valeurs peuvent être combinées au niveau du bit OR’d). Ou bien, le paramètre peut être 0, qui n’effectue aucune opération spéciale.
| Valeur | Signification |
|---|---|
|
Convertit les caractères « encodés d’échappement » (%xx) en leur forme non échapée. Cela ne décode pas d’autres encodages, tels que UTF-8. Cette fonctionnalité ne peut être utilisée que si l’utilisateur fournit des mémoires tampons dans la structure URL_COMPONENTS pour copier les composants. |
|
Échappe certains caractères à leurs séquences d’échappement (%xx). Les caractères à échapper sont des caractères non ASCII ou ceux qui doivent être placés dans une requête HTTP. Cette fonctionnalité ne peut être utilisée que si l’utilisateur fournit des mémoires tampons dans la structure URL_COMPONENTS pour copier les composants. |
|
Rejette les URL comme entrée qui contiennent des informations d’identification incorporées (un nom d’utilisateur, un mot de passe ou les deux). Si la fonction échoue en raison d’une URL non valide, les appels suivants à GetLastError retournent ERROR_WINHTTP_INVALID_URL. |
[in, out] lpUrlComponents
Pointeur vers une structure URL_COMPONENTS qui reçoit les composants d’URL.
Valeur de retour
Retourne TRUE si la fonction réussit, ou FALSE sinon. Pour obtenir des informations d’erreur étendues, appelez GetLastError. Parmi les codes d’erreur retournés, voici ce qui suit.
| Codes d’erreur | Description |
|---|---|
|
Une erreur interne s’est produite. |
|
L’URL n’est pas valide. |
|
Le schéma d’URL n’a pas pu être reconnu ou n’est pas pris en charge. |
|
La mémoire n’a pas été suffisante pour terminer l’opération demandée. (Code d’erreur Windows) |
Remarques
Même quand WinHTTP est utilisé en mode asynchrone (autrement dit, lorsque WINHTTP_FLAG_ASYNC a été défini dans WinHttpOpen), cette fonction fonctionne de façon synchrone. La valeur de retour indique la réussite ou l’échec. Pour obtenir des informations d’erreur étendues, appelez GetLastError.
Les composants requis sont indiqués par les membres de la structure URL_COMPONENTS. Chaque composant a un pointeur vers la valeur et a un membre qui stocke la longueur de la valeur stockée. Si la valeur et la longueur d’un composant sont égales à zéro, ce composant n’est pas retourné. Si le pointeur vers la valeur du composant est
Si le pointeur contient l’adresse de la mémoire tampon fournie par l’utilisateur, le membre de longueur doit contenir la taille de la mémoire tampon. La fonction WinHttpCrackUrl copie le composant dans la mémoire tampon, et le membre de longueur est défini sur la longueur du composant copié, moins 1 pour la fin de chaîne de fin de fin. Si une mémoire tampon fournie par l’utilisateur n’est pas suffisamment grande, WinHttpCrackUrl retourne faux, et GetLastError retourne ERROR_INSUFFICIENT_BUFFER.
Pour que WinHttpCrackUrl fonctionne correctement, la taille de la structure URL_COMPONENTS doit être stockée dans le membre dwStructSize de cette structure.
Si le protocole Internet de l’URL transmise pour pwszUrl n’est pas HTTP ou HTTPS, WinHttpCrackUrl retourne FAUX et GetLastError indique
ERROR_WINHTTP_UNRECOGNIZED_SCHEME.
WinHttpCrackUrl ne vérifie pas la validité ou le format d’une URL avant de tenter de la fissurer. Par conséquent, si une chaîne telle que « »http://server?Bad=URL" » est passée, la fonction retourne des résultats incorrects.
Exemples
Cet exemple montre comment décomposer une URL dans ses composants, mettre à jour un composant, puis reconstruire 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;
}
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP, Windows 2000 Professionnel avec SP3 [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003, Windows 2000 Server avec SP3 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | winhttp.h |
| bibliothèque | Winhttp.lib |
| DLL | Winhttp.dll |
| redistribuable | WinHTTP 5.0 et Internet Explorer 5.01 ou version ultérieure sur Windows XP et Windows 2000. |
Voir aussi
à propos des services HTTP Microsoft Windows (WinHTTP)