Uniform Resource Locators (URL) dans WinHTTP

Une URL est une représentation compacte de l’emplacement et de la méthode d’accès pour une ressource située sur Internet. Chaque URL se compose d’un schéma (HTTP, HTTPS, FTP ou Gopher) et d’une chaîne spécifique au schéma. Cette chaîne peut également inclure une combinaison d’un chemin d’accès au répertoire, d’une chaîne de recherche ou d’un nom de la ressource. Les fonctions Microsoft Windows HTTP Services (WinHTTP) permettent de créer, combiner, décomposer et canoniser des URL. Pour plus d’informations, consultez RFC 1738, Uniform Resource Locators et RFC 2396, Uniform Resource Identifiers (URI) : Syntaxe générique.

Qu’est-ce qu’une URL canonique ?

La syntaxe et la sémantique spécifiées des URL laissent place à la variation et à l’erreur. La canonisation est le processus de normalisation d’une URL réelle dans une forme « canonique » standard correcte.

Cela implique le codage de certains caractères en tant que « séquences d’échappement ». Les caractères US-ASCII alphanumériques n’ont pas besoin d’être encodés (les chiffres 0-9, les lettres majuscules A à Z et les lettres minuscules a-z). La plupart des autres caractères doivent être placés dans une séquence d’échappement, y compris les caractères de contrôle, l’espace, le signe de pourcentage, les « caractères non sécurisés » ( <, >, « , # , {, }, |, \, ^, ~, [, ] et ' ), et tous les caractères dont le point de code est supérieur à 127.

Utilisation des fonctions WinHTTP pour gérer les URL

WinHTTP fournit deux fonctions pour gérer les URL. WinHttpCrackUrl sépare une URL en ses composants, et WinHttpCreateUrl crée une URL à partir de composants.

Séparation des URL

La fonction WinHttpCrackUrl sépare une URL en ses composants et retourne les composants indiqués par la structure URL_COMPONENTS qui est passée à la fonction.

Les composants qui composent la structure URL_COMPONENTS sont le numéro de schéma, le nom d’hôte, le numéro de port, le nom d’utilisateur, le mot de passe, le chemin d’URL et des informations supplémentaires telles que les paramètres de recherche. Chaque composant, à l’exception du schéma et des numéros de port, a un membre de chaîne qui contient les informations et un membre qui contient la longueur du membre de chaîne. Le schéma et les numéros de port ont uniquement un membre qui stocke la valeur correspondante ; Le schéma et les numéros de port sont retournés sur tous les appels réussis à WinHttpCrackUrl.

Pour récupérer la valeur d’un composant particulier dans la structure URL_COMPONENTS , le membre qui stocke la longueur de chaîne de ce composant doit être défini sur une valeur différente de zéro. Le membre de chaîne peut être un pointeur vers une mémoire tampon ou NULL.

Si le membre pointeur contient un pointeur vers une mémoire tampon, le membre de longueur de chaîne doit contenir la taille de cette mémoire tampon. La fonction WinHttpCrackUrl retourne les informations du composant sous forme de chaîne dans la mémoire tampon et stocke la longueur de la chaîne dans le membre de longueur de chaîne.

Si le membre pointeur est défini sur NULL, le membre de longueur de chaîne peut être défini sur n’importe quelle valeur différente de zéro. La fonction WinHttpCrackUrl stocke un pointeur vers le premier caractère de la chaîne d’URL qui contient les informations du composant et définit la longueur de la chaîne sur le nombre de caractères dans la partie restante de la chaîne d’URL qui se rapporte au composant.

Tous les membres pointeurs définis sur NULL avec un membre de longueur différente de zéro pointent vers le point de départ approprié dans la chaîne d’URL. La longueur stockée dans le membre de longueur doit être utilisée pour déterminer la fin des informations du composant individuel.

Pour terminer correctement l’initialisation de la structure URL_COMPONENTS , le membre dwStructSize doit être défini sur la taille de la structure URL_COMPONENTS .

Création d’URL

La fonction WinHttpCreateUrl utilise les informations de la structure URL_COMPONENTS décrite précédemment pour créer une URL.

Pour chaque composant requis, le membre de pointeur doit contenir un pointeur vers la mémoire tampon qui contient les informations. Le membre de longueur doit être défini sur zéro si le membre pointeur contient un pointeur vers une chaîne terminée à zéro ; le membre de longueur doit être défini sur la longueur de chaîne si le membre pointeur contient un pointeur vers une chaîne qui n’est pas terminée à zéro. Le membre pointeur de tous les composants qui ne sont pas requis doit avoir la valeur NULL.

Exemple de code

L’exemple de code suivant montre comment utiliser WinHttpCrackUrl et WinHttpCreateUrl pour désassembler une URL existante, modifier l’un de ses composants et la réassembler dans une nouvelle URL.

  URL_COMPONENTS urlComp;
  LPCWSTR pwszUrl1 = 
    L"https://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;
  }