## GetWAD

Programmer's Reference
Version 2.1
December 7, 2003

#### 1. Description

The GetWAD library consists of a single DLL file which depends on standard Windows libraries as well as the WININET library. This means that GetWAD is compatible with any 32-bit version of Windows (Win95 and later) provided that Internet Explorer (4.0 or later) is installed. The DLL is multi-threaded and can be called from either single- or multi-threaded programs (or DLLs), but it must not be called concurrently from multiple threads of the same program (ie., it's not reentrant); this should not matter for the intended use. It should be able to be used from practically any language that supports DLLs.

#### 2. Interface

The library interface is minimal in order to facilitate its use from various programs. The interface consists of two groups of two functions each; each application using the library should select one of these groups.

1. The version 1.x API: it uses a built-in search list and does not contact the GetWAD master servers.

   - The "getwad_setup()" function presents a dialog that lets the user specify various searching parameters, such as the pages to be searched for the WADs, enabling / disabling of the FTP protocol and the directory where it will deposit the WADs. This function should be rarely used, as the program defaults to some reasonable values. The various search parameters are stored in an INI file and they are used from the next function. This also means that a client program can generate the INI file using its own dialogs, so it may not have to call this function at all.
   - The "getwad_fetch()" function does the actual work of locating, downloading and unzipping the WAD files. It reads the parameters stored in the INI file by the previous function and tries to locate the desired file. Once the file is located, it is downloaded, unzipped (since all WADs are stored inside ZIP files) and copied to the appropriate directory.

2. The version 2.x API: it contacts the GetWAD master servers to obtain the current search list at the beginning of each search.

   - The "getwad2_setup()" function is completely analogous to the getwad_setup() function of the 1.x API, but instead of defining the search pages, it defines a set of user-defined pages which will be used in addition to the ones downloaded from the master server.
   - The "getwad2_fetch()" function is analogous to to the getwad_fetch() function of the 1.x API; the difference is that it contacts the GetWAD master servers in order to obtain the current search list. It also accepts an extra URL to search; this is convenient as many server admins provide a page with pointers to WADs played on their servers.

The 1.x API exists only for compatibility purposes with software interfacing to the older version of GetWAD; the version 2.x API is vastly more convenient for the end users, so it should be preferred.

#### 3. Function Reference

void WINAPI getwad_setup(HWND hwnd, BOOL allow_dest_spec, LPSTR ini_name,LPSTR ini_section);
Purpose: | Presents a configuration dialog. The user can select which pages and search engines it should consult, whether to enable the FTP protocol or not, and where to deposit the downloaded WAD files.
Parameters: | hwnd: Handle to a window in the calling application. The configuration dialog will be a child of the specified window. It can be zero but it is strongly discouraged, as the user will then be able to switch to the calling application before closing the configuration dialog. allow_dest_spec: Boolean flag indicating if we want to allow the user to select the destination directory. If set to "TRUE" (ie., any integer value different from zero), the user will be able to select the WAD destination directory. If set to "FALSE" (ie., zero), the WAD destination directory will not be displayed. This can be useful since Doom launchers normally provide for a means to specify the WAD directory. ini_name: Specifies the INI file to be used for storing the configuration parameters. If it is NULL or empty, GetWAD uses the default file "getwad.ini". If you don't specify any path component, the file is assumed to be in the WINDOWS directory. If this is not true, you must specify the full pathname of the INI file. ini_section: Specifies the section inside the INI file that will be used for storing the configuration parameters. If it is NULL or empty, GetWAD uses the default section "Options".
Return value: | None

int WINAPI getwad_fetch(HWND hwnd,LPSTR wadnames,LPSTR waddir, BOOL dont_wait_upon_success, LPSTR ini_name, LPSTR ini_section);
Purpose: | Locates, downloads and installs the specified WAD file.
Parameters: | hwnd: Handle to a window in the calling application. The function will display a dialog indicating the progress of the downloading process. That dialog will be a child of the specified window. It can be zero but it is strongly discouraged, as the user will then be able to switch to the calling application before returning from this function. wadnames: Names of the WAD files to be fetched; it consists of one or more names of WAD files separated by one or more spaces. Each name may have a ".wad" or ".zip" extension, but it is not necessary. If for example you want to download the file "brit11.wad", then you could set wadnames either to "brit11.wad", "brit11.zip", or "brit11". If you want to fetch the files "exec.wad" and "dweller2.wad", you could set wadnames to "exec dweller2", or "exec.wad dweller2.wad", etc. If this parameter is NULL or empty, GetWAD will prompt the user for the WAD to fetch. waddir: Name of the directory where you want to deposit the downloaded WAD. This parameter takes precedence over the parameter specified in the GetWAD INI file. This can be convenient when you don't want to bother calling "getwad_setup()" or constructing the INI file; in that case, you can simply pass the destination directory here; the default GetWAD values will normally be sufficient for the rest of the configuration. If waddir is NULL or empty, then GetWAD will use the value specified in the INI file. dont_wait_upon_sucess: Boolean flag indicating if GetWAD should close the dialog automatically when the requested file is successfully installed. If set the "TRUE" (ie., any integer value different from zero), GetWAD will close its dialog automatically and will return to the caller. If set to "FALSE" (ie., a value of zero), GetWAD will wait until the user presses the "Close" button. ini_name: Specifies the INI file to be used for storing the configuration parameters. If it is NULL or empty, GetWAD uses the default file "getwad.ini". If you don't specify any path component, the file is assumed to be in the WINDOWS directory. If this is not true, you must specify the full pathname of the INI file. ini_section: Specifies the section inside the INI file that will be used for storing the configuration parameters. If it is NULL or empty, GetWAD uses the default section "Options".
Return value: | Returns 1 upon success, 0 upon failure (ie., the files cannot be located or the network is down, or whatever), or -1 if the INI file has not been properly created (you can avoid using the INI file, if you specify the WAD directory; otherwise, the INI file must exist and it must contain a WAD directory specification).

void WINAPI getwad2_setup(HWND hwnd, BOOL allow_dest_spec, LPSTR ini_name,LPSTR ini_section);
Purpose: | Presents a configuration dialog. The user can specify a set of extra search pages that will be used in addition to the ones fetched by the GetWAD master servers. These pages take precedence over the ones fetched from the net. In the dialog you can also specify whether to enable the FTP protocol or not, and where to deposit the downloaded WAD files.
Parameters: | hwnd: Handle to a window in the calling application. The configuration dialog will be a child of the specified window. It can be zero but it is strongly discouraged, as the user will then be able to switch to the calling application before closing the configuration dialog. allow_dest_spec: Boolean flag indicating if we want to allow the user to select the destination directory. If set to "TRUE" (ie., any integer value different from zero), the user will be able to select the WAD destination directory. If set to "FALSE" (ie., zero), the WAD destination directory will not be displayed. This can be useful since Doom launchers normally provide for a means to specify the WAD directory. ini_name: Specifies the INI file to be used for storing the configuration parameters. If it is NULL or empty, GetWAD uses the default file "getwad.ini". If you don't specify any path component, the file is assumed to be in the WINDOWS directory. If this is not true, you must specify the full pathname of the INI file. ini_section: Specifies the section inside the INI file that will be used for storing the configuration parameters. If it is NULL or empty, GetWAD uses the default section "Options".
Return value: | None

int WINAPI getwad2_fetch(HWND hwnd,LPSTR wadnames,LPSTR waddir, BOOL dont_wait_upon_success, LPSTR ini_name, LPSTR ini_section, LPSTR server_search);
Purpose: | Locates, downloads and installs the specified WAD file. It contacts the GetWAD master servers to obtain an updated search list.
Parameters: | hwnd: Handle to a window in the calling application. The function will display a dialog indicating the progress of the downloading process. That dialog will be a child of the specified window. It can be zero but it is strongly discouraged, as the user will then be able to switch to the calling application before returning from this function. wadnames: Names of the WAD files to be fetched; it consists of one or more names of WAD files separated by one or more spaces. Each name may have a ".wad" or ".zip" extension, but it is not necessary. If for example you want to download the file "brit11.wad", then you could set wadnames either to "brit11.wad", "brit11.zip", or "brit11". If you want to fetch the files "exec.wad" and "dweller2.wad", you could set wadnames to "exec dweller2", or "exec.wad dweller2.wad", etc. If this parameter is NULL or empty, GetWAD will prompt the user for the WAD to fetch. waddir: Name of the directory where you want to deposit the downloaded WAD. This parameter takes precedence over the parameter specified in the GetWAD INI file. This can be convenient when you don't want to bother calling "getwad_setup()" or constructing the INI file; in that case, you can simply pass the destination directory here; the default GetWAD values will normally be sufficient for the rest of the configuration. If waddir is NULL or empty, then GetWAD will use the value specified in the INI file. dont_wait_upon_sucess: Boolean flag indicating if GetWAD should close the dialog automatically when the requested file is successfully installed. If set the "TRUE" (ie., any integer value different from zero), GetWAD will close its dialog automatically and will return to the caller. If set to "FALSE" (ie., a value of zero), GetWAD will wait until the user presses the "Close" button. ini_name: Specifies the INI file to be used for storing the configuration parameters. If it is NULL or empty, GetWAD uses the default file "getwad.ini". If you don't specify any path component, the file is assumed to be in the WINDOWS directory. If this is not true, you must specify the full pathname of the INI file. ini_section: Specifies the section inside the INI file that will be used for storing the configuration parameters. If it is NULL or empty, GetWAD uses the default section "Options". server_search: Specifies an extra search page that will be used after the user-specified pages and before the ones fetched from the master servers. It will be ignored if it is NULL or empty. This parameter can be convenient, as server administrators often set up pages containing links to WADs played on their servers.
Return value: | Returns 1 upon success, 0 upon failure (ie., the files cannot be located or the network is down, or whatever), or -1 if the INI file has not been properly created (you can avoid using the INI file, if you specify the WAD directory; otherwise, the INI file must exist and it must contain a WAD directory specification).

#### 4. INI File Format

As mentioneed above, GetWAD uses an INI file to store its configuration. The INI file name defaults to "getwad.ini" and the section inside the INI file defaults to "Options", but both can be modified by the calling program. There are cases where the calling program may prefer to use its own configuration dialog rather than the one provided by "getwad_setup()". In that case, the calling program will probably want to construct the INI file on its own instead of relying on the default GetWAD options. For this reason, we describe here the format of the INI file. Such a sample file looks like:

    [Options]
    use_google=1
    enable_ftp=1
    wad_dir=C:\INETDOOM\wads
    npredef=5
    predef000=http://www.freewebs.com/lap-clan/
    predef001=http://www.getsomewhere.net/?dep=doom&pg=files
    predef002=http://raider.dnsalias.com:8000/doom/wads/
    predef003=http://www.rarefiles.com/download/
    predef004=http://www.doomsearch.com/search.shtml?search=%s

The various parameters correspond to the options in the Setup dialog. The "npredef" and "predefNNN" parameters are used only by the 1.x API: "npredef" is the number of the predefined locations that will be searched by the program, and "predefNNN" are the URLs of these locations. Make sure that the number of such locations is correctly indicated by the "npredef" parameter.

#### 5. License

The GetWAD program (binaries and source code) is covered by a ZLIB-like license which is the most liberal license I can think of.

Copyright (C) 2003 Hippocrates Sendoukas.

This software is provided 'as-is', without any express or implied warranty. In no event will the author be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.