Función UrlEscapeW (shlwapi.h)
Convierte caracteres o pares suplentes en una dirección URL que se puede modificar durante el transporte a través de Internet (caracteres "no seguros") en sus secuencias de escape correspondientes. Los pares suplentes son caracteres entre U+10000 y U+10FFFF (en UTF-32) o entre DC00 a DFFF (en UTF-16).
Sintaxis
LWSTDAPI UrlEscapeW(
[in] PCWSTR pszUrl,
[out] PWSTR pszEscaped,
[in, out] DWORD *pcchEscaped,
DWORD dwFlags
);
Parámetros
[in] pszUrl
Tipo: PCTSTR
Cadena terminada en null de longitud máxima INTERNET_MAX_URL_LENGTH que contiene una dirección URL completa o parcial, según corresponda para el valor de dwFlags.
[out] pszEscaped
Tipo: PTSTR de
Búfer que recibe la cadena convertida, con los caracteres no seguros convertidos en sus secuencias de escape.
[in, out] pcchEscaped
Tipo: DWORD* de
Puntero a un valor de DWORD que, en la entrada, contiene el número de caracteres del búfer de pszEscaped. Antes de llamar a UrlEscape, la aplicación que realiza la llamada debe establecer el valor al que hace referencia pcchEscaped al tamaño del búfer. Cuando esta función se devuelve correctamente, el valor recibe el número de caracteres escritos en el búfer, no incluida la terminación carácter null.
Si se devuelve un código de error E_POINTER, el búfer era demasiado pequeño para contener el resultado y el valor al que hace referencia pcchEscaped se establece en el número necesario de caracteres del búfer. Si se devuelven otros errores, el valor al que hace referencia pcchEscaped no está definido.
dwFlags
Tipo: DWORD de
Marcas que indican qué parte de la dirección URL se proporciona en pszURL y qué caracteres de esa cadena se deben convertir en sus secuencias de escape. Se definen las marcas siguientes.
URL_DONT_ESCAPE_EXTRA_INFO (0x02000000)
Solo se usa junto con URL_ESCAPE_SPACES_ONLY para evitar la conversión de caracteres en la consulta (la parte de la dirección URL después del primer # o ? carácter encontrado en la cadena). Esta marca no debe usarse sola ni combinarse con URL_ESCAPE_SEGMENT_ONLY.
URL_BROWSER_MODE
Se define para que sea el mismo que URL_DONT_ESCAPE_EXTRA_INFO.
URL_ESCAPE_SPACES_ONLY (0x04000000)
Convierta solo los caracteres de espacio en sus secuencias de escape, incluidos los caracteres de espacio de la parte de consulta de la dirección URL. Otros caracteres no seguros no se convierten en sus secuencias de escape. Esta marca supone que pszURL no contiene una dirección URL completa. Solo espera las partes que siguen a la especificación del servidor.
Combine esta marca con URL_DONT_ESCAPE_EXTRA_INFO para evitar la conversión de caracteres de espacio en la parte de consulta de la dirección URL.
Esta marca no se puede combinar con URL_ESCAPE_PERCENT o URL_ESCAPE_SEGMENT_ONLY.
URL_ESCAPE_PERCENT (0x00001000)
Convierta cualquier carácter de % que se encuentre en la sección de segmento de la dirección URL (esa sección se encuentra entre la especificación del servidor y el primer carácter # o ? ). De forma predeterminada, el carácter % no se convierte en su secuencia de escape. Otros caracteres no seguros del segmento también se convierten normalmente.
La combinación de esta marca con URL_ESCAPE_SEGMENT_ONLY incluye esos caracteres % en la parte de consulta de la dirección URL. Sin embargo, como la marca de URL_ESCAPE_SEGMENT_ONLY hace que toda la cadena se considere el segmento, cualquier número o ? También se convierten caracteres.
Esta marca no se puede combinar con URL_ESCAPE_SPACES_ONLY.
URL_ESCAPE_SEGMENT_ONLY (0x00002000)
Indica que pszURL contiene solo esa sección de la dirección URL que sigue al componente de servidor, pero que precede a la consulta. Todos los caracteres no seguros de la cadena se convierten. Si se proporciona una dirección URL completa cuando se establece esta marca, se convierten todos los caracteres no seguros de toda la cadena, incluidos # y ? Caracteres.
Combine esta marca con URL_ESCAPE_PERCENT para incluir ese carácter en la conversión.
Esta marca no se puede combinar con URL_ESCAPE_SPACES_ONLY o URL_DONT_ESCAPE_EXTRA_INFO.
URL_ESCAPE_AS_UTF8 (0x00040000)
Windows 7 y versiones posteriores. Codifique por porcentaje todos los caracteres no ASCII como equivalentes UTF-8.
URL_ESCAPE_ASCII_URI_COMPONENT (0x00080000)
Windows 8 y versiones posteriores. Codifique por porcentaje todos los caracteres ASCII fuera del conjunto no servido desde el URI RFC 3986 (a-zA-Z0-9-.~_).
Valor devuelto
Tipo: HRESULT
Devuelve S_OK si se ejecuta correctamente. Si el búfer de
Observaciones
Para los fines de este documento, una dirección URL típica se divide en tres secciones: el servidor, el segmento y la consulta. Por ejemplo:
http://microsoft.com/test.asp?url=/example/abc.asp?frame=true#fragment
La parte del servidor es "http://microsoft.com/". La barra diagonal final se considera parte de la parte del servidor.
La parte del segmento es cualquier parte de la ruta de acceso que se encuentra después de la parte del servidor, pero antes del primer # o ? carácter, en este caso simplemente "test.asp".
La parte de consulta es el resto de la ruta de acceso del primer # o ? carácter (inclusivo) al final. En el ejemplo, es "?url=/example/abc.asp?frame=true#fragment".
Los caracteres no seguros son aquellos caracteres que se pueden modificar durante el transporte a través de Internet. Esta función convierte caracteres no seguros en sus secuencias de escape "%xy" equivalentes. En la tabla siguiente se muestran caracteres no seguros y sus secuencias de escape.
| Carácter | Secuencia de escape |
|---|---|
| ^ | %5E |
| & | %26 |
| ` | %60 |
| { | %7B |
| } | %7D |
| | | %7C |
| ] | %5D |
| [ | %5B |
| " | %22 |
| < | %3C |
| > | %3E |
| \ | %5C |
El uso de la marca URL_ESCAPE_SEGMENT_ONLY también hace que la conversión de # (%23), ? (%3F), y / (%2F) caracteres.
De forma predeterminada, UrlEscape omite cualquier texto que siga a un # o ? carácter. La marca URL_ESCAPE_SEGMENT_ONLY invalida este comportamiento con respecto a toda la cadena como el segmento. La marca URL_ESCAPE_SPACES_ONLY invalida este comportamiento, pero solo para caracteres de espacio.
Ejemplos
En los ejemplos siguientes se muestra el efecto de las distintas marcas en una dirección URL. La dirección URL de ejemplo no es válida, pero se exagera con fines de demostración.
// 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
El encabezado shlwapi.h define UrlEscape como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows 2000 Server [solo aplicaciones de escritorio] |
| de la plataforma de destino de |
Windows |
| encabezado de |
shlwapi.h |
| biblioteca de |
Shlwapi.lib |
| DLL de |
Shlwapi.dll (versión 5.0 o posterior) |