En esta ocasión vamos a empezar por lo fácil: dar una descripción de las funciones auxiliares que nos permiten manipular direcciones URL (
Uniform Resource Locator).
Empezamos:
InternetCanonicalizeUrl
Esta función nos permite convertir una cadena con una URL a su equivalente pero con caracteres seguros. Las cadenas URL no pueden contener cualquier tipo de carácter, y existe un método para buscar qué caracteres no son seguros y sustituirlos por la secuencia equivalente. El ejemplo que todos conocemos es el carácter espacio y su secuencia "%20".
Hay que tener cuidado de no utilizar esta función con una cadena previamente codificada, porque la función no se realiza ningún tipo de comprobación y la re-codificará de nuevo.
BOOL InternetCanonicalizeUrl(
LPCSTR lpszUrl,
LPSTR lpszBuffer,
LPDWORD lpdwLongitudBuffer,
DWORD dwOpciones
);
- lpszUrl: un puntero a una cadena con la URL a codificar.
- lpszBuffer: un puntero a una cadena donde se almacenará la URL resultante. Este puntero debe tener memoria previamente reservada.
- lpdwLongitudBuffer: un puntero a un valor que indica la longitud de caracteres que se han reservado para lpszBuffer. Cuando la función retorna, copiará en este valor el número de caracteres copiados en lpszBuffer si la función se ejecutó correctamente, o el número de bytes necesitados si la función retornó error.
- dwOpciones: una serie de banderas que configuran el comportamiento de la función:
- ICU_BROWSER_MODE: indica que se comportará como la codificación que hace el navegador, es decir, después del carácter "?" ó "#" no codificará nada.
- ICU_NO_ENCODE: No codifica nada.
- ICU_DECODE: convierte todas las secuencias codificadas (%XX) en su correspondiente cadena decodificada. Para usar esta bandera debe hacerse en combinación con ICU_NO_ENCONDE ya que en caso contrario, no tendrá efecto.
- ICU_ENCODE_PERCENT: Codifica los signos de porcentaje, que por defecto no son codificados. Sólo está disponible a partir de IE 5.
- ICU_ENCODE_SPACES_ONLY: Sólo codifica los espacios.
La función retorna TRUE o FALSE dependiendo de su éxito.
Si utilizamos esta función a partir de IE4, la bandera ICU_BROWSER_MODE se utilizará siempre, por lo que si queremos codificar la cadena completa, debemos recurrir a otras funciones, como UrlCanonicalize de la librería shlwapi.dll
InternetCombineUrl
Permite combinar una dirección base con una ruta relativa, dando como resultado una URL absoluta codificada. En otras palabras, nos combina el nombre del host con la ruta relativa, pasando el resultado por InternetCanonizaliceUrl.
BOOL InternetCombineUrl(
LPCTSTR lpszUrlBase,
LPCTSTR lpszUrlRelativa,
LPTSTR lpszBuffer,
LPDWORD lpdwLongitudBuffer,
DWORD dwOpciones
);
- lpszUrlBase: un puntero a una cadena con el host.
- lpszUrlRelativa: un puntero a una cadena con la ruta relativa.
- lpszBuffer: un puntero a una cadena con espacio suficiente para albergar el resultado.
- lpdwLongitudBuffer: Un puntero a una variable que almacena la longitud reservada, en caracteres, de lpszBuffer. Cuando la función retorna correctamente, almacenará en esta variable la longitud de los caracteres copiados, o el espacio necesario si no ha ocurrido un error.
- dwOpciones: indica las opciones que se utilizarán para realizar la llamada interna a InternetCanonicalizeUrl. Se admiten los mismos valores que en dicha función.
La función retorna TRUE o FALSE dependiendo de su éxito o fracaso.
InternetCrackUrl
Tranquilos, que esta función no tiene nada que ver con los hackers ni nada parecido, símplemente se encarga de "despedazar" una URL devolviendo sus componentes:
BOOL InternetCrackUrl(
LPCTSTR lpszUrl,
DWORD dwLongitudUrl,
DWORD dwOpciones,
LPURL_COMPONENTS lpComponentesUrl
);
- lpszUrl: un puntero a una cadena con la dirección URL a "despedazar".
- lpszLongitudUrl: cero o el número de caracteres de la URL, si la cadena es UNICODE.
- dwOpciones: uno de los siguientes valores:
- ICU_DECODE: convierte las cadenas codificadas en su original. Sólo se puede usar cuando se asigna un buffer a los campos de la estructura URL_COMPONENTS.
- ICU_ESCAPE: convierte las secuencias de escape a su valor original. Sólo se puede usar cuando se asigna un buffer a los campos de la estructura URL_COMPONENTS.
- lpComponentesUrl: la dirección de una estructura de tipo URL_COMPONENTS en la que se retorna los valores de cada uno de los elementos de la URL. La estructura tiene los siguientes campos:
typedef struct {
DWORD dwStructSize;
LPTSTR lpszScheme;
DWORD dwSchemeLength;
INTERNET_SCHEME nScheme;
LPTSTR lpszHostName;
DWORD dwHostNameLength;
INTERNET_PORT nPort;
LPTSTR lpszUserName;
DWORD dwUserNameLength;
LPTSTR lpszPassword;
DWORD dwPasswordLength;
LPTSTR lpszUrlPath;
DWORD dwUrlPathLength;
LPTSTR lpszExtraInfo;
DWORD dwExtraInfoLength;
} URL_COMPONENTS, *LPURL_COMPONENTS;
Los significados de los campos son:
- dwStructSize: el tamaño en byes de la estructura. Símplemente nos basta con asignar el valor sizeof(URL_COMPONENTS).
- nScheme: un valor enumerado que indica el tipo de esquema (protocolo) de la URL: http, ftp, gopher, mailto, etc.
- nPort: el número de puerto de la URL. Si no aparece ninguno, cada protocolo cuenta con su número de puerto por defecto.
- El resto de campos: son pares de atributos para cada componente de la URL: el primero de ellos (lpszXXX) es un puntero a una cadena donde se almacena el componente. El segundo (dwXXX) es la longitud del buffer donde apunta el puntero.
Si el puntero es NULL y la longitud 0, no se retornará ningún valor para ese componente.
Si el puntero es NULL pero la longitud es distinta de 0, se almacena en el puntero la dirección donde empieza el componente dentro de la propia URL, es decir, nos retorna un puntero a una subcadena de lpszUrl y nos copia la longitud del componente en la variable longitud.
Y finalmente, podemos almacenar en el puntero la dirección de un buffer, previamente reservado por nosotros, y establecer la variable longitud al número de caracteres que hemos reservado para este buffer en cuestión. Es este caso, la función nos copiará en cada uno de los buffers, el componente correspondiente, hasta el máximo indicado por la variable longitud.
Estos son campos y su resultado, aplicando la siguiente URL:------http://usuario:clave@www.servidor.com/ruta/recurso.html?param=valor
- lpszScheme y dwSchemeLength: puntero y longitud a esquema (protocolo). En el ejemplo, el valor resultante es "http".
- lpszHostName y dwHostNameLength: puntero y longitud al servidor. En el ejemplo, el valor es "www.servidor.com".
- lpszUserName y dwUserNameLength: puntero y longitud al nombre de usuario. En el ejemplo, el valor es "usuario".
- lpszPassword y dwPasswordLength: puntero y longitud a la clave de usuario. En el ejemplo, el valor es: "clave".
- lpszUrlPath y dwUrlPathLength: puntero y longitud a la ruta relativa de la URL. En el ejemplo, el valor es: "/ruta/recurso.html".
- lpszExtraInfo y dwExtraInfoLength: puntero y longitud a información adicional, como pueden ser los parámetros (a partir del carácter ?) o el ancla local (a partir del carácter #). En nuestro ejemplo, su valor es "?param=valor".
Esta función también retorna un valor booleano indicando su éxito o fracaso.
InternetCreateUrl
Esta función hace la operación inversa a la anterior, es decir: nos compone una cadena de URL a partir de sus componentes individuales.
BOOL InternetCreateUrl(
LPURL_COMPONENTS lpComponentesUrl,
DWORD dwOpciones,
LPTSTR lpszUrl,
LPDWORD lpdwLongitudUrl
);
No voy a entrar en más detalles, porque los parámetros se usan del mismo modo que con InternetCrackUrl, pero de forma inversa. Sólo hay que decir, que dentro de la estructura URL_COMPONENTS, se ignorarán aquellos componentes cuyo puntero se haya establecido a NULL. Hay que ser cuidadoso también con la manipulación de los punteros a carácter, ya que es muy normal equivocarse.
La función retornará FALSE en caso de error y GetLastError nos retorna ERROR_INSUFFICIENT_BUFFER si el buffer lpszUrl es demasiado pequeño, o si hemos cometido algún error manipulando los punteros de caracteres.
