Función UrlEscapeA (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 UrlEscapeA(
  [in]      PCSTR pszUrl,
  [out]     PSTR  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

Búfer que recibe la cadena convertida, con los caracteres no seguros convertidos en sus secuencias de escape.

[in, out] pcchEscaped

Tipo: DWORD*

Puntero a un valor DWORD que, en la entrada, contiene el número de caracteres en el búfer pszEscaped . Antes de llamar a UrlEscape, la aplicación que realiza la llamada debe establecer el valor al que hace referencia pcchEscaped en el tamaño del búfer. Cuando esta función devuelve correctamente, el valor recibe el número de caracteres escritos en el búfer, no incluido el carácter NULL de terminación.

Si se devuelve un código de error de 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 en el búfer. Si se devuelven otros errores, el valor al que hace referencia pcchEscaped no está definido.

dwFlags

Tipo: DWORD

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 que sigue al primer carácter # o ? 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 igual que URL_DONT_ESCAPE_EXTRA_INFO.

URL_ESCAPE_SPACES_ONLY (0x04000000)

Convierta solo 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. Espera solo 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 % 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 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 solo contiene 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 ? .

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 sus 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 de URI RFC 3986 (a-zA-Z0-9-.~_).

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si se ejecuta correctamente. Si el búfer pcchEscaped era demasiado pequeño para contener el resultado, se devuelve E_POINTER y el valor al que apunta pcchEscaped se establece en el tamaño de búfer necesario. De lo contrario, se devuelve un valor de error estándar.

Comentarios

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 número o ? carácter, en este caso simplemente "test.asp".

La parte de la consulta es el resto de la ruta de acceso del primer número o ? carácter (inclusivo) al final. En el ejemplo, es "?url=/example/abc.asp?frame=true#fragment".

Los caracteres no seguros son aquellos que se pueden modificar durante el transporte a través de Internet. Esta función convierte caracteres no seguros en sus secuencias de escape equivalentes "%xy". En la tabla siguiente se muestran caracteres no seguros y sus secuencias de escape.

El uso de la marca URL_ESCAPE_SEGMENT_ONLY también provoca la conversión de # (%23), ? (%3F) y / (%2F) caracteres.

De forma predeterminada, UrlEscape omite cualquier texto que siga a un # o ? . La marca URL_ESCAPE_SEGMENT_ONLY invalida este comportamiento con respecto a toda la cadena como 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

Requisitos

Consulte también

Control de localizadores uniformes de recursos