en:docs:fapi:mouregister

This is part of Family API which allow to create dual-os version of program runs under OS/2 and DOS

Note: This is legacy API call. It is recommended to use 32-bit equivalent

2021/09/17 06:47 · prokushev
2021/08/20 05:18 · prokushev

MouRegister

This call registers a mouse subsystem within a session.

Syntax

 MouRegister (ModuleName, EntryName, Mask)

Parameters

  • ModuleName (PSZ) - input : Address of the dynamic link module name. The maximum length is 9 bytes (including ASCIIZ terminator).
  • EntryName (PSZ) - input : Address of the dynamic link entry point name of a routine that receives control when any of the registered functions are called. The maximum length is 33 bytes (including ASCIIZ terminator).
  • Mask (ULONG) - input : A mask of bits, where each bit set to 1 identifies a mouse function being registered.

Return Code

rc (USHORT) - return:Return code descriptions are:

  • 0 NO_ERROR
  • 385 ERROR_MOUSE_NO_DEVICE
  • 413 ERROR_MOUSE_INVALID_ASCIIZ
  • 414 ERROR_MOUSE_INVALID_MASK
  • 415 ERROR_MOUSE_REGISTER
  • 466 ERROR_MOU_DETACHED
  • 505 ERROR_MOU_EXTENDED_SG

Remarks

The Base Mouse Subsystem is the default mouse subsystem. There can be only one MouRegister outstanding for each session without an intervening MouDeRegister. MouDeRegister must be issued by the same process that issued MouRegister.

When any registered function is called, control is routed to EntryName. When this routine is entered, four additional values are pushed onto the stack. The first is the index number (Word) of the function being called. The second is a near pointer (Word). The third is the caller's DS register (Word). The fourth is the return address (DWord) to the mouse router. For example, if MouGetNumMickeys were called and control routed to EntryName, the stack would appear as if the following instructions were executed:

 PUSH@ WORD    NumberOfMickeys
 PUSH  WORD    DeviceHandle
 CALL  FAR     MouGetNumMickeys
 PUSH  WORD    Function Code
 CALL  NEAR    Entry point in Mouse Router
 PUSH  DS
 CALL  FAR     EntryName.

When a registered function returns to the Mouse Router, AX is interpreted as follows:

  • AX = 0 No error. Do not invoke the Base Mouse Subsystem routine. Return AX = 0.
  • AX = -1 Invoke the BaseMouse Subsystem routine. Return AX = return code from the Base Mouse Subsystem.
  • AX = error (if not 0 or -1) Do not invoke the Base Mouse Subsystem Routine. Return AX = error.

When the mouse router receives a mouse call, it routes it to the Base Mouse Subsystem unless an application or other mouse subsystem has previously issued MouRegister for that call. If the call was registered, the subsystem is entered at the EntryName specified, and provided with the applicable function code.

The registered function mask is used to determine whether a requested function is performed by the registered mouse subsystem or default to the Base Mouse Subsystem.

The following list shows the relationship of the mouse API calls and the Function Code passed to either the Base Mouse Subsystem or a registered mouse subsystem.

MOU API calls Function Code Function Mask
MouGetNumButtons00H00000001H
MouGetNumMickeys01H00000002H
MouGetDevStatus02H00000004H
MouGetNumQueEl03H00000008H
MouReadEventQue04H00000010H
MouGetScaleFact05H00000020H
MouGetEventMask06H00000040H
MouSetScaleFact07H00000080H
MouSetEventMask08H00000100H
MouGetHotKey09H00000200H
MouSetHotKey0AH00000400H
MouOpen0BH00000800H
MouClose0CH00001000H
MouGetPtrShape0DH00002000H
MouSetPtrShape0EH00004000H
MouDrawPtr0FH00008000H
MouRemovePtr10H00010000H
MouGetPtrPos11H00020000H
MouSetPtrPos12H00040000H
MouInitReal13H00080000H
MouFlushQue14H00100000H
MouSetDevStatus15H00200000H

A registered mouse sybsystem must leave the stack, on exit, in the exact state it was received.

Bindings

C

#define INCL_MOU
 
USHORT  rc = MouRegister(ModuleName, EntryName, Mask);
 
PSZ     ModuleName;    /* Module Name */
PSZ     EntryName;     /* Entry Name */
ULONG   Mask;          /* Function Mask */
 
USHORT  rc;            /* return code */

MASM

EXTRN   MouRegister:FAR
INCL_MOU            EQU 1
 
PUSH@  ASCIIZ  ModuleName    ;Module Name
PUSH@  ASCIIZ  EntryName     ;Entry Name
PUSH   DWORD   Mask          ;Function Mask
CALL   MouRegister
 
Returns WORD

en/docs/fapi/mouregister.txt · Last modified: 2021/11/04 14:16 by prokushev