home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / driver / sound / dmsmpu / program.doc < prev    next >
Encoding:
Text File  |  1993-02-22  |  6.1 KB  |  177 lines
  1.                         Generic MPU-401 Device Driver
  2.                  Copyright (C) 1990-1993, Delta Music Systems
  3.  
  4.  
  5.                            Developer Instructions
  6.  
  7.  
  8.  
  9. Introduction
  10.  
  11. The generic MPU-401 Device Driver is for MIDI interfaces in AT compatible
  12. systems with an ISA bus.  It was written under OS/2 1.21, and has been
  13. tested under 1.21, 1.3, 2.0, and 2.1(beta).
  14.  
  15. The device driver supports the complete set of MPU commands.  Extensions
  16. specific to OS/2 have been added, and are available through the DMS MPU
  17. Interface Library.  If you are interested in purchasing the library, please
  18. use the order form (see the file ORDER.FRM).
  19.  
  20. This software is not in the public domain; however, it may be distributed
  21. freely so long as it is not bundled with any commercial product, or any fee
  22. beyond duplication and shipping is charged for distribution.  If you would
  23. like information on distributing this software with another product, please
  24. contact us at the address below.
  25.  
  26. Delta Music Systems
  27. 2615 Ginghamsburg-Frederick Rd.
  28. Tipp City, OH  45371
  29.  
  30. If you would like to be notified of future products from Delta Music Systems,
  31. please fill out and return the registration form (see the file REGISTER.FRM).
  32.  
  33.  
  34.  
  35. Developer Instructions
  36.  
  37. The generic MPU-401 device driver is accessed through the DOS API provided
  38. by OS/2.  The published interface includes only those functions that provide
  39. complete MPU-401 compatibility.  Additional functionality, such as blocking
  40. reads and packet-oriented messages, is available through the DMS MPU Interface
  41. Library.
  42.  
  43. The following table lists the published interface to the generic MPU-401
  44. device driver.  All numbers are in hexadecimal unless otherwise indicated.
  45.  
  46. Please take careful note of the changes for the OS/2 2.x Device Interface.
  47.  
  48. ****************************************************************************
  49.  
  50. OS/2 1.x:
  51. USHORT DosOpen("MPU401",
  52.                PHFILE  phf,
  53.                PUSHORT pusAction, 
  54.                0L, 
  55.                FILE_NORMAL,
  56.                FILE_OPEN, 
  57.                OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYREADWRITE,
  58.                0L)
  59.  
  60. phf          The address of the variable that receives the handle returned by
  61.              OS/2.  This handle will be used for all other functions.
  62.  
  63. pusAction    This variable is not utilized, but must still be present.
  64.  
  65. Return Value
  66.  
  67. The return value is zero if the function is successful. Otherwise, it is an
  68. error value, which may be one of the following:
  69.  
  70.      ERROR_ACCESS_DENIED
  71.      ERROR_FILE_NOT_FOUND
  72.      ERROR_INVALID_ACCESS
  73.      ERROR_INVALID_PARAMETER
  74.      ERROR_OPEN_FAILED
  75.      ERROR_PATH_NOT_FOUND
  76.      ERROR_SHARING_BUFFER_EXCEEDED
  77.      ERROR_SHARING_VIOLATION
  78.      ERROR_TOO_MANY_OPEN_FILES
  79.  
  80. ****************************************************************************
  81.  
  82. USHORT DosClose(HFILE hf)
  83.  
  84. hf         Identifies the device to close. This handle must have been created
  85.            by using the DosOpen function.
  86.  
  87. Return Value
  88.  
  89. The return value is zero if the function is successful. Otherwise, it is an
  90. error value, which may be one of the following:
  91.  
  92.      ERROR_ACCESS_DENIED
  93.      ERROR_FILE_NOT_FOUND
  94.      ERROR_INVALID_HANDLE
  95.  
  96. ****************************************************************************
  97.  
  98. USHORT DosRead(HFILE hf, BYTE *Buffer, USHORT BufSize, PUSHORT BytesRead)
  99.  
  100. The DosRead function reads up to a specified number of bytes of data from a
  101. file into a buffer. The function may read fewer than the specified number of
  102. bytes if it reaches the end of the file.
  103.  
  104. hf            Identifies the device to be read. This handle must have been
  105.               created by using the DosOpen function.
  106.  
  107. Buffer        Points to the buffer that receives the data.
  108.  
  109. BufSize       Specifies the size of the buffer.
  110.  
  111. pcbBytesRead  Points to the variable that receives the number of bytes read
  112.               from the file.  If no data has been received by the interface,
  113.               this value may be zero.
  114.  
  115. Return Value
  116.  
  117. The return value is zero if the function is successful. Otherwise, it is an
  118. error value, which may be one of the following:
  119.  
  120.      ERROR_ACCESS_DENIED
  121.      ERROR_INVALID_HANDLE
  122.  
  123. ****************************************************************************
  124.  
  125. USHORT DosWrite(HFILE hf, BYTE *Buffer, USHORT BufSize, PUSHORT pBytesWritten)
  126.  
  127. hf             Identifies the device that receives the data. This handle
  128.                must have been created by using the DosOpen function.
  129.  
  130. Buffer         Points to the buffer that contains the data to write.
  131.  
  132. BufSize        Specifies the size of the Buffer.
  133.  
  134. pBytesWritten  Points to the variable receiving the number of bytes written.
  135.  
  136. Return Value
  137.  
  138. The return value is zero if the function is successful. Otherwise, it is an
  139. error value, which may be one of the following:
  140.  
  141.      ERROR_ACCESS_DENIED
  142.      ERROR_INVALID_HANDLE
  143.  
  144. ****************************************************************************
  145.  
  146. USHORT DosDevIOCtl(PVOID  pvData,
  147.                    PVOID  pvParms,
  148.                    USHORT usFunction,
  149.                    USHORT usCategory,
  150.                    HFILE  hf)
  151.  
  152. pvData      Points to a buffer that contains the length of the Parm buffer
  153.                                                 for variable length messages.
  154.  
  155. pvParms     Points to a buffer that contains any data to be transmitted, or
  156.             to store data being returned.  The length of this buffer is not
  157.             checked by the device driver.
  158.  
  159. usFunction  the function number is equivalent to the MPU command number.
  160.             For example, to reset the device, use a function code of FF.
  161.  
  162. usCategory  Category 80 is used for MPU commands
  163.  
  164. hf          Identifies the device that receives the command. This handle
  165.             must have been created by using the DosOpen function.
  166.  
  167. Return Value
  168.  
  169. In addition to the system error values, the DosDevIOCtl function returns
  170. device driver return-value information.
  171.  
  172. The error value may be one of the following:
  173.  
  174.      ERROR_INVALID_CATEGORY
  175.  
  176. ****************************************************************************
  177.