MusicKit: midi_driver.h Source File

00001 /*
00002   $Id: midi_driver.h 1000 2001-02-13 00:08:47Z leigh $
00003   Defined In: The MusicKit
00004 
00005   Description: MIDI driver typedefs, defines, and functions
00006   Original Author: David Jaffe
00007 
00008   Copyright (c) 1988-1992, NeXT Computer, Inc.
00009   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00010   Portions Copyright (c) 1994 Stanford University
00011 */
00012 /*
00013 Modification history:
00014 
00015   $Log$
00016   Revision 1.7  2001/02/13 00:08:47  leigh
00017   Added MKMDErrorString()
00018 
00019   Revision 1.6  2000/12/07 00:09:20  leigh
00020   Added missing function prototypes, changed MKMDPort et al to mach_port_t
00021 
00022   Revision 1.5  2000/11/29 23:21:26  leigh
00023   Renamed MD functions to MKMD
00024 
00025   Revision 1.4  2000/06/13 22:03:31  leigh
00026   Removed incorrect avoidance of MKMD_ functions when on m68k
00027 
00028   Revision 1.3  2000/01/27 18:15:43  leigh
00029   upgraded to new typedef names for Mach
00030 
00031   Revision 1.2  1999/11/24 17:30:38  leigh
00032   Added a MKMDDownloadDLSInstruments stub
00033 
00034   Revision 1.2  1999/07/29 01:26:06  leigh
00035   Added Win32 compatibility, CVS logs, SBs changes
00036 
00037 */
00038 #ifndef _MKMD_
00039 #define _MKMD_
00040 
00041 // Determine the MacOsX derivative being compiled on. This is a passing phase (MOXS 1.2) until the two O.S. merge API
00042 #define macosx_server (defined(__ppc__) && defined(ppc))
00043 #define openstep_i386 (i386 && !WIN32)
00044 // earlier OpenStep incantations had NSPort as a concrete class.
00045 #if macosx_server || WIN32 || m68k || openstep_i386
00046 #define NSMachPort NSPort
00047 #endif
00048 
00049 #import <mach/kern_return.h>
00050 #import <mach/message.h>
00051 #import <mach/port.h>
00052 #import <mach/boolean.h>
00053 
00054 #define MKMDPort mach_port_t
00055 #define MKMDOwnerPort mach_port_t
00056 #define MKMDReplyPort mach_port_t
00057 typedef kern_return_t MKMDReturn;
00058 
00059 #define MKMD_RECEPTION_USING_PORTS 1
00060 #define MKMD_SUCCESS KERN_SUCCESS
00061 #define MKMD_PORT_NULL PORT_NULL
00062 
00063 /* Each event consists of a byte and a time stamp. */
00064 typedef struct {
00065     int time;             /* Absolute time in quanta */
00066     unsigned char byte;   /* The byte */
00067 } MKMDRawEvent;
00068 
00069 /* MKMD_MAX_EVENT is the maximum number of events that can be
00070  * sent to or received from the driver in a single package. 
00071  */
00072 #define MKMD_MAX_EVENT 100
00073    
00074 /* MKMD_MAX_MSG_SIZE is the maximum size of the message you
00075  * can receive from the driver. 
00076  */
00077 #define MKMD_MAX_MSG_SIZE 1024  // More than enough
00078 
00079 /* Clock modes */
00080 #define MKMD_CLOCK_MODE_INTERNAL 0
00081 #define MKMD_CLOCK_MODE_MTC_SYNC 1
00082 
00083 /* error codes */
00084 #define MKMD_ERROR_BUSY 100
00085 #define MKMD_ERROR_NOT_OWNER 101
00086 #define MKMD_ERROR_QUEUE_FULL 102
00087 #define MKMD_ERROR_BAD_MODE 103
00088 #define MKMD_ERROR_UNIT_UNAVAILABLE 104
00089 #define MKMD_ERROR_ILLEGAL_OPERATION 105
00090 #define MKMD_ERROR_UNKNOWN_ERROR 106
00091 
00092 /* exception codes */
00093 #define MKMD_EXCEPTION_MTC_STOPPED 1
00094 #define MKMD_EXCEPTION_MTC_STARTED_FORWARD 2
00095 #define MKMD_EXCEPTION_MTC_STARTED_REVERSE 3
00096 
00097 /* Defines for system ignores. */
00098 #define MKMD_IGNORE_CLOCK        0x0100
00099 #define MKMD_IGNORE_START        0x0400
00100 #define MKMD_IGNORE_CONTINUE     0x0800
00101 #define MKMD_IGNORE_STOP         0x1000
00102 #define MKMD_IGNORE_ACTIVE       0x4000
00103 #define MKMD_IGNORE_RESET        0x8000
00104 #define MKMD_IGNORE_REAL_TIME    0xdd00  /* All of the above */
00105 
00106 #define MKMD_PORT_A_UNIT 0
00107 #define MKMD_PORT_B_UNIT 1
00108 
00109 /* Reply function types. */
00110 typedef void (*MKMDDataReplyFunction)
00111     (mach_port_t replyPort, short unit, MKMDRawEvent *events, unsigned int count);
00112 typedef void (*MKMDAlarmReplyFunction)
00113     (mach_port_t replyPort, int requestedTime, int actualTime);
00114 typedef void (*MKMDExceptionReplyFunction)
00115     (mach_port_t replyPort, int exception);
00116 typedef void (*MKMDQueueReplyFunction)
00117     (mach_port_t replyPort, short unit);
00118 
00119 /* Struct for passing reply functions to midi_driver library. */
00120 typedef struct _MKMDReplyFunctions {
00121     MKMDDataReplyFunction dataReply;
00122     MKMDAlarmReplyFunction alarmReply;
00123     MKMDExceptionReplyFunction exceptionReply;
00124     MKMDQueueReplyFunction queueReply;
00125 } MKMDReplyFunctions;
00126 
00127 // returns NULL if unable to find the hostname, otherwise whatever value for MKMDPort
00128 // that has meaning.
00129 extern MKMDPort
00130    MKMDGetMIDIDeviceOnHost(const char *hostname);
00131 
00132 /******* Managing ownership of the driver ********/
00133 extern kern_return_t 
00134     MKMDBecomeOwner(mach_port_t driver, mach_port_t owner);
00135 extern kern_return_t 
00136     MKMDReleaseOwnership(mach_port_t driver, mach_port_t owner);
00137 
00138 /*** Claiming a particular serial port (ownership of driver required) *****/
00139 extern kern_return_t 
00140     MKMDClaimUnit(mach_port_t driver, mach_port_t owner, short unit);
00141 extern kern_return_t 
00142     MKMDReleaseUnit(mach_port_t driver, mach_port_t owner, short unit);
00143 
00144 /******** Controlling the clock ****************/
00145 extern kern_return_t 
00146     MKMDSetClockMode(mach_port_t driver, mach_port_t owner, short synchUnit, int mode);
00147 extern kern_return_t 
00148     MKMDSetClockQuantum(mach_port_t driver, mach_port_t owner, int microseconds);
00149 extern kern_return_t 
00150     MKMDSetClockTime(mach_port_t driver, mach_port_t owner, int time);
00151 extern kern_return_t 
00152     MKMDGetClockTime(mach_port_t driver, mach_port_t owner, int *time);
00153 extern kern_return_t 
00154     MKMDGetMTCTime(mach_port_t driver, mach_port_t owner, short *format, short *hours, short *minutes, short *seconds, short *frames);
00155 extern kern_return_t 
00156     MKMDStartClock(mach_port_t driver, mach_port_t owner);
00157 extern kern_return_t 
00158     MKMDStopClock(mach_port_t driver, mach_port_t owner);
00159 
00160 /****************** Requesting asynchronous messages *******************/
00161 extern kern_return_t 
00162     MKMDRequestData(mach_port_t driver, mach_port_t owner, short unit, mach_port_t replyPort);
00163 extern kern_return_t 
00164     MKMDRequestAlarm(mach_port_t driver, mach_port_t owner, mach_port_t replyPort, int time);
00165 extern kern_return_t 
00166     MKMDRequestExceptions(mach_port_t driver, mach_port_t owner, mach_port_t exceptionPort);
00167 extern kern_return_t 
00168     MKMDRequestQueueNotification(mach_port_t driver, mach_port_t owner, short unit, mach_port_t notificationPort, int size);
00169 
00170 /****************** Receiving asynchronous messages *******************/
00171 extern kern_return_t 
00172     MKMDAwaitReply(mach_port_t ports, MKMDReplyFunctions *funcs, int timeout);
00173 
00174 #define MKMD_NO_TIMEOUT (-1)
00175 
00176 extern kern_return_t 
00177     MKMDHandleReply(msg_header_t *msg,MKMDReplyFunctions *funcs);
00178 
00179 /****************** Writing MKMD data to the driver *********************/
00180 extern kern_return_t 
00181     MKMDSendData(mach_port_t driver, mach_port_t owner, short unit, MKMDRawEvent *data, unsigned int count);
00182 extern kern_return_t 
00183     MKMDGetAvailableQueueSize(mach_port_t driver, mach_port_t owner, short unit, int *size);
00184 extern kern_return_t 
00185     MKMDClearQueue(mach_port_t driver, mach_port_t owner, short unit);
00186 extern kern_return_t 
00187     MKMDFlushQueue(mach_port_t device_port, port_name_t owner_port, short unit);
00188 extern kern_return_t 
00189     MKMDDownloadDLSInstruments(unsigned int *patches, int patchCount);
00190 /* return the names of available drivers */
00191 extern const char **
00192     MKMDGetAvailableDrivers(unsigned int *selectedDriver);
00193 
00194 /* interpreting error codes into a readable string. */
00195 extern char *MKMDErrorString(MKMDReturn errorCode);
00196 
00197 /********************* Controling how incoming data is formated ***********/
00198 extern kern_return_t 
00199     MKMDFilterMessage(mach_port_t driver, mach_port_t owner, short unit, unsigned char statusByte, boolean_t filterIt);
00200 extern kern_return_t 
00201     MKMDParseInput(mach_port_t driver, mach_port_t owner, short unit, boolean_t parseIt);
00202 
00203 /* This will be obsolete soon: */
00204 extern kern_return_t 
00205     MKMDSetSystemIgnores(mach_port_t driver, mach_port_t owner, short unit, unsigned int ignoreBits);
00206 
00207 /*
00208  * Originally from <MusicKit/midi_driver_compatability.h
00209  * Author: David Jaffe
00210  * CCRMA, Stanford University, 1994.
00211  *
00212  * These definitions provide compatability between the Music Kit
00213  * MIDI driver and the NeXT hardware driver.  
00214  *
00215  * Actually, now we only use the mididriver versions
00216  * for NeXT hardware, and all other architectures use DriverKit
00217  * MusicKit MIDI drivers. However all architectures use the MKMD_ versions
00218  * so these definitions apply for m68k in addition to non-NeXT systems.
00219  */
00220 
00221 /* These macros make the MusicKit functions and macros look like those in libdsp. */
00222 #if m68k
00223 #define MKMDRawEvent                       MIDIRawEvent
00224 #define MKMD_MAX_EVENT                     MIDI_MAX_EVENT
00225 #define MKMD_MAX_MSG_SIZE                  MIDI_MAX_MSG_SIZE
00226 #define MKMD_CLOCK_MODE_INTERNAL           MIDI_CLOCK_MODE_INTERNAL
00227 #define MKMD_CLOCK_MODE_MTC_SYNC           MIDI_CLOCK_MODE_MTC_SYNC
00228 #define MKMD_ERROR_BUSY                    MIDI_ERROR_BUSY
00229 #define MKMD_ERROR_NOT_OWNER               MIDI_ERROR_NOT_OWNER
00230 #define MKMD_ERROR_QUEUE_FULL              MIDI_ERROR_QUEUE_FULL
00231 #define MKMD_ERROR_BAD_MODE                MIDI_ERROR_BAD_MODE
00232 #define MKMD_ERROR_UNIT_UNAVAILABLE        MIDI_ERROR_UNIT_UNAVAILABLE
00233 #define MKMD_ERROR_ILLEGAL_OPERATION       MIDI_ERROR_ILLEGAL_OPERATION
00234 #define MKMD_ERROR_UNKNOWN_ERROR           MIDI_ERROR_UNKNOWN_ERROR
00235 #define MKMD_EXCEPTION_MTC_STOPPED         MIDI_EXCEPTION_MTC_STOPPED
00236 #define MKMD_EXCEPTION_MTC_STARTED_FORWARD MIDI_EXCEPTION_MTC_STARTED_FORWARD
00237 #define MKMD_EXCEPTION_MTC_STARTED_REVERSE MIDI_EXCEPTION_MTC_STARTED_REVERSE
00238 #define MKMD_IGNORE_CLOCK                  MIDI_IGNORE_CLOCK
00239 #define MKMD_IGNORE_START                  MIDI_IGNORE_START
00240 #define MKMD_IGNORE_CONTINUE               MIDI_IGNORE_CONTINUE
00241 #define MKMD_IGNORE_STOP                   MIDI_IGNORE_STOP
00242 #define MKMD_IGNORE_ACTIVE                 MIDI_IGNORE_ACTIVE
00243 #define MKMD_IGNORE_RESET                  MIDI_IGNORE_RESET
00244 #define MKMD_IGNORE_REAL_TIME              MIDI_IGNORE_REAL_TIME
00245 #define MKMDDataReplyFunction              MIDIDataReplyFunction
00246 #define MKMDAlarmReplyFunction             MIDIAlarmReplyFunction
00247 #define MKMDExceptionReplyFunction         MIDIExceptionReplyFunction
00248 #define MKMDQueueReplyFunction             MIDIQueueReplyFunction
00249 #define MKMDReplyFunctions                 MIDIReplyFunctions
00250 #define MKMDBecomeOwner                    MIDIBecomeOwner
00251 #define MKMDReleaseOwnership               MIDIReleaseOwnership
00252 #define MKMDClaimUnit                      MIDIClaimUnit
00253 #define MKMDReleaseUnit                    MIDIReleaseUnit
00254 #define MKMDSetClockMode                   MIDISetClockMode
00255 #define MKMDSetClockQuantum                MIDISetClockQuantum
00256 #define MKMDSetClockTime                   MIDISetClockTime
00257 #define MKMDGetClockTime                   MIDIGetClockTime
00258 #define MKMDGetMTCTime                     MIDIGetMTCTime
00259 #define MKMDStartClock                     MIDIStartClock
00260 #define MKMDStopClock                      MIDIStopClock
00261 #define MKMDSetSystemIgnores               MIDISetSystemIgnores
00262 #define MKMDRequestData                    MIDIRequestData
00263 #define MKMDRequestAlarm                   MIDIRequestAlarm
00264 #define MKMDRequestExceptions              MIDIRequestExceptions
00265 #define MKMDRequestQueueNotification       MIDIRequestQueueNotification
00266 #define MKMDAwaitReply                     MIDIAwaitReply
00267 #define MKMD_NO_TIMEOUT                    MIDI_NO_TIMEOUT
00268 #define MKMDHandleReply                    MIDIHandleReply
00269 #define MKMDSendData                       MIDISendData
00270 #define MKMDGetAvailableQueueSize          MIDIGetAvailableQueueSize
00271 #define MKMDClearQueue                     MIDIClearQueue
00272 #define MKMDFlushQueue                     MIDIFlushQueue
00273 #define MKMDFilterMessage                  MIDIFilterMessage
00274 #define MKMDParseInput                     MIDIParseInput
00275 #endif // m68K compatability
00276 
00277 #endif _MKMD_
00278