UrlCombineA, fonction (shlwapi.h)

Article
08/26/2023

Lorsqu’elle est fournie avec une URL relative et sa base, retourne une URL sous forme canonique.

Syntaxe

LWSTDAPI UrlCombineA(
  [in]            PCSTR pszBase,
  [in]            PCSTR pszRelative,
  [out, optional] PSTR  pszCombined,
  [in, out]       DWORD *pcchCombined,
                  DWORD dwFlags
);

Paramètres

[in] pszBase

Type : PCTSTR

Pointeur vers une chaîne terminée par un caractère Null de longueur maximale INTERNET_MAX_URL_LENGTH qui contient l’URL de base.

[in] pszRelative

Type : PCTSTR

Pointeur vers une chaîne terminée par un caractère Null de longueur maximale INTERNET_MAX_URL_LENGTH qui contient l’URL relative.

[out, optional] pszCombined

Type : PTSTR

Pointeur vers une mémoire tampon qui, lorsque cette fonction retourne correctement, reçoit une chaîne terminée par null qui contient l’URL combinée.

[in, out] pcchCombined

Type : DWORD*

Pointeur vers une valeur qui, lors de l’entrée, est définie sur le nombre de caractères dans la mémoire tampon pszCombined . Lorsque la fonction retourne correctement, la valeur varie selon que la fonction réussit ou retourne E_POINTER. Pour les autres valeurs de retour, la valeur de ce paramètre n’a aucun sens.

dwFlags

Type : DWORD

Indicateurs qui spécifient la façon dont l’URL est convertie en forme canonique. Les indicateurs suivants peuvent être combinés.

URL_DONT_SIMPLIFY (0x08000000)

Traitez '/./' et '/.. /' dans une chaîne d’URL en tant que caractères littéraux, et non en tant que raccourci pour la navigation. Pour plus d’informations, voir Remarques.

URL_ESCAPE_PERCENT (0x00001000)

Convertissez toute occurrence de '%' en séquence d’échappement.

URL_ESCAPE_SPACES_ONLY (0x04000000)

Remplacez uniquement les espaces par des séquences d’échappement. Cet indicateur est prioritaire sur URL_ESCAPE_UNSAFE, mais ne s’applique pas aux URL opaques.

URL_ESCAPE_UNSAFE (0x20000000)

Remplacez les caractères non sécurisés par leurs séquences d’échappement. Les caractères non sécurisés sont les caractères qui peuvent être modifiés pendant le transport sur Internet, et incluent les caractères (<, , >#, {, }, |, ^, ~, [, ] et '). Cet indicateur s’applique à toutes les URL, y compris aux URL opaques.

URL_NO_META

Défini pour être identique à URL_DONT_SIMPLIFY.

URL_PLUGGABLE_PROTOCOL (0x40000000)

Combinez des URL avec des protocoles enfichables définis par le client, conformément à la spécification W3C. Cet indicateur ne s’applique pas à des protocoles standard comme ftp, http, gopher, etc. Si cet indicateur est défini, UrlCombine ne simplifie pas les URL. Il n’est donc pas nécessaire de définir également URL_DONT_SIMPLIFY.

URL_UNESCAPE (0x10000000)

Annulez l’échappement des séquences d’échappement que contiennent les URL, à deux exceptions près. Les séquences d’échappement pour « ? » et « # » ne sont pas sans échappement. Si l’un des indicateurs URL_ESCAPE_XXX est également défini, les deux URL sont d’abord sans échappement, puis combinées, puis placées dans une séquence d’échappement.

URL_ESCAPE_AS_UTF8 (0x00040000)

Windows 7 et versions ultérieures. Encodez en pourcentage tous les caractères non-ASCII en tant qu’équivalents UTF-8.

Valeur retournée

Type : HRESULT

Retourne les codes d’erreur COM standard, y compris les éléments suivants.

Code de retour	Description
S_OK	pszCombined pointe vers une chaîne qui contient les URL combinées. La valeur de pcchCombined est définie sur le nombre de caractères dans la chaîne, sans compter le caractère NULL de fin.
E_POINTER	La mémoire tampon était trop petite. La valeur de pcchCombined est définie sur le nombre minimal de caractères que la mémoire tampon doit être en mesure de contenir, y compris le caractère NULL de fin.

Remarques

Les éléments entre les barres obliques sont traités comme des identificateurs hiérarchiques ; le dernier élément spécifie le document lui-même. Vous devez entrer une barre oblique (/) après le nom du document pour ajouter d’autres éléments ; sinon, UrlCombine échange un document contre un autre. Par exemple :


hRetVal = UrlCombine(TEXT("http://xyz/test/abc"), 
                     TEXT("bar"), 
                     lpszCombined, 
                     &dwLength, 0);

Le code précédent retourne l’URL http://xyz/test/bar. Si vous souhaitez que l’URL combinée soit http://xyz/test/abc/bar, utilisez l’appel suivant à UrlCombine.


hRetVal = UrlCombine(TEXT("http://xyz/test/abc/"), 
                     TEXT("bar"), 
                     lpszCombined, 
                     &dwLength, 0);

Si une chaîne d’URL contient '/.. /' ou '/./', UrlCombine traite généralement les caractères comme s’ils indiquaient la navigation dans la hiérarchie d’URL. La fonction simplifie les URL avant de les combiner. Pour instance, « /hello/cruel/.. /world » est simplifié en « /hello/world ». Si l’indicateur URL_DONT_SIMPLIFY est défini dans dwFlags, la fonction ne simplifie pas les URL. Dans ce cas, « /hello/cruel/.. /world » est laissé tel qu’il est.

Notes

L’en-tête shlwapi.h définit UrlCombine en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel, Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	shlwapi.h
Bibliothèque	Shlwapi.lib
DLL	Shlwapi.dll (version 5.0 ou ultérieure)

Voir aussi

Gestion des localisateurs de ressources uniformes

UrlCanonicalize

Partager via