Funzione UrlEscapeW (shlwapi.h)
Converte caratteri o coppie di surrogati in un URL che potrebbe essere modificato durante il trasporto attraverso Internet ("caratteri non sicuri") nelle sequenze di escape corrispondenti. Le coppie di surrogati sono caratteri compresi tra U+10000 e U+10FFFF (in UTF-32) o tra DC00 e DFFF (in UTF-16).
Sintassi
LWSTDAPI UrlEscapeW(
[in] PCWSTR pszUrl,
[out] PWSTR pszEscaped,
[in, out] DWORD *pcchEscaped,
DWORD dwFlags
);
Parametri
[in] pszUrl
Tipo: PCTSTR
Stringa con terminazione Null di lunghezza massima INTERNET_MAX_URL_LENGTH che contiene un URL completo o parziale, come appropriato per il valore in dwFlags.
[out] pszEscaped
Tipo: PTSTR
Buffer che riceve la stringa convertita, con i caratteri non sicuri convertiti nelle sequenze di escape.
[in, out] pcchEscaped
Tipo: DWORD*
Puntatore a un valore
Se viene restituito un codice di errore E_POINTER, il buffer era troppo piccolo per contenere il risultato e il valore a cui fa riferimento pcchEscaped viene impostato sul numero di caratteri richiesto nel buffer. Se vengono restituiti altri errori, il valore a cui fa riferimento pcchEscaped non è definito.
dwFlags
Tipo: DWORD
Flag che indicano quale parte dell'URL viene fornita in pszURL e quali caratteri in tale stringa devono essere convertiti nelle sequenze di escape. Vengono definiti i flag seguenti.
URL_DONT_ESCAPE_EXTRA_INFO (0x02000000)
Usato solo in combinazione con URL_ESCAPE_SPACES_ONLY per impedire la conversione dei caratteri nella query (la parte dell'URL che segue il primo # o ? carattere rilevato nella stringa). Questo flag non deve essere usato da solo, né combinato con URL_ESCAPE_SEGMENT_ONLY.
URL_BROWSER_MODE
Definito come uguale a URL_DONT_ESCAPE_EXTRA_INFO.
URL_ESCAPE_SPACES_ONLY (0x04000000)
Convertire solo i caratteri di spazio nelle sequenze di escape, inclusi questi caratteri di spazio nella parte query dell'URL. Altri caratteri non sicuri non vengono convertiti nelle sequenze di escape. Questo flag presuppone che pszURL non contenga un URL completo. Prevede solo le parti che seguono la specifica del server.
Combinare questo flag con URL_DONT_ESCAPE_EXTRA_INFO per impedire la conversione di caratteri di spazio nella parte query dell'URL.
Questo flag non può essere combinato con URL_ESCAPE_PERCENT o URL_ESCAPE_SEGMENT_ONLY.
URL_ESCAPE_PERCENT (0x00001000)
Convertire qualsiasi carattere % trovato nella sezione segmento dell'URL (quella sezione che cade tra la specifica del server e il primo carattere # o ? ). Per impostazione predefinita, il carattere % non viene convertito nella sequenza di escape. Anche altri caratteri non sicuri nel segmento vengono convertiti normalmente.
La combinazione di questo flag con URL_ESCAPE_SEGMENT_ONLY include i caratteri % nella parte della query dell'URL. Tuttavia, poiché il flag URL_ESCAPE_SEGMENT_ONLY fa in modo che l'intera stringa venga considerata il segmento, qualsiasi # o ? vengono convertiti anche caratteri.
Questo flag non può essere combinato con URL_ESCAPE_SPACES_ONLY.
URL_ESCAPE_SEGMENT_ONLY (0x00002000)
Indica che pszURL contiene solo la sezione dell'URL che segue il componente server, ma precede la query. Tutti i caratteri non sicuri nella stringa vengono convertiti. Se viene fornito un URL completo quando questo flag è impostato, tutti i caratteri non sicuri nell'intera stringa vengono convertiti, inclusi # e ? personaggi.
Combinare questo flag con URL_ESCAPE_PERCENT per includere tale carattere nella conversione.
Questo flag non può essere combinato con URL_ESCAPE_SPACES_ONLY o URL_DONT_ESCAPE_EXTRA_INFO.
URL_ESCAPE_AS_UTF8 (0x00040000)
Windows 7 e versioni successive. Codifica in percentuale tutti i caratteri non ASCII come equivalenti UTF-8.
URL_ESCAPE_ASCII_URI_COMPONENT (0x00080000)
Windows 8 e versioni successive. Codificare in percentuale tutti i caratteri ASCII al di fuori del set non valido da URI RFC 3986 (a-zA-Z0-9-.~_).
Valore restituito
Tipo: HRESULT
Restituisce S_OK in caso di esito positivo. Se il buffer pcchEscaped
Osservazioni
Ai fini di questo documento, un URL tipico è suddiviso in tre sezioni: il server, il segmento e la query. Per esempio:
http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment
La parte del server è "http://microsoft.com/". La barra finale viene considerata parte della parte del server.
La parte del segmento fa parte del percorso trovato dopo la parte del server, ma prima del primo # o ? carattere, in questo caso semplicemente "test.asp".
La parte della query è il resto del percorso dal primo oggetto # o ? carattere (inclusivo) alla fine. Nell'esempio è "?url=/example/abc.asp?frame=true#fragment".
I caratteri non sicuri sono i caratteri che potrebbero essere modificati durante il trasporto attraverso Internet. Questa funzione converte i caratteri non sicuri nelle sequenze di escape "%xy" equivalenti. La tabella seguente mostra i caratteri non sicuri e le relative sequenze di escape.
| Carattere | Sequenza di escape |
|---|---|
| ^ | %5E |
| & | %26 |
| ` | %60 |
| { | %7B |
| } | %7D |
| | | %7C |
| ] | %5D |
| [ | %5B |
| " | %22 |
| < | %3C |
| > | %3E |
| \ | %5C |
L'uso del flag URL_ESCAPE_SEGMENT_ONLY causa anche la conversione di # (%23), ? (%3F) e / (%2F) caratteri.
Per impostazione predefinita, urlEscape ignora qualsiasi testo che segue # o ? carattere. Il flag URL_ESCAPE_SEGMENT_ONLY esegue l'override di questo comportamento in relazione all'intera stringa come segmento. Il flag URL_ESCAPE_SPACES_ONLY esegue l'override di questo comportamento, ma solo per gli spazi.
Esempi
Negli esempi seguenti viene illustrato l'effetto dei vari flag in un URL. L'URL di esempio non è valido, ma è esagerato a scopo dimostrativo.
// The full original URL
http://microsoft.com/test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY
// Only space characters are escaped. Other unsafe characters are ignored.
// Note: This flag expects the server portion of the URL to be omitted.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex%%20ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SPACES_ONLY | URL_DONT_ESCAPE_EXTRA_INFO
// Spaces in the segment are converted into their escape sequences, but
// spaces in the query are not.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%e<s%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_PERCENT
// Here only the segment and query are supplied and the server component is
// omitted, although that is not required. Only the segment is considered.
// All unsafe characters plus the % character are converted in the segment.
Original = test/t%e<s t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
Result = test/t%25e%3Cs%20t.asp?url=/{ex% ample</abc.asp?frame=true#fr%agment
// URL_ESCAPE_SEGMENT_ONLY
// Note: This flag expects only the segment, omitting the server and query
// components.
// The / character is escaped as well as the usual unsafe characters.
Original = test/t%e<s t.asp
Result = test%2Ft%e%3Cs%20t.asp
Nota
L'intestazione shlwapi.h definisce UrlEscape come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| 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 | Finestre |
| intestazione |
shlwapi.h |
| libreria |
Shlwapi.lib |
| dll | Shlwapi.dll (versione 5.0 o successiva) |