home *** CD-ROM | disk | FTP | other *** search
/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / GCTV101.ZIP / GOLDSAPI.DOC < prev    next >
Encoding:
Text File  |  1995-09-18  |  11.4 KB  |  246 lines
  1. ______________________________________________________________________
  2.  
  3.                         The Goldware Sound API
  4.                     Version 1.00, August 9th, 1995
  5.               A specification written by Odinn Sorensen
  6.                      Donated to the Public Domain
  7. ______________________________________________________________________
  8.  
  9.  
  10. The Goldware Sound API (GSAPI) is a set of functions provided by an
  11. interrupt service function installed on the Alternate Multiplex
  12. Interrupt (AMI) 2Dh. For full details on the Alternate Multiplex
  13. Interrupt, please see Ralf Brown's Interrupt List (INTER46*.ZIP), his
  14. AMI specification (ALTMPX35.ZIP) and/or his AMIS library
  15. (AMISL091.ZIP).
  16.  
  17. This chapter contains a specification of the current of the GSAPI.
  18. Refer to the AMI specification for details about implementing an AMI
  19. interrupt service function.
  20.  
  21. In the AMI specification there is an installation check function which
  22. returns a signature string which identifies installed interrupt
  23. services. The signature string for the GSAPI is as follows:
  24.  
  25. Manufacturer's name: Goldware
  26. Product name:        GoldSAPI
  27.  
  28. Signature as it would appear in Ralf Brown's Interrupt List:
  29.  
  30.   'Goldware' 'GoldSAPI'  The Goldware Sound API by Odinn Sorensen.
  31.  
  32. Applications looking for the GSAPI should scan the AMI for signatures
  33. and if it finds a match (not case sensitive) on the product name plus
  34. a version from 1.00 up to 1.99, it can consider the GSAPI installed
  35. and ready. A major version different from 1 must be considered totally
  36. incompatible with version 1.xx. All version 1.xx's must be backward
  37. compatible.
  38.  
  39. Note that the manufacturer's name does not have to be "Goldware". This
  40. is to allow you to brand your own GSAPI implementations with your own
  41. manufacturer's name in the signature.
  42.  
  43. Here is the specification as it would appear in Ralf Brown's Interrupt
  44. List:
  45.  
  46. --------s-2D--10-----------------------------
  47. INT 2D - Goldware Sound API (GSAPI) - OPEN API
  48.         AL = 10h
  49.         AH = AMIS multiplex number for the Goldware Sound API.
  50. Return: AX = 0000h if successful, 0001h if another caller has already
  51.                opened the api, FFFFh if the api is cannot be opened
  52.                for any other reason.
  53.         BX = A unique key value which the caller must use again when
  54.                closing the api using the AL=11h function.
  55.         CX = The size of the gsapidata structure.
  56.         DX:DI -> Pointer to the gsapi structure (see below).
  57. Program: The Goldware Sound API (GSAPI) is a generic sound driver API
  58.            designed by Odinn Sorensen of Goldware International. The
  59.            GSAPI was originally invented for sound card support in the
  60.            GoldED mail reader.
  61. Note:   This function must be called before any other function. It is
  62.           a hint to the api that it must get ready to load and play
  63.           sounds. Depending on the implementation, this function may
  64.           not do anything except prevent other access until the AL=11h
  65.           close api function is called.
  66.         The unique key value can be anything, but it is suggested to
  67.           simply keep a count of the number of calls to this function
  68.           and use that as the key value.
  69.  
  70. Format of the gsapidata structure:
  71. Offset  Size    Description
  72.   00h   WORD    Version of the sound driver (*).
  73.   02h   WORD    Version of the dsp (*).
  74.   04h   WORD    I/O port number (*).
  75.   06h   BYTE    IRQ number (*).
  76.   07h   BYTE    DMA channel number (*).
  77.   08h   WORD    Current sample rate in Hz (*).
  78.   0Ah   WORD    Status word. FFFFh if a sound is playing.
  79.   0Ch   WORD    Segment of requested memory buffer.
  80.   0Eh   WORD    Offset of requested memory buffer.
  81.   10h   DWORD   Length of requested memory buffer.
  82.   14h   80      ASCIIZ parameters string.
  83.  
  84. Note:   The gsapidata structure members marked with (*) are
  85.           informational (read) only for caller programs and may or may
  86.           not be set to real values by the api. Any data which the api
  87.           cannot determine is set to zero.
  88. --------s-2D--11-----------------------------
  89. INT 2D - Goldware Sound API (GSAPI) - CLOSE API
  90.         AL = 11h
  91.         AH = AMIS multiplex number for the Goldware Sound API.
  92.         BX = The unique key value which was returned by the AL=11h
  93.                open api function.
  94. Return: AX = 0000h if successful, 0001h if the api was not open, FFFFh
  95.                if the key value was not correct.
  96. Note:   This function will automatically call the AL=15h stop sound
  97.           and AL=13h close sound file functions if necessary.
  98. --------s-2D--12------------------------------
  99. INT 2D - Goldware Sound API (GSAPI) - OPEN AND LOAD SOUND FILE
  100.         AL = 12h
  101.         AH = AMIS multiplex number for the Goldware Sound API.
  102.         The name of the sound file is given in the gsapidata
  103.           parameters string field.
  104.         If the gsapidata length field is non-zero, the segment and
  105.           offset fields are assumed to be a pointer to a buffer which
  106.           can be used to load the file.
  107. Return: AX = error code
  108.           0000h - Sound file was opened and loaded without errors
  109.           0001h - A sound file was already opened and must be closed
  110.                     first.
  111.           0002h - A memory buffer is needed to load the file. The api
  112.                     sets the gsapidata length field to the amount of
  113.                     memory needed. The calling program must allocate
  114.                     the memory buffer, set the segment and offset
  115.                     fields in the gsapidata structure and then call
  116.                     this function again. The file is not considered
  117.                     open until the file has been successfully loaded.
  118.                     Depending on the implementation, the memory buffer
  119.                     requested may be as large as the entire file, even
  120.                     longer than 64K.
  121.           0003h - Sound file format not supported.
  122.           FFFFh - DOS returned an error when accessing the file. BX
  123.                     contains the DOS error code.
  124. Note:   This function may optionally set the gsapidata sample rate
  125.           field to the primary sample rate as found in the sound file.
  126.           The sample rate field must be set to zero if setting of the
  127.           sample rate is not supported.
  128.         The function is allowed to close the file immediately after
  129.           loading, but then it must "pretend" that it is open so that
  130.           the AL=13h close sound file function will succeed.
  131.         The sound file is only loaded, not played.
  132. --------s-2D--13-----------------------------
  133. INT 2D - Goldware Sound API (GSAPI) - CLOSE SOUND FILE
  134.         AL = 13h
  135.         AH = AMIS multiplex number for the Goldware Sound API.
  136. Return: AX = 0000h if successful, 0001h if no sound file is open.
  137. Note:   The calling program must call this function before
  138.           deallocating the memory buffer if it was allocated.
  139. --------s-2D--14-----------------------------
  140. INT 2D - Goldware Sound API (GSAPI) - PLAY SOUND
  141.         AL = 14h
  142.         AH = AMIS multiplex number for the Goldware Sound API.
  143.         BX = Sample rate in Hz or zero to use default sample rate.
  144. Return: AX = 0000h if successful, 0001h if there is no sound to play.
  145. Note:   Plays the sound file which was previously loaded using the
  146.           AL=12h load sound function. The sound is played from the
  147.           beginning. If a sound is already playing, it is restarted.
  148.           Sounds are assumed to be played in the background and this
  149.           function will return as soon as playback is started.
  150.         Implementation of the sample rate setting is optional. If it
  151.           is implemented and the sample rate is valid, it will be
  152.           copied to the gsapidata sample rate field.
  153. --------s-2D--15-----------------------------
  154. INT 2D - Goldware Sound API (GSAPI) - STOP SOUND
  155.         AL = 15h
  156.         AH = AMIS multiplex number for the Goldware Sound API.
  157. Return: AX = 0000h if successful, 0001h if there is no sound to stop.
  158. Note:   If a sound is playing, it is stopped.
  159. --------s-2D--16-----------------------------
  160. INT 2D - Goldware Sound API (GSAPI) - PAUSE SOUND
  161.         AL = 16h
  162.         AH = AMIS multiplex number for the Goldware Sound API.
  163. Return: AX = 0000h if successful, 0001h if there is no sound to pause.
  164. Note:   If a sound is playing, it is temporarily paused. Playback can
  165.           be resumed by calling the AL=16h resume sound function.
  166. --------s-2D--17-----------------------------
  167. INT 2D - Goldware Sound API (GSAPI) - RESUME SOUND
  168.         AL = 17h
  169.         AH = AMIS multiplex number for the Goldware Sound API.
  170. Return: AX = 0000h if successful, 0001h if there is no sound to
  171.                resume.
  172. Note:   If a sound is paused using the AL=16h pause sound function,
  173.           playback is resumed from the point it was paused.
  174. --------s-2D--18-----------------------------
  175. INT 2D - Goldware Sound API (GSAPI) - BREAK SOUND LOOP
  176.         AL = 18h
  177.         AH = AMIS multiplex number for the Goldware Sound API.
  178.         BX = 0001h to break looping sample immediately, 0000h to break
  179.                loop after looping sample has played to the end.
  180. Return: AX = 0000h if successful, 0001h if there is no sound to break,
  181.                FFFFh if the function is not supported.
  182. Note:   Implementation of this function is optional, but if it is
  183.           implemented, it must not simply stop playing a sound, unless
  184.           the currently looping sample was the last.
  185.         Calling programs may want to call this function to determine
  186.           if loop breaking is possible and if not, use a different
  187.           method for breaking loops, for example by allowing users to
  188.           press a key to stop a playing sound.
  189. --------s-2D--19-----------------------------
  190. INT 2D - Goldware Sound API (GSAPI) - SPEAKER ON/OFF
  191.         AL = 19h
  192.         AH = AMIS multiplex number for the Goldware Sound API.
  193.         BX = 0000h to turn off the speaker, 0001h to turn it on.
  194. Return: Nothing.
  195. Note:   The speaker is assumed to already be on when the api is
  196.           opened.
  197. ---------------------------------------------
  198.  
  199. I have implemented a program loader which provides the interrupt
  200. service function with the Goldware Sound API. The current version of
  201. the program loader is named GCTVSAPI 1.00 and may be found in the
  202. archive GCTV100.ZIP. The current version of GCTVSAPI loads the
  203. Creative Labs CT-VOICE.DRV file for playing of .VOC files on Sound
  204. Blasters or 100% compatibles.
  205.  
  206. I hope that others will write program loaders or TSR's that implement
  207. the Goldware Sound API for other sound cards than the Sound Blasters,
  208. or even a Sound Blaster compatible implementation that does not
  209. require CT-VOICE.DRV.
  210.  
  211. If you have written a Goldware Sound API implementation, please let me
  212. know, so that I and the reg.sites can make it available for other
  213. users.
  214.  
  215. Enjoy!
  216.  
  217. Odinn Sorensen
  218.  
  219.  
  220. ______________________________________________________________________
  221.  
  222.                       Author contact information
  223. ______________________________________________________________________
  224.  
  225.  
  226. Goldware International
  227. Odinn Sorensen
  228. Boeslunde Byvej 114
  229. DK-4242 Boeslunde
  230. Denmark, Europe
  231.  
  232. Voice phone:    +45-53540015
  233. Fax:            +45-58162222
  234. Data, ModemV34: +45-58162222
  235. Data, EuroISDN: +45-58162223
  236.  
  237. Internet: odinn@ibm.net
  238.           odinn@winboss.dk
  239.  
  240. FidoNet: 2:236/77.0    (ModemV34)
  241.          2:236/1077.0  (EuroISDN)
  242.  
  243.  
  244. ______________________________________________________________________
  245.  
  246.