en:ibm:prcp:mou:register

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
en:ibm:prcp:mou:register [2016/02/04 03:07] – created valeriusen:ibm:prcp:mou:register [2016/09/15 04:19] (current) – valerius
Line 1: Line 1:
 +==== MouRegister ====
 +
 +**Bindings**: [[register#C bindings|C]], [[register#MASM bindings|MASM]]
 +
 +This call registers a mouse subsystem within a session. 
 +
 +//MouRegister// (ModuleName, EntryName, Mask) 
 +
 +//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. Bit values are: 
 +
 +^Bit ^Description ^
 +|31-22 |Reserved, set to zero |
 +|21 |[[en:ibm:prcp:mou:setdevstatus|MouSetDevStatus]] |
 +|20 |[[en:ibm:prcp:mou:flushque|MouFlushQue]] |
 +|19 |[[en:ibm:prcp:mou:initreal|MouInitReal]] |
 +|18 |[[en:ibm:prcp:mou:setptrpos|MouSetPtrPos]] |
 +|17 |[[en:ibm:prcp:mou:getptrpos|MouGetPtrPos]] |
 +|16 |[[en:ibm:prcp:mou:removeptr|MouRemovePtr]] |
 +|15 |[[en:ibm:prcp:mou:drawptr|MouDrawPtr]] |
 +|14 |[[en:ibm:prcp:mou:setptrshape|MouSetPtrShape]] |
 +|13 |[[en:ibm:prcp:mou:getptrshape|MouGetPtrShape]] |
 +|12 |[[en:ibm:prcp:mou:close|MouClose]] |
 +|11 |[[en:ibm:prcp:mou:open|MouOpen]] |
 +|10 |Reserved |
 +|9 |Reserved |
 +|8 |[[en:ibm:prcp:mou:seteventmask|MouSetEventMask]] |
 +|7 |[[en:ibm:prcp:mou:setscalefact|MouSetScaleFact]] |
 +|6 |[[en:ibm:prcp:mou:geteventmask|MouGetEventMask]] |
 +|5 |[[en:ibm:prcp:mou:getscalefact|MouGetScaleFact]] |
 +|4 |[[en:ibm:prcp:mou:readeventque|MouReadEventQue]] |
 +|3 |[[en:ibm:prcp:mou:getnumqueel|MouGetNumQueEl]] |
 +|2 |[[en:ibm:prcp:mou:getdevstatus|MouGetDevStatus]] |
 +|1 |[[en:ibm:prcp:mou:getnummickeys|MouGetNumMickeys]] |
 +|0 |[[en:ibm:prcp:mou:getnumbuttons|MouGetNumButtons]] |
 +
 +//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 [[en:ibm:prcp:mou:register|MouRegister]] outstanding for each session without an intervening [[en:ibm:prcp:mou:dereg|MouDeRegister]]. [[en:ibm:prcp:mou:dereg|MouDeRegister]] must be issued by the same process that issued [[en:ibm:prcp:mou:register|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 [[en:ibm:prcp:mou:getnummickeys|MouGetNumMickeys]] were called and control routed to //EntryName//, the stack would appear as if the following instructions were executed: 
 +
 +<code asm>
 +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.
 +</code>
 +
 +
 +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 [[en:ibm:prcp:mou:register|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 ^
 +|[[en:ibm:prcp:mou:getnumbuttons|MouGetNumButtons]] |00H |
 +|[[en:ibm:prcp:mou:getnummickeys|MouGetNumMickeys]] |01H |
 +|[[en:ibm:prcp:mou:getdevstatus|MouGetDevStatus]] |02H |
 +|[[en:ibm:prcp:mou:getnumqueel|MouGetNumQueEl]] |03H |
 +|[[en:ibm:prcp:mou:readeventque|MouReadEventQue]] |03H |
 +|[[en:ibm:prcp:mou:getscalefact|MouGetScaleFact]] |05H |
 +|[[en:ibm:prcp:mou:geteventmask|MouGetEventMask]] |06H |
 +|[[en:ibm:prcp:mou:setscalefact|MouSetScaleFact]] |07H |
 +|[[en:ibm:prcp:mou:seteventmask|MouSetEventMask]] |08H |
 +|Reserved |09H |
 +|Reserved |0AH |
 +|[[en:ibm:prcp:mou:open|MouOpen]] |0BH |
 +|[[en:ibm:prcp:mou:close|MouClose]] |0CH |
 +|[[en:ibm:prcp:mou:getptrshape|MouGetPtrShape]] |0DH |
 +|[[en:ibm:prcp:mou:setptrshape|MouSetPtrShape]] |0EH |
 +|[[en:ibm:prcp:mou:drawptr|MouDrawPtr]] |0FH |
 +|[[en:ibm:prcp:mou:removeptr|MouRemovePtr]] |10H |
 +|[[en:ibm:prcp:mou:getptrpos|MouGetPtrPos]] |11H |
 +|[[en:ibm:prcp:mou:setptrpos|MouSetPtrPos]] |12H |
 +|[[en:ibm:prcp:mou:initreal|MouInitReal]] |13H |
 +|[[en:ibm:prcp:mou:flushque|MouFlushQue]] |14H |
 +|[[en:ibm:prcp:mou:setdevstatus|MouSetDevStatus]] |15H |
 +
 +A registered mouse sybsystem must leave the stack, on exit, in the exact state it was received. 
 +
 +=== C bindings ===
 +
 +<code 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 */
 +</code>
 +
 +=== MASM bindings ===
 +
 +<code asm>
 +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
 +</code>