DOS Session Window Manager Services

For the DOS Session Window Manager, the virtual video device driver provides the following DOSRequestVDD services:

The Set Access request informs the virtual video device driver that the caller is interested in receiving video events for the requested DOS session, preventing future callers from obtaining the same privilege. It also declares the DOS session to be windowed. Under the cover, the virtual video device driver can initiate a global timer hook for the purpose of video event checking upon creation of the first DOS session. In addition, the same interface can be used by the OS/2 Session Window Manager to help the virtual video device driver track which sessions are being windowed by PM so that events are not reported when PM is not foreground. When PM returns to foreground, it is up to the virtual video device driver to post refreshed events so that all DOS-session windows are repainted.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_SETACCESS (1)            */
        ULONG cbInput,  /* See the ACCESS_ constants          */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     #define ACCESS_RELEASE   0 /* Release access             */
     #define ACCESS_REQUEST   1 /* Request access             */
     #define ACCESS_PMREQUEST 2 /* Request access made by PM  */

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_ACCESS_DENIED (Access already has been taken.)
        ERROR_INVALID_FUNCTION (iFunc invalid, or access
         already set.)

The Set Focus request records the current DOS session as having or not having focus. Unlike the foreground/background notification hooks provided by the DOS Session Manager (which are supported only by the Session Manager), this function is called by the DOS Session Window Manager as the user gives or takes focus to or from DOS sessions.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS Session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_SETFOCUS (2)             */
        ULONG cbInput,  /* TRUE if gaining focus,             */
                        /*   FALSE if losing                  */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION (iFunc is invalid)

The Set Lock request suspends and resumes the DOS session's video state. The virtual video device driver guarantees that the video state will not change following a LOCK until a corresponding UNLOCK is issued. Moreover, if a DOS session is locked multiple times, it must be unlocked an equivalent number of times before it is truly unlocked.

Implementation of this service currently is based on the VDHFreeze and VDHThaw services, instead of a lazy lock, to avoid additional overhead in the interrupt and I/O handlers, and to make the lock implementation simple for both background and foreground DOS sessions. Consequently, callers should use the lock service sparingly and for as brief a time as possible to avoid communication problems due to line drop.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_SETLOCK (3)              */
        ULONG cbInput,  /* TRUE if locking,                   */
                        /*   FALSE if unlocking               */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION (iFunc is invalid)
        ERROR_BUFFER_OVERFLOW (Too many freezes
         outstanding.)

The Query Mode request returns current mode information for the DOS session, such as screen dimensions, whether or not the DOS session is suspended, code-page ID, and so forth.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_QUERYMODE (4)            */
        ULONG cbInput,  /* 0                                  */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Sizeof(VVMODE)                     */
        PVOID pOutput   /* Pointer to a VVMODE structure      */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (VDM has no video state
                                           yet.)
        ERROR_ACCESS_DENIED        (User buffer could not
                                           be locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                           outstanding.)

where VVMODE is a structure containing:

     /*
     ** Output for MODE event
     */

     typedef struct vvm_s
     {
        ULONG ulAdapter;    /* See the ADAPTER_* constants.   */
        ULONG ulFormat;     /* See the FORMAT_* constants.    */
        ULONG ulDDFormat;   /* See the DDFORMAT_* constants.  */
        ULONG flMode;       /* Mode descriptors (See MODE_*   */
                            /*  constants.)                   */
        ULONG nRows;        /* Height of screen in rows       */
                            /* (or y pels)                    */
        ULONG nCols;        /* Width of screen in columns     */
                            /* (or x pels)                    */
        ULONG nPlanes;      /* Number of planes (Must be 1    */
                            /*  for OS/2 2.0.)                */
        ULONG nBitCount;    /* If TEXT, zero;  if BITMAP,     */
                            /*  bits per pel).                */
        ULONG ulCellWidth;  /* Width of cells (normally 8;    */
                            /*  1 for BITMAPs)                */
        ULONG ulCellHeight; /* Height of cells (1 for         */
                            /*  BITMAPs)                      */
        ULONG fSuspended;   /* See the SUSPEND_* constants.   */
        ULONG cpID;         /* Current code-page ID           */
        ULONG FormatID;     /* Current format ID              */
     }  VVMODE;
     #define ADAPTER_MONO  0   /* Adapters supported          */
     #define ADAPTER_CGA   1   /* (Same as VioGetConfig       */
                               /*  constants)                 */
     #define ADAPTER_EGA   2
     #define ADAPTER_VGA   3
     #define ADAPTER_8514A 7

     #define FORMAT_CGA    2   /* LVB formats supported       */
     #define FORMAT_4BYTE  4
     #define FORMAT_BITMAP 0

     #define DDFORMAT_4PLANE 1 /* Display driver formats      */
                               /* supported                   */

     #define MODE_MONO        0x0001 /* Monochrome mode in    */
                                        effect                */
     #define MODE_UNDERLINE   0x0002 /* Underlining in effect */
     #define MODE_SUP_XSCALE2 0x1000 /* X scaling supported   */
                                     /* by factor of 2        */
     #define MODE_SUP_YSCALE2 0x2000 /* Y scaling supported   */
                                     /* by factor of 2        */
     #define MODE_SUP_PARTIALSCAN 0x4000 /* Partial scan line */
                                   /* copy requests supported */
     #define SUSPEND_NONE             0 /* DOS session running*/
                                           normally           */
     #define SUSPEND_OUT_OF_MEMORY    1 /* DOS session sus-   */
                                           pended due to low  */
                                        /* memory             */
     #define SUSPEND_UNSUPPORTED_MODE 2 /* DOS session sus-   */
                                           pended due to      */
                                        /* unsupported mode   */

