idn wrapper - Client Side IDN Conversion Software for Windows Copyright (c) 2000,2001,2002 Japan Network Information Center. All rights reserved. *** NOTICE ****************************************************** If you have installed mDN Wrapper (former version of idn wrapper) on your system, you should unwrap all the programs before installing idn wrapper. Or if you have installed pre-release versions of idn wrapper, you should uninstall it before installing the release version. In this case, the configuration file `idn.conf' will be removed by the uninstall process. If you made changes to that file, you should first make a backup, then merge the contents by hand after installation. ***************************************************************** 1. Introduction For supporting internationalized domain names, each client application should convert domain names (their encodings) to that DNS server accepts. This requires applications to handle internationalized domain names in its core, and it is the vendor's responsibility to make their programs IDN-compatible. Although there are ongoing efforts in IETF to standardize IDN framework (architecture, encoding etc.) and several RFCs are expected to be published soon as the result, not many applications support IDN to this date. So, there are needs for some helper application which makes legacy applications IDN-aware. `runidn' in idnkit is one of such solutions for Unix-like operating systems, and this software, `idn wrapper' is the one for Windows. On windows, name resolving request is passed to WINSOCK DLL. idn wrapper replaces WINSOCK DLL with the one that can handle IDN, which makes legacy windows applications compatible with IDN. This is the whole idea of idn wrapper. 2. Setup and Configuration idn wrapper wraps WINSOCK DLL by placing wrapper (fake) DLLs in the application's directory. For the installation, idn wrapper comes with a setup program and a configuration program. NOTE: You can also install idn wrapper DLLs in the Windows system directory. But this installation is very dangerous and may cause severe problems in your system. You should try it at your own risk. 2.1. Setup Program To install idn wrapper, run "setup.exe". Setup program will do: + Installing Files Copy idn wrapper files (DLL, Program EXE, etc) into diretory "\Program Files\JPNIC\idn wrapper" This directory may be changed on setup sequence. + Setting registry entries Setup program will create keys and values under registry: "HKEY_LOCAL_MACHINES\Software\JPNIC\IDN" InstallDir REG_SZ "" Pathname of the idn wrapper's installation directory. The installer makes copies of the original WINSOCK DLLs in that directory, which is referenced by the idn wrapper's fake DLLs. ConfFile REG_SZ "\idn.conf" Name of the idnkit's configuration file, which defines various parameter regarding multilingual domain name handling. See the contents of the file for details. This value can be changed with the Configuration Program or the registry editor. LogFile REG_SZ "\idn_wrapper.log" Name of the idn wrapper's log file. This value can be changed with the Configuration Program or the registry editor. LogLevel DWORD -1 Logging level. Default is -1, which indicates no logging is made. This value can be changed with the Configuration Program or the registry editor. PerProg KEY Under this key, idn wrapper set program-specific values. idn wrapper uses program's executable name as key, and put values under that key. PerProg\\Where REG_DWORD Encoding Position PerProg\>progname>\Encoding REG_SZ Local Encoding Name Configuration program set local encpoding name. "Where" value is usually not required in standard installation. If you installed idn wrapper in system directory, chanage "Where" values to fit your environment. + Creating icon Setup program will create program icon for idn wrapper's configuration program, and put it into "Start Menu". You can start configuration program with it. 2.2. Configuration Program Configuration program is a tool for wrap specific program, or unwrap programs. If you start "Configuration Program", you'll get window like this. +---+-------------------------------------------------+---+---+---+ | | idn wrapper - Configuration | _ | O | X | +---+-------------------------------------------------+---+---+---+ | idn wrapper Configuration Program version X.X | +-----------------------------------------------------------------+ | Wrapped Program +---------+ | | +---------------------------------------------+---+ | Wrap.. | | | | | A | +---------+ | | | +---+ +---------+ | | | | | | Unwrap..| | | | | | +---------+ | | | | | +---------+ | | | | | |UnwrapAll| | | | | | +---------+ | | | | | +---------+ | | | | | |RewrapAll| | | | | | +---------+ | | | | | +---------+ | | | | | | Log.. | | | | | | +---------+ | | | | | +---------+ | | | +---+ |Advanced.| | | | | V | +---------+ | | +---+-------------------------------------+---+---+ +---------+ | | | < | | > | | Exit | | | +---+-------------------------------------+---+ +---------+ | +-----------------------------------------------------------------+ Listbox contains list of current wrapped programs. Initially it is empty. To wrap a program, press button "wrap". You'll get following dialog. +---+-------------------------------------------------+---+---+---+ | | idn wrapper - Wrap Executable | _ | O | X | +---+-------------------------------------------------+---+---+---+ | +----------------------------------------+ +--------+ | | Program: | | |Browse..| | | +----------------------------------------+ +--------+ | | +----------+ | | Encoding: | | o Default o UTF-8 | | +----------+ | | [] Force local DLL reference | +-----------------------------------------------------------------+ | +--------+ +--------+ | | | Wrap | | Cancel | | | +--------+ +--------+ | +-----------------------------------------------------------------+ First, enter program (executable name with full path) or browse wrapping exectable from file browser. Then set local encoding of that program. Usually use "Default" as local encoding. If target program uses internationalized encoding, then specify "UFT-8". The "Force local DLL reference" button controls the DLL search order of the program to be wrapped (Windows95 does not have this capability, hence this button does not appear). If it is checked, DLLs in the local directory (the directory which the executable file is in) are always preferred, even if the executable specifies otherwise. If you have problem with wrapping, checking this button may solve the problem, but it is also possible that it causes other problem. Finally, put "wrap" button to wrap specified program with given encoding. Wrapped program will be listed in listbox of the first window. When you install a new version of idn wrapper, you have to re-wrap your programs in order to update DLLs used for wrapping. "Rewrap all" button is provided for this purpose. Just press the button, and all the currently wrapped programs will be re-wrapped. To unwrap a program, press button "unwrap". You'll get following confirmating dialog. +---+-------------------------------------------------+---+---+---+ | | idn wrapper - Unwrap Executable | _ | O | X | +---+-------------------------------------------------+---+---+---+ | +---------------------------------------------------+ | | Program: | | | | +---------------------------------------------------+ | +-----------------------------------------------------------------+ | +--------+ +--------+ | | | Unwrap | | Cancel | | | +--------+ +--------+ | +-----------------------------------------------------------------+ If you unwrap a program, the program will be vanished from listbox of the first window. Also "Unwrap all" button is provided to unwrap all the programs that are currently wrapped. To configure logging, press button "log". You'll get the following dialog. +---+-------------------------------------------------+---+---+---+ | | idn wrapper - Log Configuration | _ | O | X | +---+-------------------------------------------------+---+---+---+ | Log Level: o None o Fatal o Error o Warning o Info o Trace | | | | +------------------------------------+ +---------+ | | Log File:| | | Browse..| | | +------------------------------------+ +---------+ | | +------+ +--------+ | |Log Operation: | View | | Delete | | | +------+ +--------+ | +-----------------------------------------------------------------+ | +--------+ +--------+ | | | OK | | Cancel | | | +--------+ +--------+ | +-----------------------------------------------------------------+ Logging level can be selected from the followings. None no logging at all Fatal only records fatal errors Error also records non-fatal errors Warning also records warning mssages Info also records informational messages Trace also records trace information Note that these levels are for log output from IDN library (idnkit.dll). idn wrapper itself supports only off (None) and on (the rest). Pathname of the log file can also be specified with this dialog. You can view the current log file contents by pressing "View" button, or delete it by "Delete" button. Note that log level and log file configuration doesn't affect already running processes. Press "advanced" button to invoke the advanced configuration dialog. This dialog is for advanced users and enables customization for some basic parameters which normal users need not change, since appropriate defaults are provided. +---+-------------------------------------------------+---+---+---+ | | idn wrapper - Advanced Configuration | _ | O | X | +---+-------------------------------------------------+---+---+---+ | IDN Wrapping Mode | | o Wrap both WINSOCK 1.1 and WINSOCK 2.0 | | o Wrap only WINSOCK 1.1 | | o Wrap only WINSOCK 2.0 | | o Wrap only WINSOCK 2.0 if it exists. | | Otherwise wrap only WINSOCK 1.1 | +-----------------------------------------------------------------+ | IDN Configuration | | +--------------------------------+ +----------+ | | Config File: | | | Browse.. | | | +--------------------------------+ +----------+ | | +------+ | | | Edit | | | +------+ | +-----------------------------------------------------------------+ | +--------+ +--------+ | | | OK | | Cancel | | | +--------+ +--------+ | +-----------------------------------------------------------------+ IDN Wrapping Mode Customize wrapping mode. Normally the default item should be appropriate. Changing it to other item may help when you have problems. IDN Configuration Set the configuration file for multilingual domain name handling. By pressing "Edit" button, you can edit then contents of the file. 3. Limitations 3.1. DLL Versions Wrapper DLL is tightly coupled with specific DLL version, because it must export all the entries including un-documented ones. If WINSOCK DLL version changed, idn wrapper may not work correctly. Current idn wrapper is tested on Win2000 (WINSOCK 1.1 + 2.0) WinME (WINSOCK 1.1 + 2.0) But there are no assuarance for future versions of Windows. 3.2. DNS, WINS, LMHOSTS There are three name resolving methods in windows, DNS, WINS and LMHOSTS. Using idn wrapper, domain name conversion will performed on all of thoses methods. It may cause some trouble if windows using WINS or LMHOSTS. We recommend use DNS oly if you want to use idn wrapper. 3.3. Converting Names other than Domain Name In WINSOCK 2.0, there are generic name resolution APIs are introduced. WSALookupServiceBeginW WSALookupServiceNextW WSALookupServiceEnd They are use mainly domain name conversion now, but not limited to resolving domain name. idn wrapper hooks this API and convert given name anyway. This causes some trouble if conversion name is not domain name. 3.4. Applications don't use these APIa Some applications don't use these APIs to resolving domain names. For example, 'nslookup' issue DNS request locally. For these applications, idn wrapper does not work. 3.5. Applications bound to specific WINSOCK DLL Some applications are bound to specific DLL, not relying on standard DLL search path. Netscape Communicator seems to be one of such programs. idn wrapper in standard installation cannot wrap such programs. If you want to wrap those programs, you may use installation into system directory. But this installation is very dangerous, for it is possible that your system cannot boot again. 4. Registry Setting - Summary 4.1. Priority of Setting Settings of idn wrapper is placed on registry Software\JPNIC\IDN under HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER. idn wrapper first read HKEY_LOCAL_MACHINE, and if HKEY_CURRENT_USER exist, overwrite with this one. Usually set HKEY_LOCAL_MACHINE only. But if you need per user setting, then set HKEY_CURRENT_USER. Note that the configuration program reads/writes only HKEY_LOCAL_MACHINE. 4.2. Registry Key There's common settings and per program settings. _Common Settings Software\JPNIC\IDN\InstallDir Installation directory Software\JPNIC\IDN\Where Where to convert encoding 0: both WINSOCK 1.1 and WINSOCK 2.0 1: if WINSOCK 2.0 exist, convert at 2.0 DLL if WINSOCK 1.1 only, convert at 1.1 DLL 2: only in WINSOCK1.1 3: only in WINSOCK2.0 Software\JPNIC\IDN\ConfFile idnkit Configuration File Software\JPNIC\IDN\LogFile Log File Software\JPNIC\IDN\LogLevel Log Level _Per Program Settings Converting position and program's local encoding may be set per program bases. Software\JPNIC\IDN\PerProg\\Where Software\JPNIC\IDN\PerProg\\Encoding If not specified, the following values are assumed. Where 0 (both 1.1 DLL and 2.0 DLL) Encoding [process's code page]