Writing an Installation DLL

You can provide one or two installation DLLs. These DLLs can be the same DLL with two different entry points or two different DLLs with corresponding entry points. There are two ways to call an installation DLL:

• Call the routine after all files have been copied, but before script files have been processed (using the SSDLL and SSDLLENTRY keywords), or
  
• Call the routine after all files have been copied and after script files have been processed (using the SSTERMDLL and SSTERMDLLENTRY keywords).

The parameters for each entry point are as follows:

HWND (input)

Owner handle. This handle allows the DLL to create windows for the user interface.

Source path of the installation package.

Target drive (a drive letter and colon (for example, d:).

DLL input parameters, as specified by the SSDLLINPUTPARMS keyword in CONTROL.SCR.

MINSTALL object window handle that receives messages to perform media control interface and CONFIG.SYS operations.

A CHAR[256] null-terminated string that contains response-file data needed by the DLL. The encoded string is created by the DLL as a series of ASCII characters. This information allows MINSTALL to operate in an unattended installation mode where all user responses are provided by the response-file string. The encoded information is passed to the DLL, and all user interaction is bypassed.

The following is an example prototype used to define an installation DLL.

ULONG APIENTRY StartMyInstall (HWND hwndOwnerHandle,                               PSZ pszSourcePath,
                               PSZ pszTargetDrive,
                               PSZ pszMyParms,
                               HWND hwndMinstallHandle,
                               PSZ pszResponseFile);

MINSTALL provides numerous services to the installation DLLs due to the various environments in which MINSTALL must operate. You can use MINSTALL on a machine that has never had OS/2 multimedia installed on it. You can also use MINSTALL on a machine that has OS/2 multimedia installed on the hard drive. OS/2 multimedia does not need to be running to use MINSTALL in this environment. MINSTALL retains control of the MMPM2.INI and CONFIG.SYS files to ensure no changes are made to these files while MINSTALL is running.

While MINSTALL has control of the MMPM2.INI and CONFIG.SYS files it might be necessary for an installation DLL to read or write to one or both of these files. MINSTALL provides an interface to allow the installation DLLs access to both the MMPM2.INI and CONFIG.SYS files. Also, if OS/2 multimedia is installed and running, some files might be open that MINSTALL attempts to replace. When this occurs, MINSTALL copies the open files to a temporary directory until the next system restart.

The following table lists the messages, along with the message formats and descriptions, available to an installation DLL. An installation DLL can send these messages with WinSendMsg or WinPostMsg.

Message

Description

Installs a CODEC using the ulCodecCompType field.

mp1 = 0;                               /* Not used */
mp2 = MPFROMP(PINSTCODECINIFILEINFO);  /* Pointer to the
                                          INSTIOPROC structure */

IM_CODEC2INSTALL

Installs a CODEC using the fccCodecCompType[5] field.

mp1 = 0;                                /* Not used */
mp2 = MPFROMP (PINSTCODECINIFILEINFO);  /* Pointer to the
                                           INSTIOPROC structure */

IM_CONFIGDELETE

Deletes a line from the CONFIG.SYS file.

mp1 = MPFROMP(PCONFIGDATA); /* Pointer to the CONFIGDATA structure */
mp2 = 0;                    /* Not used */

IM_CONFIGENUMERATE

Gets a line from the CONFIG.SYS file.

mp1 = MPFROMP(PCONFIGDATA); /* Pointer to the CONFIGDATA structure */
mp2 = 0;                    /* Not used */

IM_CONFIGMERGE

Merges data into an existing CONFIG.SYS entry.

mp1 = MPFROMP(PCONFIGDATA); /* Pointer to the CONFIGDATA structure */
mp2 = 0;                    /* Not used */

IM_CONFIGNEW

Adds a new line to the CONFIG.SYS file.

mp1 = MPFROMP(PCONFIGDATA); /* Pointer to the CONFIGDATA structure */
mp2 = 0;                    /* Not used */

IM_CONFIGQUERYCHANGED

Returns TRUE if the CONFIG.SYS file has been changed.

mp1 = 0;  /* Not used */
mp2 = 0;  /* Not used */

IM_CONFIGREPLACE

Replaces an existing CONFIG.SYS file.

mp1 = MPFROMP(PCONFIGDATA); /* Pointer to the CONFIGDATA structure */
mp2 = 0;                    /* Not used */

IM_CONFIGUPDATE

Updates an existing CONFIG.SYS entry.

mp1 = MPFROMP(PCONFIGDATA); /* Pointer to the CONFIGDATA structure */
mp2 = 0;                    /* Not used */

IM_CREATE_WPS_OBJECT

Installs a folder and its contents.

mp1 = 0;                        /* Not used */
mp2 = MPFROMP(PINSTOBJECTDATA); /* Pointer to the
                                   INSTOBJECTDATA structure */

IM_DESTROY_WPS_OBJECT

Destroys an existing folder and its contents.

mp1 = 0;                /* Not used */
mp2 = MPFROMP(HOBJECT); /* This must be the exact OBJECTID
                           with which the object was created  */

IM_EA_JOIN

Joins an EA file to its parent file (the file that it was previously separated from).

mp1 = 0;                    /* Not used */mp2 = MPFROMP(PINSTEAJOIN); /* Pointer to the INSTEAJOIN
                               structure */

IM_EA_LONG_NAME_JOIN

Creates an EA file containing a long name (greater than 8 characters but less than 256) and joins it to a file or directory.

mp1 = 0;                            /* Not used */mp2 = MPFROMP(PINSTEALONGNAMEJOIN); /* A pointer to the structure
                                       that contains the long name
                                       as an ASCII string, the file or
                                       directory name to which the long
                                       name is to be applied, and the
                                       new EA name */

IM_LOG_ERROR

Writes a message to the MINSTALL.LOG file. This can be an error type message or only an information type message.

mp1 = MPFROMP((PSZ)pszStatement); /* The text of the message to insert
                                     at the end of the MINSTALL.LOG
                                     file */
mp2 = 0;                          /* Not used */

IM_MCI_EXTENDED_SYSINFO

Maps to the mciSendCommand MCI_SYSINFO.

mp1 = MPFROML(LONG);  /* The MCI_SYSINFO extended function desired */
mp2 = MPFROMP(*MCI_SYSINFO_PARMS); /* The SYSINFO
                                                      structure       */

IM_MCI_SEND_COMMAND

Sends an MCI command.

mp1 = 0;                            /* Not used */
mp2 = MPFROMP(PINSTMCISENDCOMMAND); /* Pointer to the INSTMCISENDCOMMAND
                                       structure */

IM_MIDIMAP_INSTALL

Installs a MIDI map.

mp1 = 0;                            /* Not used */
mp2 = MPFROMP(PMIDIMAPINSTALLDATA); /* Pointer to the
                                       MIDIMAPINSTALLDATA structure */

IM_MMIO_INSTALL

Installs an IOProc.

mp1 = 0;                    /* Not used */
mp2 = MPFROMP(PINSTIOPROC); /* Pointer to the INSTIOPROC structure */

IM_QUERYPATH

Requests the current location of a copied file.

mp1 = PMFROMP(PSZ); /* The name of the file needed  */
mp2 = PMFROMP(PSZ); /* The full path to the file    */

IM_SPI_INSTALL

Installs stream protocol information.

mp1 = 0;            /* Not used */
mp2 = MPFROMP(PSZ); /* The fully qualified path of a SPI resource DLL */

The data structures used as parameters for the messages in the previous list are defined in the MINSTALL.H file located in the \TOOLKIT\H subdirectory.

Follow these guidelines when writing an installation DLL:

• Set the mouse pointer to SPTR_WAIT during any operation lasting more than one second between requests for user information.
  
• Keep the user interface as responsive as possible by using the MM_DISPATCHVARS and MM_DISPATCHMESSAGES() macros before and after all I/O intensive operations and and while updates are being made to INI files and the CONFIG.SYS file. This is necessary because installation DLLs are executed in the MINSTALL message queue thread. These macros are defined in the MINSTALL.H file.