The Query Cursor request returns current cursor position and shape information for the DOS session:

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_QUERYCURSOR (5)          */
        ULONG cbInput,  /* 0                                  */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Sizeof(VVCURSOR)                   */
        PVOID pOutput   /* Pointer to a VVCURSOR structure    */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (VDM has no video state
                                    yet.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

where VVCURSOR is a structure containing:

     /*
     ** Output for CURSOR event
     */

     typedef struct vvc_s
     {
        ULONG row;          /* Row (Y position) of DOS        */
                            /* session's cursor               */
        ULONG col;          /* Column (X position) of DOS     */
                            /* session's cursor               */
        ULONG ulScanStart;  /* Starting scan line for DOS     */
                            /* session's cursor               */
        ULONG ulScanEnd;    /* Ending scan line for DOS       */
                            /* session's cursor               */
        ULONG fVisible;     /* TRUE if DOS session cursor     */
                            /* visible,                       */
                            /* FALSE if not                   */
     } VVCURSOR;

The Query Palette request returns the RGB array for the DOS session. The RGB array contains 16 RGB entries for text modes and (2(n) bits per pel) entries for graphics modes:

     DosRequestVDD(
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_QUERYPALETTE (6)         */
        ULONG cbInput,  /* 0                                  */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Size of RGB array, in bytes        */
        PVOID pOutput   /* Pointer to RGB array               */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (VDM has no video state
                                    yet.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

where the RGB array contains 16 RGB entries for text modes (FORMAT_CGA) and (2(n)BitCount) entries for graphics modes. RGB entries are packed on byte boundaries and have the following structure:

     typedef struct rgb_s
     {
        BYTE bBlue;
        BYTE bGreen;
        BYTE bRed;
     }  RGB;

The Copy LVB request copies a rectangular portion of the DOS session's logical video buffer (that is, text-based LVB) to the specified output LVB. Using this call, the DOS Session Window Manager can keep a private copy of the LVB in sync with the virtual video device driver's LVB for a given DOS session:

     DosRequestVDD
     (
        HVDD  hvddVideo /* virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_COPYLVB (7)              */
        ULONG cbInput,  /*  Sizeof(RECTL)                     */
        PVOID pInput,   /* Pointer to RECTL structure         */
        ULONG cbOutput, /* Size of output LVB                 */
        PVOID pOutput   /* Pointer to output LVB              */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (DOS session has no video
                                    state yet.)
        ERROR_INVALID_DATA         (DOS session has changed
                                    video modes.)
        ERROR_NOT_LOCKED           (Caller must lock DOS
                                    session)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

where RECTL is a structure defining the region to be copied:

     typedef struct rcl_s
     {
        LONG xLeft;     /* Left column (leftmost is 0)        */
        LONG yBottom;   /* Bottom row                         */
        LONG xRight;    /* Right column                       */
        LONG yTop;      /* Top row (topmost is 0)             */
     }  RECTL;

and where pOutput points to an output LVB. Using this call, the DOS Session Window Manager keeps a private LVB in sync with the virtual video device driver's LVB for a given DOS session. Arbitrary rectangles of the source LVB are copied to the same relative position in the target LVB.

ERROR_INVALID_DATA is returned to callers that have exclusive event access when a DOS session is in the process of changing video modes. It alleviates the need for a caller to constantly lock and unlock the DOS session to ensure a reliable transfer. Callers without exclusive event access have no alternative but to lock and unlock for each copy; otherwise, they run the risk of obtaining incorrect or obsolete information. The virtual video device driver enforces this, and will return ERROR_NOT_LOCKED if called without exclusive access and the DOS session unlocked.

The Copy Bit Map request copies a rectangular portion of the DOS session's graphics video buffer to the specified output buffer. The output buffer is interpreted either as a device-dependent bit map (DDB) into which the requested region is copied at the same relative position, or as a device-independent bit map (DIB) intermediate buffer into which the region always is copied, starting at offset 0.
```
     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_COPYBITMAP (8)           */
        ULONG cbInput,  /* Sizeof(VVRECT)                     */
        PVOID pInput,   /* Pointer to VVRECT structure        */
        ULONG cbOutput, /* Size of output graphics buffer     */
        PVOID pOutput   /* Pointer to output graphics buffer  */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid)
        ERROR_INVALID_PARAMETER    (Pointers are invalid)
        ERROR_NOT_READY            (DOS session has no video
                                    state yet)
        ERROR_INVALID_DATA         (DOS session has changed
                                    video modes)
        ERROR_NOT_LOCKED           (Caller must lock DOS
                                    session)
        ERROR_ACCESS_DENIED        (User buffer could not
                                    be locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)
```
where VVRECT is a structure defining the region to be copied and how it is to be copied:
```
     /*
     ** Input for COPYBITMAP request
     */

     typedef struct vvr_s
     {
        ULONG  ulDDFormat;  /* Display driver format          */
                            /* (0 if DIB used)                */
        ULONG  cx;          /* Target bit map width           */
        ULONG  cy;          /* Target bit map height          */
        RECTL  rcl;         /* Rectangle being requested      */
        PBYTE  pbColorXlate;/* Display driver color           */
                            /* translation table              */
     }  VVRECT;
```
and where pOutput points to an output graphics buffer. Using this call, the DOS Session Window Manager keeps a private bit map in sync with the virtual video device driver's graphics buffer for a given DOS session.
ulDDFormat in the VVRECT structure determines whether the request is a DIB transfer (zero) or a DDB transfer (nonzero). DIB transfers are supported for whole scan lines only (that is, xLeft and xRight are ignored). The first requested scan line must be copied to offset 0 of the bit-map buffer, and so on.
Only one DDB format, DDFORMAT_4PLANE (1), has been defined for the current release, but third parties that provide both new virtual video device drivers and new PM display drivers can define their own formats. The DOS Session Window Manager, in its capacity as mediator between the virtual video device driver and the Presentation Manager display driver, makes no interpretation of ulDDFormat in the VVMODE structure other than to initiate device-independent bit-map transfers for a zero format and device-dependent transfers for nonzero formats.
The DDFORMAT_4PLANE format requires a bit-map buffer that matches the dimensions of the DOS session's current graphics mode and has exactly four color planes (16 colors). The first scan line of the first plane is at offset 0, followed by the first scan line of the second plane at the next DWORD boundary, and so on. In addition, none of the four planes of data for a particular scan line can cross a 64KB boundary; instead, they must start at the next 64KB boundary.
For example, if the DOS session is in a 640 x 480 x 16 mode (that is, four planes of 480 80-byte scan lines), then only 204 complete scan lines will fit in each 64KB section of the buffer. The buffer must therefore be 128KB, plus 22.5KB for the 72 remaining scan lines, for a total of 150.5KB.
For this version of OS/2, DDFORMAT_4PLANE bit-map transfers are supported only for whole scan lines (vvr.rcl.xLeft and vvr.rcl.xRight are ignored). The buffer is assumed to be as large as the DOS session's current graphics screen dimensions, and the requested scan lines must be copied to the same relative position within the target buffer.
ERROR_INVALID_DATA is returned to callers that have exclusive event access when a DOS session is in the process of changing video modes. It alleviates the need to constantly lock and unlock the DOS session to ensure a reliable transfer. Callers without exclusive event access have no alternative but to lock and unlock for each copy; otherwise, they run the risk of obtaining incorrect or obsolete information. The virtual video device driver enforces this, and will return ERROR_NOT_LOCKED if called without exclusive access when the DOS session is unlocked.

The Wait Event request returns the next windowed DOS session video event. The DOS Session Window Manager uses this interface to obtain video state changes for any unminimized windowed DOS sessions and calls the appropriate graphics engine or PM Window Manager interfaces to realize the changes:

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_WAITEVENT (9)            */
        ULONG cbInput,  /* Size of buffer for event data      */
        PVOID pInput,   /* Pointer to event buffer            */
        ULONG cbOutput, /* Sizeof(VVEVENT)                    */
        PVOID pOutput   /* Pointer to VVEVENT structure       */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

where VVEVENT is filled in with the following information:

     /*
     ** Output for VVDSYSREQ_WAITEVENT
     */

     typedef struct vve_s
     {
        LONG  iEvent;  /* One of the VVDEVENT_constants       */
        ULONG sgID;    /* Screen group ID of DOS session      */
        ULONG nData;   /* # of entries of information returned*/
     }  VVEVENT;

     /* Event IDs for VVDSYSREQ_WAITEVENT.                    */

     #define VVDEVENT_NONE     0  /* No change                 */
     #define VVDEVENT_MODE     1  /* Mode change               */
     #define VVDEVENT_PALETTE  2  /* Palette change            */
     #define VVDEVENT_LVB      3  /* Text or graphics buffer
                                  /* change                    */
     #define VVDEVENT_SCROLL   4  /* Scroll change             */
     #define VVDEVENT_STRING   5  /* String output change      */
     #define VVDEVENT_CURSOR   6  /* Cursor position/type
                                  /* change                    */
     #define VVDEVENT_INPUT    7  /* DOS session is input ready*/
     #define VVDEVENT_ENDPASTE 8  /* Cancelled pasting         */
     #define VVDEVENT_PASTE    9  /* Start pasting             */
     #define VVDEVENT_SWITCHERROR 10  /* Session switch error  */
     #define VVDEVENT_TITLECHANGE 11  /* Session title change  */
     #define VVDEVENT_DDE         12  /*  Set/Clear DDE flag   */

and the buffer addressed by pInput is filled in with:

     VVMODE structure,       if (iEvent == VVDEVENT_MODE)
     VVLVB structure(s),     if (iEvent == VVDEVENT_LVB)
     VVSCROLL structure,     if (iEvent == VVDEVENT_SCROLL)
     VVSTRING structure,     if (iEvent == VVDEVENT_STRING)
     VVCURSOR structure,     if (iEvent == VVDEVENT_CURSOR or
                                VVDEVENT_INPUT)
     null-terminated string, if (iEvent == VVDEVENT_TITLECHANGE)

For all the above events, nData will equal 1 (with the exception of the LVB event, which will return the number of VVLVB structures provided). For those events not listed (PALETTE, PASTE, ENDPASTE, SWITCHERROR, and NONE), nData will equal 0, as no additional data is returned with those notifications.

The Control Event request provides several subfunctions that control the event thread (that is, any thread dedicated to the WAITEVENT request).

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_CONTROLEVENT (10)        */
        ULONG cbInput,  /* See the CONTROL_constants          */
        PVOID pInput,   /* Pointer to event buffer            */
        ULONG cbOutput, /* Sizeof(VVEVENT)                    */
        PVOID pOutput   /* Pointer to VVEVENT structure       */
     );

     #define CONTROL_RELEASE         0 /* Release event thread */
     #define CONTROL_VDMMINIMIZED    1 /* Disable video events */
                                       /* for DOS session      */
     #define CONTROL_VDMUNMINIMIZED  2 /* Enable video events  */
                                       /* for DOS session      */

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION  (iFunc is invalid)
        ERROR_INVALID_PARAMETER (parameter(s) are invalid)

The RELEASE function is used to unblock any threads blocked in the WAITEVENT request. The resulting event is NONE. The VDMMINIMIZED and VDMUNMINIMIZED functions disable and enable event reporting for the DOS session, respectively.

[Back: Virtual Video Device Driver Services for OS/2 Applications (DosRequestVDD)]
[Next: Presentation Manager Display Driver Services]