## Virtual Device Driver Reference for OS/2

[prev][next][parent][TOC]

### VDHInstallUserHook - Parameters

Event (ULONG) A DOS session event (such as DOS session termination).

Possible values are:

VDD_EXIT DOS session support is shutting down
VDM_CREATE DOS session creation
VDM_TERMINATE DOS session termination
VDM_FOREGROUND DOS session to the foreground
VDM_BACKGROUND DOS session to the background
VDM_CREATE_DONE DOS session creation completed successfully
VDM_VDD_CREATE_DONE DOS session virtual device driver creation completed
VDM_PDB_DESTROY DOS Program Data Block (PDB) destroyed in DOS session
VDM_PDB_CHANGE PDB changed in DOS session
VDM_CODEPAGE_CHANGE Code page change event
VDM_TITLE_CHANGE DOS session title change event
VDM_MEMORY_MAPPED_IN Pages mapped into a DOS session (0 to 1MB+64KB)
VDM_MEMORY_UN_MAPPED Pages unmapped from a DOS session (0 to 1MB+64KB).
VDM_BEGIN_VPM_TASK Protected-mode task has started
VDM_END_VPM_TASK Protected-mode task has ended

The interfaces for the UserHook handlers (depending on the event that is handled) are:

     RETCODE HOOKENTRY pfnExit()

             ENTRY     None

             EXIT      None

             CONTEXT   INIT

                       Task

     RETCODE HOOKENTRY pfnCreate(hvdm)

             ENTRY         hvdm

             EXIT-SUCCESS  Return a nonzero value

             EXIT-FAILURE  Return 0

                             DOS session creation fails; the DOS Session Manager

                             calls all the VD_TERMINATE hooks for all

                             virtual device drivers that returned Successful on this

                             DOS session creation.

             CONTEXT       DOS session-task

     RETCODE HOOKENTRY pfnTerminate(hvdm)

             ENTRY         hvdm - DOS session being terminated

             EXIT-SUCCESS  Return a nonzero value

             EXIT-FAILURE  Return 0

             CONTEXT       DOS session-task

     RETCODE HOOKENTRY pfnForeground(hvdm)

             ENTRY     hvdm - DOS session coming foreground

             EXIT      None

             CONTEXT   Task

     RETCODE HOOKENTRY pfnBackground(hvdm)

             ENTRY     hvdm - DOS session going background

             EXIT      None

             CONTEXT   Task

     RETCODE HOOKENTRY pfnCreateDone(hvdm)

             ENTRY     hvdm

             EXIT      None

             CONTEXT   DOS session creation

     RETCODE HOOKENTRY pfnVDDCreateDone(hvdm)

             ENTRY     hvdm

             EXIT      None

             CONTEXT   DOS session Creation

     RETCODE HOOKENTRY pfnPDBDestroy(hvdm,segPDB)

             ENTRY         hvdm

                           segPDB  V86 segment of terminating PDB

             EXIT-SUCCESS  Return a nonzero value

             EXIT-FAILURE  Return 0

             CONTEXT       DOS session-task

     RETCODE HOOKENTRY pfnPDBChange(hvdm,segPDB)

             ENTRY         hvdm

                           segPDB  V86 segment of new PDB

             EXIT-SUCCESS  Return a nonzero value

             EXIT-FAILURE  Return 0

             CONTEXT       DOS session-task

     VOID HOOKENTRY pfnCodePageChange(ulCodePage)

          ENTRY         ulCodePage - New code page

          EXIT-SUCCESS  Return a nonzero value

          EXIT-FAILURE  Return 0

                          An error is returned on the set code-page operation, but

                          the rest of the device-code-page handlers are called.

          CONTEXT       DOS session-task

     VOID HOOKENTRY pfnVDMTitleChange (pszTitle)

          ENTRY         pszTitle  new DOS session Title

          EXIT-SUCCESS  Return a nonzero value

          EXIT-FAILURE  Return 0

          CONTEXT       DOS session-task

          NOTES         1. This event is called for both full screen and windowed

                           DOS session.

                        2. If pszTitle is NULL, the virtual device driver should

                           treat it as DOS session's default and original title.

                        3. Ideally there should be only one virtual device driver for this

                           hook, but this is not a restriction.  One of the

                           virtual device drivers registered is responsible for

                           putting the title.  Only this virtual device driver returns

                           a nonzero value; all others return 0.

     RETCODE HOOKENTRY pfnMemoryMappedIn (hvdm,page,cpages,fl)

             ENTRY         hvdm

                           page     page address

                           cpages   # of pages mapped in from

                                    the starting page address

                           fl       type of mapping, (see VDHMapPages)

             EXIT-SUCCESS  Return a nonzero value

             EXIT-FAILURE  Return 0

             CONTEXT       DOS session-task

     RETCODE HOOKENTRY pfnMemoryUnMapped (hvdm,page,cpages,fl)

             ENTRY         hvdm

                           page     page address

                           cpages   # of pages unmapped from the starting page address

                           fl       type of mapping, (see VDHMapPages)

             EXIT-SUCCESS  Return a nonzero value

             EXIT-FAILURE  Return 0

             CONTEXT       DOS session-task

     RETCODE HOOKENTRY pfnBeginVDMTask (hvdm,page,cpages,fl)

             ENTRY         hvdm

                           page     page address

                           cpages   # of pages unmapped from the starting page address

                           fl       type of mapping, (see VDHMapPages)

             EXIT-SUCCESS  Return a nonzero value

             EXIT-FAILURE  Return 0

             CONTEXT       DOS session-task

     RETCODE HOOKENTRY pfnEndVDMTask (hvdm,page,cpages,fl)

             ENTRY         hvdm

                           page     page address

                           cpages   # of pages unmapped from the starting page address

                           fl       type of mapping, (see VDHMapPages)

             EXIT-SUCCESS  Return a nonzero value

             EXIT-FAILURE  Return 0

             CONTEXT       DOS session-task

     RETCODE HOOKENTRY pfnBeginVPMTask (hvdm,page,cpages,fl)

             ENTRY         hvdm

                           page     page address

                           cpages   # of pages unmapped from the starting page address

                           fl       type of mapping, (see VDHMapPages)

             EXIT          None

             CONTEXT       DOS session-task

     RETCODE HOOKENTRY pfnEndVPMTask (hvdm,page,cpages,fl)

             ENTRY         hvdm

                           page     page address

                           cpages   # of pages unmapped from the starting page address

                           fl       type of mapping, (see VDHMapPages)

             EXIT          None

             CONTEXT       DOS session-task

UserHook (PUSERHOOK) A user-defined handler for the event.

rc (BOOL) - returns

Success If the function is successful, it returns a nonzero value.

Failure If the function fails, an invalid input parameter or a kernel heap overflow (that is, if the system runs out of memory) causes a system halt.