Differences

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

--- en:ibm:prcp:mou:register [2016/02/04 03:39] – created valerius
+++ en: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>