home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / screen / scsv50.arj / SCSAVER.API < prev    next >
Encoding:
Text File  |  1992-03-30  |  9.0 KB  |  248 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.        ________________________
  9.        \                     \ \
  10.         \       Tom           \ \
  11.          \       Donnelly      \ \
  12.           \       Computer      \ \
  13.            \       Software      \ \
  14.             \_____________________\_\
  15.              \_____________________\_\
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.                                                            Screen Saver
  23.                                                             Version 5.0
  24.  
  25.                                    Screen blanker and security software
  26.  
  27.                           APPLICATION PROGRAMMING INTERFACE DESCRIPTION
  28.  
  29.  
  30.  
  31.                                                            Tom Donnelly
  32.                                                       Computer Software
  33.                                                           P.O. Box 3856
  34.                                                           San Dimas, CA
  35.                                                                   91773
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.         Copyright (C) 1992  Tom R. Donnelly  All Rights Reserved
  56.  
  57. APPLICATION PROGRAMMING INTERFACE DESCRIPTION                       ...1
  58. ========================================================================
  59.  
  60.  
  61.    This document describes the protocol required by a user application
  62.    program to communicate with the resident copy of Screen Saver.  Using
  63.    this interface, it is possible to change various parameters of the
  64.    resident program from within a user application.
  65.  
  66.    The information provided in this document is subject to change
  67.    without notice.
  68.  
  69.    All communication between a user application and Screen Saver is
  70.    performed through DOS Interrupt 54h.  Using this interrupt, an
  71.    application can interrogate whether Screen Saver is resident, which
  72.    version is running and the segment address at which it was loaded.
  73.    The application may also read and/or update the status byte, used to
  74.    control certain Screen Saver options.
  75.  
  76.    Before issuing any calls to Screen Saver, you must insure that the
  77.    vector for interrupt 54h is not zero.  If it is zero, then Screen
  78.    Saver is not resident.  Issuing INT 54h when the vector is zero will
  79.    send your computer into hyperspace, forcing a cold-boot.
  80.  
  81.               Mov   AX,3554h      ;Get interrupt vectors in ES:BX
  82.               Int   21h           ;Call DOS
  83.               Or    BX,BX         ;Any offset?
  84.               Jz    Not_resident  ;No - not resident
  85.               Mov   BX,ES         ;Copy segment
  86.               Or    BX,BX         ;Any segment?
  87.               Jz    Not_resident  ;No - not resident
  88.  
  89.    After determining that the INT 54h vector points to something, the
  90.    program is free to make function calls.  All function calls require
  91.    the function number in the AH register, the component code in AL
  92.    register (Screen Saver's component code is 3) and the characters 'TD'
  93.    in the CX register.  Some functions, such as ReplaceStatusByte,
  94.    require a new status byte in the BL register.
  95.  
  96.    If the function call was successful, CX will be returned containing
  97.    zero (otherwise, CX will be non-zero).  Byte parameters will usually
  98.    be returned in the AL register.  The GetLoadAddr function returns the
  99.    segment address in the ES register.
  100.  
  101.                              *** IMPORTANT ***
  102.  
  103.    Screen Saver is not the only program to use the INT 54h interface.
  104.    It is important to check the success of the function call even when
  105.    you find INT 54h to be non-zero.  Screen Saver will only answer
  106.    function calls containing the correct component code (3) in AL.  In
  107.    addition, there may be function calls which are not supported on
  108.    older versions of Screen Saver.  Issuing an unsupported function call
  109.    will return a non-zero value in the CX register.
  110.  
  111.  
  112. APPLICATION PROGRAMMING INTERFACE DESCRIPTION                       ...2
  113. ========================================================================
  114.  
  115.  
  116.    Function 0 - GetVersion
  117.       Entry:  AH=0        Function code
  118.               AL=3        Component code (always 3)
  119.               CX='TD'     Literal
  120.  
  121.       Exit:   CX=0        If Screen Saver is resident.
  122.               AL=version  Format is Major*10 + Minor, eg: Version 4.9
  123.                           is returned as 49 (decimal) or 31h.
  124.  
  125.    ---------------------------------------------------------------------
  126.  
  127.    Function 3 - GetState
  128.       Entry:  AH=3        Function code
  129.               AL=3        Component code (always 3)
  130.               CX='TD'     Literal
  131.  
  132.       Exit:   CX=0        If Screen Saver is resident.
  133.               AL=1        If Screen Saver is ON or ON with LOCK.
  134.               AL=0        If Screen Saver is OFF.
  135.  
  136.    ---------------------------------------------------------------------
  137.  
  138.    Function 4 - Disable (deactivate Screen Saver)
  139.       Entry:  AH=4        Function code
  140.               AL=3        Component code (always 3)
  141.               CX='TD'     Literal
  142.  
  143.       Exit:   CX=0        If Screen Saver is resident.
  144.  
  145.    ---------------------------------------------------------------------
  146.  
  147.    Function 5 - Enable (reactivate Screen Saver)
  148.       Entry:  AH=5        Function code
  149.               AL=3        Component code (always 3)
  150.               CX='TD'     Literal
  151.  
  152.       Exit:   CX=0        If Screen Saver is resident.
  153.  
  154.    ---------------------------------------------------------------------
  155.  
  156.    Function 7 - GetLoadAddr
  157.       Entry:  AH=7        Function code
  158.               AL=3        Component code (always 3)
  159.               CX='TD'     Literal
  160.  
  161.       Exit:   CX=0        If Screen Saver is resident.
  162.               ES=         Segment address of resident code.
  163.  
  164.  
  165. APPLICATION PROGRAMMING INTERFACE DESCRIPTION                       ...3
  166. ========================================================================
  167.  
  168.  
  169.  
  170.    Function 8 - GetStatusByte
  171.       Entry:  AH=8        Function code
  172.               AL=3        Component code (always 3)
  173.               CX='TD'     Literal
  174.  
  175.       Exit:   CX=0        If Screen Saver is resident.
  176.               AL=76543210 Status byte from resident code.
  177.                           Bit 7:  1=EGA supported (do not change)
  178.                           Bit 6:  1=VGA supported (do not change)
  179.                           Bit 5:  1=MCGA supported (do not change)
  180.                           Bit 4:  Reserved for future use (zero)
  181.                           Bit 3:  1=Invoke keyboard lock
  182.                           Bit 2:  1=Invoke screen blanker
  183.                           Bit 1:  1=Lock-mode active (LOCK or LOCKONLY)
  184.                           Bit 0:  1=Blanker active (ON or LOCK mode)
  185.  
  186.    ---------------------------------------------------------------------
  187.  
  188.    Function 9 - ReplaceStatusByte
  189.       Entry:  AH=9        Function code
  190.               AL=3        Component code (always 3)
  191.               BL=byte     new status byte (See Function 8 for details)
  192.               CX='TD'     Literal
  193.  
  194.       Exit:   CX=0        If Screen Saver is resident.
  195.  
  196.  
  197. APPLICATION PROGRAMMING INTERFACE DESCRIPTION                       ...4
  198. ========================================================================
  199.  
  200.  
  201.    Example:  Activate security lock from an application program.
  202.  
  203.              This code fragment performs the following:
  204.                 1. Insures that vectors for INT 54h is not zero.
  205.                 2. Requests the resident version to make sure that
  206.                    Screen Saver is resident and that it is at least
  207.                    version 5.0.
  208.                 3. Requests the resident status byte.
  209.                 4. Turns on the lock-request bit in the status byte.
  210.                 5. Replaces the status byte in the resident code.
  211.  
  212.  
  213.               Mov   AX,3554h      ;Get interrupt vectors in ES:BX
  214.               Int   21h           ;Call DOS
  215.               Or    BX,BX         ;Any offset?
  216.               Jz    NotResident   ;No - not resident
  217.               Mov   BX,ES         ;Copy segment
  218.               Or    BX,BX         ;Any segment?
  219.               Jz    NotResident   ;No - not resident
  220.  
  221.               Mov   AH,0          ;GetVersion function code
  222.               Mov   AL,3          ;Component code
  223.               Mov   CX,'TD'       ;Literal
  224.               Int   54h
  225.               Jcxz  GotVersion    ;Got it ok
  226.               Jmp   NotResident
  227.        GotVersion:
  228.               Cmp   AL,50         ;Version 5.0 or greater?
  229.               Jb    BadVersion    ;No - skip the rest
  230.  
  231.               Mov   AH,8          ;GetStatusByte function code
  232.               Mov   AL,3          ;Component code
  233.               Mov   CX,'TD'       ;Literal
  234.               Int   54h
  235.               Jcxz  GotStatus     ;Got it ok
  236.               <Handle error here>
  237.        GotStatus:
  238.               Or    AL,00001010b  ;Insure lock mode and activate lock
  239.  
  240.               Mov   BL,AL         ;copy to BL for Replace function
  241.               Mov   AH,9          ;ReplaceStatusByte function code
  242.               Mov   AL,3          ;Component code
  243.               Mov   CX,'TD'       ;Literal
  244.               Int   54h
  245.               Jcxz  AllDone
  246.               <Handle error here>
  247.        AllDone:
  248.