UrlCombineW, fonction (shlwapi.h)

Article
11/20/2024

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

Syntaxe

LWSTDAPI UrlCombineW(
  [in]            PCWSTR pszBase,
  [in]            PCWSTR pszRelative,
  [out, optional] PWSTR  pszCombined,
  [in, out]       DWORD  *pcchCombined,
                  DWORD  dwFlags
);

Paramètres

[in] pszBase

Type : PCTSTR

Pointeur vers une chaîne terminée par 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 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éfini sur le nombre de caractères dans la mémoire tampon pszCombined. Lorsque la fonction est retournée avec succès, 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 est sans signification.

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, pas comme raccourci pour la navigation. Pour plus d’informations, consultez les 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 ceux 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 les URL opaques.

URL_NO_META

Défini comme étant 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 aux protocoles standard tels que 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 URL_DONT_SIMPLIFY.

URL_UNESCAPE (0x10000000)

Annulez l’échappement des séquences d’échappement que les URL contiennent, avec deux exceptions. Les séquences d’échappement pour « ? » et « # » ne sont pas échappées. Si l’un des indicateurs URL_ESCAPE_XXX est également défini, les deux URL sont d’abord non échappées, puis combinées, puis échappées.

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 de retour

Type : HRESULT

Retourne les codes d’erreur COM standard, notamment les suivants.

Retourner le code	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 de la chaîne, sans compter la fin caractère null.
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 contenir, y compris la fin caractère NULL.

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 pour 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 pour 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 indiquent la navigation dans la hiérarchie d’URL. La fonction simplifie les URL avant de les combiner. Par exemple, « /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é comme c’est le cas.

Note

L’en-tête shlwapi.h définit UrlCombine comme 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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel, Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’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