Compartir a través de

Función UrlCombineA (shlwapi.h)

  • Artículo

Cuando se proporciona con una dirección URL relativa y su base, devuelve una dirección URL en forma canónica.

Sintaxis

LWSTDAPI UrlCombineA(
  [in]            PCSTR pszBase,
  [in]            PCSTR pszRelative,
  [out, optional] PSTR  pszCombined,
  [in, out]       DWORD *pcchCombined,
                  DWORD dwFlags
);

Parámetros

[in] pszBase

Tipo: PCTSTR

Puntero a una cadena terminada en null de longitud máxima INTERNET_MAX_URL_LENGTH que contiene la dirección URL base.

[in] pszRelative

Tipo: PCTSTR

Puntero a una cadena terminada en null de longitud máxima INTERNET_MAX_URL_LENGTH que contiene la dirección URL relativa.

[out, optional] pszCombined

Tipo: PTSTR

Puntero a un búfer que, cuando esta función devuelve correctamente, recibe una cadena terminada en NULL que contiene la dirección URL combinada.

[in, out] pcchCombined

Tipo: DWORD*

Puntero a un valor que, en la entrada, se establece en el número de caracteres del búfer pszCombined . Cuando la función se devuelve correctamente, el valor depende de si la función es correcta o devuelve E_POINTER. Para otros valores devueltos, el valor de este parámetro no tiene sentido.

dwFlags

Tipo: DWORD

Marcas que especifican cómo se convierte la dirección URL en forma canónica. Se pueden combinar las marcas siguientes.

URL_DONT_SIMPLIFY (0x08000000)

Trate '/./' y '/.. /' en una cadena de dirección URL como caracteres literales, no como abreviatura para la navegación. Vea comentarios para obtener más información.

URL_ESCAPE_PERCENT (0x00001000)

Convierta cualquier aparición de '%' en su secuencia de escape.

URL_ESCAPE_SPACES_ONLY (0x04000000)

solo reemplaza los espacios por secuencias de escape. Esta marca tiene prioridad sobre URL_ESCAPE_UNSAFE, pero no se aplica a direcciones URL opacas.

URL_ESCAPE_UNSAFE (0x20000000)

reemplaza los caracteres no seguros por sus secuencias de escape. Los caracteres no seguros son aquellos que se pueden modificar durante el transporte a través de Internet e incluyen los caracteres (<, >, , ", #, {, }, |, , ^, [, ], y '). Esta marca se aplica a todas las direcciones URL, incluidas las opacas.

URL_NO_META

Se define para que sea igual que URL_DONT_SIMPLIFY.

URL_PLUGGABLE_PROTOCOL (0x40000000)

Combine direcciones URL con protocolos conectables definidos por el cliente, según la especificación W3C. Esta marca no se aplica a protocolos estándar como ftp, http, gopher, etc. Si se establece esta marca, UrlCombine no simplifica las direcciones URL, por lo que no es necesario establecer también URL_DONT_SIMPLIFY.

URL_UNESCAPE (0x10000000)

Anulación de escape de las secuencias de escape que contienen las direcciones URL, con dos excepciones. Las secuencias de escape de '?' y '#' no están sin escape. Si también se establece una de las marcas de URL_ESCAPE_XXX, las dos direcciones URL se desenrutan primero y, a continuación, se combinan y, a continuación, se aplican caracteres de escape.

URL_ESCAPE_AS_UTF8 (0x00040000)

Windows 7 y versiones posteriores. Codifique por porcentaje todos los caracteres no ASCII como sus equivalentes UTF-8.

Valor devuelto

Tipo: HRESULT

Devuelve códigos de error COM estándar, incluidos los siguientes.

Código devuelto Descripción
S_OK
 pszCombined apunta a una cadena que contiene las direcciones URL combinadas. El valor de pcchCombined se establece en el número de caracteres de la cadena, sin contar el carácter NULL de terminación.
E_POINTER
 El búfer era demasiado pequeño. El valor de pcchCombined se establece en el número mínimo de caracteres que debe contener el búfer, incluido el carácter NULL de terminación.

Comentarios

Los elementos entre barras diagonales se tratan como identificadores jerárquicos; el último elemento especifica el propio documento. Debe escribir una barra diagonal (/) después del nombre del documento para anexar más elementos; de lo contrario, UrlCombine intercambia un documento por otro. Por ejemplo:


hRetVal = UrlCombine(TEXT("http://xyz/test/abc"), 
                     TEXT("bar"), 
                     lpszCombined, 
                     &dwLength, 0);

El código anterior devuelve la dirección URL. http://xyz/test/bar. Si desea que la dirección URL combinada sea http://xyz/test/abc/bar, use la siguiente llamada a UrlCombine.


hRetVal = UrlCombine(TEXT("http://xyz/test/abc/"), 
                     TEXT("bar"), 
                     lpszCombined, 
                     &dwLength, 0);

Si una cadena de dirección URL contiene '/.. /' o '/./', UrlCombine normalmente trata los caracteres como si indicaran la navegación en la jerarquía de direcciones URL. La función simplifica las direcciones URL antes de combinarlas. Por ejemplo, "/hello/cruel/.. /world" se ha simplificado a "/hello/world". Si la marca URL_DONT_SIMPLIFY se establece en dwFlags, la función no simplifica las direcciones URL. En este caso, "/hello/cruel/.. /world" se deja tal y como está.

Nota

El encabezado shlwapi.h define UrlCombine 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 Convenciones para prototipos de función.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional, Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado shlwapi.h
Library Shlwapi.lib
Archivo DLL Shlwapi.dll (versión 5.0 o posterior)

Consulte también

Control de localizadores uniformes de recursos

UrlCanonicalize