Funzione UrlCombineA (shlwapi.h)
Se fornito con un URL relativo e la relativa base, restituisce un URL in formato canonico.
Sintassi
LWSTDAPI UrlCombineA(
[in] PCSTR pszBase,
[in] PCSTR pszRelative,
[out, optional] PSTR pszCombined,
[in, out] DWORD *pcchCombined,
DWORD dwFlags
);
Parametri
[in] pszBase
Tipo: PCTSTR
Puntatore a una stringa con terminazione null di lunghezza massima INTERNET_MAX_URL_LENGTH contenente l'URL di base.
[in] pszRelative
Tipo: PCTSTR
Puntatore a una stringa con terminazione null di lunghezza massima INTERNET_MAX_URL_LENGTH contenente l'URL relativo.
[out, optional] pszCombined
Tipo: PTSTR
Puntatore a un buffer che, quando questa funzione restituisce correttamente, riceve una stringa con terminazione null contenente l'URL combinato.
[in, out] pcchCombined
Tipo: DWORD*
Puntatore a un valore impostato sul numero di caratteri nel buffer pszCombined . Quando la funzione restituisce correttamente, il valore dipende dal fatto che la funzione abbia esito positivo o restituisca E_POINTER. Per altri valori restituiti, il valore di questo parametro è senza significato.
dwFlags
Tipo: DWORD
Flag che specificano come l'URL viene convertito in formato canonico. È possibile combinare i flag seguenti.
URL_DONT_SIMPLIFY (0x08000000)
Trattare '/./' e '/.. /' in una stringa URL come caratteri letterali, non come shorthand per la navigazione. Per altre discussioni, vedere Osservazioni.
URL_ESCAPE_PERCENT (0x00001000)
Convertire qualsiasi occorrenza di '%' nella sequenza di escape.
URL_ESCAPE_SPACES_ONLY (0x04000000)
sostituisce solo gli spazi con sequenze di escape. Questo flag ha la precedenza su URL_ESCAPE_UNSAFE, ma non si applica agli URL opachi.
URL_ESCAPE_UNSAFE (0x20000000)
sostituisce i caratteri non sicuri con le rispettive sequenze di escape. I caratteri non sicuri sono i caratteri che possono essere modificati durante il trasporto su Internet e includono i caratteri (<, >, {, }, |, ^, ~, [, ], e '). Questo flag si applica a tutti gli URL, inclusi gli URL opachi.
URL_NO_META
Definito come URL_DONT_SIMPLIFY.
URL_PLUGGABLE_PROTOCOL (0x40000000)
Combinare GLI URL con i protocolli pluggable definiti dal client, in base alla specifica W3C. Questo flag non si applica ai protocolli standard, come ftp, http, gopher e così via. Se questo flag è impostato, UrlCombine non semplifica gli URL, quindi non è necessario impostare anche URL_DONT_SIMPLIFY.
URL_UNESCAPE (0x10000000)
Annullare l'escape di qualsiasi sequenza di escape che gli URL contengono, con due eccezioni. Le sequenze di escape per '?' e '#' non vengono eliminate. Se viene impostato anche uno dei flag di URL_ESCAPE_XXX, i due URL vengono prima non in escape, quindi combinati, quindi escape.
URL_ESCAPE_AS_UTF8 (0x00040000)
Windows 7 e versioni successive. Codifica per percentuale tutti i caratteri non ASCII come equivalenti UTF-8.
Valore restituito
Tipo: HRESULT
Restituisce codici di errore COM standard, inclusi i seguenti.
Codice restituito | Descrizione |
---|---|
|
pszCombined punta a una stringa contenente gli URL combinati. Il valore di pcchCombined è impostato sul numero di caratteri nella stringa, senza contare il carattere NULL terminante. |
|
Il buffer era troppo piccolo. Il valore di pcchCombined è impostato sul numero minimo di caratteri che il buffer deve essere in grado di contenere, incluso il carattere NULL terminante. |
Commenti
Gli elementi tra le barre vengono trattati come identificatori gerarchici; l'ultimo elemento specifica il documento stesso. È necessario immettere una barra (/) dopo il nome del documento per aggiungere altri elementi; in caso contrario , UrlCombine scambia un documento per un altro. Ad esempio:
hRetVal = UrlCombine(TEXT("http://xyz/test/abc"),
TEXT("bar"),
lpszCombined,
&dwLength, 0);
Il codice precedente restituisce l'URL http://xyz/test/bar. Se si vuole che l'URL combinato sia http://xyz/test/abc/bar, usare la chiamata seguente a UrlCombine.
hRetVal = UrlCombine(TEXT("http://xyz/test/abc/"),
TEXT("bar"),
lpszCombined,
&dwLength, 0);
Se una stringa URL contiene '/.. /' o '/./', UrlCombine considera in genere i caratteri come se indicassero lo spostamento nella gerarchia di URL. La funzione semplifica gli URL prima di combinarli. Ad esempio, "/hello/crudele/.. /world" è semplificato in "/hello/world". Se il flag URL_DONT_SIMPLIFY è impostato in dwFlags, la funzione non semplifica gli URL. In questo caso, "/hello/crudele/.. /world" è lasciato così come è.
Nota
L'intestazione shlwapi.h definisce UrlCombine come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.
Requisiti
Requisito | Valore |
---|---|
Client minimo supportato | Windows 2000 Professional, Windows XP [solo app desktop] |
Server minimo supportato | Windows 2000 Server [solo app desktop] |
Piattaforma di destinazione | Windows |
Intestazione | shlwapi.h |
Libreria | Shlwapi.lib |
DLL | Shlwapi.dll (versione 5.0 o successiva) |