MusicKit: midi_driver.h Source File

00001 /*
00002   $Id: midi_driver.h 860 2000-12-07 19:32:34Z leigh $
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     MIDI driver typedefs, defines, and functions exported to other MusicKit frameworks.
00007 
00008     This file provides compatability between the various platform dependent 
00009     MIDI drivers used by the MusicKit.
00010     We only use the mididriver versions for NeXT hardware, all other
00011     architectures use MusicKit MIDI drivers using the DriverKit for OpenStep,
00012     DirectMusic for Windows, CoreMIDI/QTMA for MacOS X etc.
00013     The other sobering thought about this framework is that it does not rely on
00014     any OpenStep/Cocoa API types, unless they are declared here. 
00015     Therefore cStrings and ints are de rigeur...
00016 
00017   Original Author: David Jaffe
00018 
00019   Copyright (c) 1988-1992, NeXT Computer, Inc.
00020   Portions Copyright (c) 1994 NeXT Computer, Inc. and reproduced under license from NeXT
00021   Portions Copyright (c) 1994 Stanford University
00022   Portions Copyright (c) 2000 The MusicKit Project.
00023 */
00024 /*
00025 Modification history:
00026 
00027   $Log$
00028   Revision 1.1  2000/12/07 19:32:34  leigh
00029   Initial revision
00030 
00031   Revision 1.5  2000/11/13 23:36:57  leigh
00032   Added back legacy NeXT MIDI port macros, more ports are now MKMDReplyPort, mach headers are removed
00033 
00034   Revision 1.4  2000/11/10 23:13:33  leigh
00035   Changed return and port types to be more transparent, reversed #define so that 68k code will use the MIDI versions, everyone else uses the MKMD versions.
00036 
00037   Revision 1.3  2000/10/29 06:05:54  leigh
00038   Moved to MKMDPort types for ports. Changed name prefixes to be specific to the MusicKit. Added MKMDGetMIDIDeviceOnHost.
00039 
00040   Revision 1.2  2000/05/05 22:41:44  leigh
00041   kludge around type definitions
00042 
00043   Revision 1.1  2000/03/11 01:42:20  leigh
00044   Initial Release
00045 
00046   Revision 1.1.1.1  2000/01/14 00:14:34  leigh
00047   Initial revision
00048 */
00049 #ifndef _MKMD_
00050 #define _MKMD_
00051 
00052 #import <Foundation/Foundation.h>
00053 #import <mach/kern_return.h>
00054 
00055 // This allows us to introduce anything necessary for library declarations, namely for Windows. Unused in MacOS X.
00056 #define PERFORM_API
00057 
00058 // kludge around type definitions. This should be replaced.
00059 typedef int msg_header_t;  // mach_msg_header_t
00060 
00061 #define MKMD_RECEPTION_USING_PORTS 0
00062 #define MKMD_PORT_NULL 0
00063 
00064 #define MKMDPort int
00065 #define MKMDOwnerPort int
00066 #define MKMDReplyPort int
00067 typedef int MKMDReturn;
00068 
00069 /* Each event consists of a byte and a time stamp. */
00070 typedef struct {
00071     int time;             /* Absolute time in quanta */
00072     unsigned char byte;   /* The byte */
00073 } MKMDRawEvent, *MKMDRawEventPtr;
00074 
00075 /* MKMD_MAX_EVENT is the maximum number of events that can be
00076  * sent to or received from the driver in a single package. 
00077  */
00078 #define MKMD_MAX_EVENT 100
00079    
00080 /* MKMD_MAX_MSG_SIZE is the maximum size of the message you
00081  * can receive from the driver. 
00082  */
00083 #define MKMD_MAX_MSG_SIZE 1024  // More than enough
00084 
00085 /* Clock modes */
00086 #define MKMD_CLOCK_MODE_INTERNAL 0
00087 #define MKMD_CLOCK_MODE_MTC_SYNC 1
00088 
00089 /* error codes */
00090 #define MKMD_SUCCESS KERN_SUCCESS  // use this until all the MKMidi checks have been converted to MKMD_SUCCESS.
00091 //#define MKMD_SUCCESS 0
00092 #define MKMD_ERROR_BUSY 100
00093 #define MKMD_ERROR_NOT_OWNER 101
00094 #define MKMD_ERROR_QUEUE_FULL 102
00095 #define MKMD_ERROR_BAD_MODE 103
00096 #define MKMD_ERROR_UNIT_UNAVAILABLE 104
00097 #define MKMD_ERROR_ILLEGAL_OPERATION 105
00098 #define MKMD_ERROR_UNKNOWN_ERROR 106
00099 
00100 /* exception codes */
00101 #define MKMD_EXCEPTION_MTC_STOPPED 1
00102 #define MKMD_EXCEPTION_MTC_STARTED_FORWARD 2
00103 #define MKMD_EXCEPTION_MTC_STARTED_REVERSE 3
00104 
00105 /* Defines for system ignores. */
00106 #define MKMD_IGNORE_CLOCK        0x0100
00107 #define MKMD_IGNORE_START        0x0400
00108 #define MKMD_IGNORE_CONTINUE     0x0800
00109 #define MKMD_IGNORE_STOP         0x1000
00110 #define MKMD_IGNORE_ACTIVE       0x4000
00111 #define MKMD_IGNORE_RESET        0x8000
00112 #define MKMD_IGNORE_REAL_TIME    0xdd00  /* All of the above */
00113 
00114 // legacy MIDI port definitions referring to NeXT serial ports
00115 #define MKMD_PORT_A_UNIT 0
00116 #define MKMD_PORT_B_UNIT 1
00117 
00118 /* Reply function types. */
00119 typedef void (*MKMDDataReplyFunction)
00120     (port_t replyPort, short unit, MKMDRawEvent *events, unsigned int count);
00121 typedef void (*MKMDAlarmReplyFunction)
00122     (port_t replyPort, int requestedTime, int actualTime);
00123 typedef void (*MKMDExceptionReplyFunction)
00124     (port_t replyPort, int exception);
00125 typedef void (*MKMDQueueReplyFunction)
00126     (port_t replyPort, short unit);
00127 
00128 /* Struct for passing reply functions to midi_driver library. */
00129 typedef struct _MKMDReplyFunctions {
00130     MKMDDataReplyFunction dataReply;           // called when we have received MIDI data.
00131     MKMDAlarmReplyFunction alarmReply;         // called to alert the caller of problems.
00132     MKMDExceptionReplyFunction exceptionReply; // called to alert the caller of problems (what distinction)
00133     MKMDQueueReplyFunction queueReply;         // 
00134 } MKMDReplyFunctions;
00135 
00136 /******* Locating the driver ********/
00137 // returns NULL if unable to find the hostname, otherwise whatever value for MKMDPort
00138 // that has meaning.
00139 PERFORM_API MKMDPort
00140     MKMDGetMIDIDeviceOnHost(const char *hostname);
00141 
00142 /******* Managing ownership of the driver ********/
00143 /* Routine MKMDBecomeOwner */
00144 PERFORM_API MKMDReturn 
00145     MKMDBecomeOwner(MKMDPort mididriver_port, MKMDOwnerPort owner_port);
00146 /* Routine MKMDReleaseOwnership */
00147 PERFORM_API MKMDReturn 
00148     MKMDReleaseOwnership(MKMDPort mididriver_port, MKMDOwnerPort owner_port);
00149 
00150 /*** Claiming a particular serial port (ownership of driver required) *****/
00151 PERFORM_API MKMDReturn 
00152     MKMDClaimUnit(MKMDPort driver, MKMDOwnerPort owner, short unit);
00153 PERFORM_API MKMDReturn 
00154     MKMDReleaseUnit(MKMDPort driver, MKMDOwnerPort owner, short unit);
00155 
00156 /******** Controlling the clock ****************/
00157 PERFORM_API MKMDReturn 
00158     MKMDSetClockMode(MKMDPort driver, MKMDOwnerPort owner, short synchUnit, int mode);
00159 // set the period of each clock tick in microseconds.
00160 PERFORM_API MKMDReturn 
00161     MKMDSetClockQuantum(MKMDPort driver, MKMDOwnerPort owner, int microseconds);
00162 PERFORM_API MKMDReturn 
00163     MKMDSetClockTime(MKMDPort driver, MKMDOwnerPort owner, int time);
00164 PERFORM_API MKMDReturn 
00165     MKMDGetClockTime(MKMDPort driver, MKMDOwnerPort owner, int *time);
00166 PERFORM_API MKMDReturn 
00167     MKMDGetMTCTime(MKMDPort driver, MKMDOwnerPort owner, short *format, short *hours, short *minutes, short *seconds, short *frames);
00168 PERFORM_API MKMDReturn 
00169     MKMDStartClock(MKMDPort driver, MKMDOwnerPort owner);
00170 PERFORM_API MKMDReturn 
00171     MKMDStopClock(MKMDPort driver, MKMDOwnerPort owner);
00172 
00173 /****************** Requesting asynchronous messages *******************/
00174 PERFORM_API MKMDReturn 
00175     MKMDRequestData(MKMDPort driver, MKMDOwnerPort owner, short unit, MKMDReplyPort replyPort);
00176 PERFORM_API MKMDReturn 
00177     MKMDRequestAlarm(MKMDPort driver, MKMDOwnerPort owner, MKMDReplyPort replyPort, int time);
00178 PERFORM_API MKMDReturn 
00179     MKMDRequestExceptions(MKMDPort driver, MKMDOwnerPort owner, port_t exceptionPort);
00180 PERFORM_API MKMDReturn 
00181     MKMDRequestQueueNotification(MKMDPort driver, MKMDOwnerPort owner, short unit, MKMDReplyPort notificationPort, int size);
00182 
00183 /****************** Receiving asynchronous messages *******************/
00184 // This waits until a reply is received on port_set
00185 PERFORM_API MKMDReturn 
00186     MKMDAwaitReply(MKMDReplyPort ports, MKMDReplyFunctions *funcs, int timeout);
00187 
00188 #define MKMD_NO_TIMEOUT (-1)
00189 
00190 PERFORM_API MKMDReturn 
00191     MKMDHandleReply(msg_header_t *msg, MKMDReplyFunctions *funcs);
00192 
00193 /* Routine MKMDSetReplyCallback - this is called to nominate a function to be called on reception of events
00194 instead of sending a message to a Mach port */
00195 PERFORM_API MKMDReturn MKMDSetReplyCallback (
00196         MKMDPort mididriver_port,
00197         MKMDOwnerPort owner_port,
00198         short unit,
00199         void (*newCallbackFn)(void *),
00200         void *newCallbackParam);
00201 
00202 /****************** Writing MKMD data to the driver *********************/
00203 PERFORM_API MKMDReturn 
00204     MKMDSendData(MKMDPort driver, MKMDOwnerPort owner, short unit, MKMDRawEvent *data, unsigned int count);
00205 PERFORM_API MKMDReturn 
00206     MKMDGetAvailableQueueSize(MKMDPort driver, MKMDOwnerPort owner, short unit, int *size);
00207 PERFORM_API MKMDReturn 
00208     MKMDClearQueue(MKMDPort driver, MKMDOwnerPort owner, short unit);
00209 PERFORM_API MKMDReturn 
00210     MKMDFlushQueue(MKMDPort device_port, MKMDOwnerPort owner_port, short unit);
00211 /* download the patch numbers (MSB,LSB,patch) to the sound card */
00212 PERFORM_API MKMDReturn 
00213     MKMDDownloadDLSInstruments(unsigned int *patches, int patchCount);
00214 /* return the names of available drivers */
00215 PERFORM_API const char **
00216     MKMDGetAvailableDrivers(unsigned int *selectedDriver);
00217 
00218 /********************* Controling how incoming data is formated ***********/
00219 PERFORM_API MKMDReturn 
00220     MKMDFilterMessage(MKMDPort driver, MKMDOwnerPort owner, short unit, unsigned char statusByte, boolean_t filterIt);
00221 PERFORM_API MKMDReturn 
00222     MKMDParseInput(MKMDPort driver, MKMDOwnerPort owner, short unit, boolean_t parseIt);
00223 
00224 /* This will be obsolete soon: */
00225 PERFORM_API MKMDReturn 
00226     MKMDSetSystemIgnores(MKMDPort driver, MKMDOwnerPort owner, short unit, unsigned int ignoreBits);
00227 
00228 #endif _MKMD_
00229