MusicKit  0.0.0
PerformMIDI.h
00001 /*
00002   $Id$
00003   Defined In: The MusicKit
00004 
00005   Description:
00006     MIDI driver typedefs, defines, and functions exported to other MusicKit frameworks.
00007     See the HeaderDoc header below.
00008 
00009   Original Author: Leigh M. Smith, <leigh@leighsmith.com>
00010 
00011   Copyright (c) 2000-2004 The MusicKit Project.
00012 
00013   Permission is granted to use and modify this code for commercial and non-commercial
00014   purposes so long as the author attribution and this copyright message remains intact
00015   and accompanies all derived code.
00016 */
00037 #ifndef _MKMD_
00038 #define _MKMD_
00039 
00040 /* We #include this file regardless of the setting of
00041    HAVE_CONFIG_H so that other applications compiling against this
00042    header don't have to define it. If you are seeing errors for
00043    MKPerformSndMIDIConfig.h not found, you haven't run ./configure 
00044  */
00045 #include "MKPerformSndMIDIConfig.h"
00046 #include <objc/objc.h> /* for BOOL */
00047 
00048 /* kludge around type definitions. This should be replaced. */
00049 typedef int kern_return_t;
00050 typedef int msg_header_t;
00051 typedef int boolean_t;
00052 
00061 #define MKMDPort int
00062 
00071 #define MKMDOwnerPort int
00072 
00082 #define MKMDReplyPort int
00083 
00090 typedef int MKMDReturn;
00091 
00103 #define MKMD_RECEPTION_USING_PORTS 0
00104 
00109 #define MKMD_PORT_NULL 0
00110 
00111 /* Each event consists of a byte and a time stamp. */
00115 typedef struct {
00117     int time;
00119     unsigned char byte;
00120 } MKMDRawEvent;
00121 
00126 typedef MKMDRawEvent *MKMDRawEventPtr;
00127 
00134 #define MKMD_MAX_EVENT 100
00135 
00142 #define MKMD_MAX_MSG_SIZE 1024  // More than enough
00143 
00150 #define MKMD_CLOCK_MODE_INTERNAL 0
00151 
00158 #define MKMD_CLOCK_MODE_MTC_SYNC 1
00159 
00160 /* error codes */
00167 #define MKMD_SUCCESS 0
00168 
00169 /* error codes */
00170 #define MKMD_ERROR_BUSY 100
00171 #define MKMD_ERROR_NOT_OWNER 101
00172 #define MKMD_ERROR_QUEUE_FULL 102
00173 #define MKMD_ERROR_BAD_MODE 103
00174 #define MKMD_ERROR_UNIT_UNAVAILABLE 104
00175 #define MKMD_ERROR_ILLEGAL_OPERATION 105
00176 #define MKMD_ERROR_UNKNOWN_ERROR 106
00177 
00178 /* exception codes */
00179 #define MKMD_EXCEPTION_MTC_STOPPED 1
00180 #define MKMD_EXCEPTION_MTC_STARTED_FORWARD 2
00181 #define MKMD_EXCEPTION_MTC_STARTED_REVERSE 3
00182 
00183 /* Defines for system ignores. */
00184 #define MKMD_IGNORE_CLOCK        0x0100
00185 #define MKMD_IGNORE_START        0x0400
00186 #define MKMD_IGNORE_CONTINUE     0x0800
00187 #define MKMD_IGNORE_STOP         0x1000
00188 #define MKMD_IGNORE_ACTIVE       0x4000
00189 #define MKMD_IGNORE_RESET        0x8000
00190 #define MKMD_IGNORE_REAL_TIME    0xdd00  /* All of the above */
00191 
00196 #define MKMD_PORT_A_UNIT 0
00197 
00202 #define MKMD_PORT_B_UNIT 1
00203 
00204 /* Reply function types. */
00217 typedef void (*MKMDDataReplyFunction)
00218     (MKMDReplyPort replyPort, short unit, MKMDRawEvent *events, unsigned int count);
00219 
00230 typedef void (*MKMDAlarmReplyFunction)
00231     (MKMDReplyPort replyPort, int requestedTime, int actualTime);
00232 
00241 typedef void (*MKMDExceptionReplyFunction)
00242     (MKMDReplyPort replyPort, int exception);
00243 
00253 typedef void (*MKMDQueueReplyFunction)
00254     (MKMDReplyPort replyPort, short unit);
00255 
00270 typedef struct _MKMDReplyFunctions {
00271     MKMDDataReplyFunction dataReply;
00272     MKMDAlarmReplyFunction alarmReply;
00273     MKMDExceptionReplyFunction exceptionReply;
00274     MKMDQueueReplyFunction queueReply;
00275 } MKMDReplyFunctions;
00276 
00284 PERFORM_API char *MKMDErrorString(MKMDReturn errorCode);
00285 
00294 PERFORM_API MKMDPort
00295     MKMDGetMIDIDeviceOnHost(const char *hostname);
00296 
00297 /******* Managing ownership of the driver ********/
00306 PERFORM_API MKMDReturn 
00307     MKMDBecomeOwner(MKMDPort mididriver_port, MKMDOwnerPort owner_port, MKMDReplyFunctions *replyFunctions);
00308 
00316 PERFORM_API MKMDReturn 
00317     MKMDReleaseOwnership(MKMDPort mididriver_port, MKMDOwnerPort owner_port);
00318 
00319 
00320 /*** Claiming a particular serial port (ownership of driver required) *****/
00331 PERFORM_API MKMDReturn 
00332     MKMDClaimUnit(BOOL input, MKMDPort driver, MKMDOwnerPort owner, short unit, void *userData);
00333 
00344 PERFORM_API MKMDReturn 
00345     MKMDReleaseUnit(BOOL input, MKMDPort driver, MKMDOwnerPort owner, short unit, void *userData);
00346 
00347 /******** Controlling the clock ****************/
00348 
00365 PERFORM_API MKMDReturn 
00366     MKMDSetClockMode(MKMDPort driver, MKMDOwnerPort owner, short synchUnit, int mode);
00367 
00381 PERFORM_API MKMDReturn 
00382     MKMDSetClockQuantum(MKMDPort driver, MKMDOwnerPort owner, int microseconds);
00383 
00397 PERFORM_API MKMDReturn 
00398     MKMDSetClockTime(MKMDPort driver, MKMDOwnerPort owner, int time);
00399 
00413 PERFORM_API MKMDReturn 
00414     MKMDGetClockTime(MKMDPort driver, MKMDOwnerPort owner, int *time);
00415 
00440 PERFORM_API MKMDReturn 
00441     MKMDGetMTCTime(MKMDPort driver, MKMDOwnerPort owner, short *format, short *hours, short *minutes, short *seconds, short *frames);
00442 
00454 PERFORM_API MKMDReturn 
00455     MKMDStartClock(MKMDPort driver, MKMDOwnerPort owner);
00456 
00468 PERFORM_API MKMDReturn 
00469     MKMDStopClock(MKMDPort driver, MKMDOwnerPort owner);
00470 
00471 
00472 /****************** Requesting asynchronous messages *******************/
00473 
00490 PERFORM_API MKMDReturn 
00491     MKMDRequestData(MKMDPort driver, MKMDOwnerPort owner, short unit, MKMDReplyPort replyPort);
00492 
00508 PERFORM_API MKMDReturn 
00509     MKMDRequestAlarm(MKMDPort driver, MKMDOwnerPort owner, MKMDReplyPort replyPort, int time);
00510 
00524 PERFORM_API MKMDReturn 
00525     MKMDRequestExceptions(MKMDPort driver, MKMDOwnerPort owner, MKMDReplyPort exceptionPort);
00526 
00546 PERFORM_API MKMDReturn 
00547     MKMDRequestQueueNotification(MKMDPort driver, MKMDOwnerPort owner, short unit, MKMDReplyPort notificationPort, int size);
00548 
00549 /****************** Receiving asynchronous messages *******************/
00550 
00562 PERFORM_API MKMDReturn 
00563     MKMDAwaitReply(MKMDReplyPort ports, MKMDReplyFunctions *funcs, int timeout);
00564 
00571 #define MKMD_NO_TIMEOUT (-1)
00572 
00582 PERFORM_API MKMDReturn 
00583     MKMDHandleReply(msg_header_t *msg, MKMDReplyFunctions *funcs);
00584 
00604 PERFORM_API MKMDReturn MKMDSetReplyCallback (
00605         MKMDPort mididriver_port,
00606         MKMDOwnerPort owner_port,
00607         short unit,
00608         void (*newCallbackFn)(void *),
00609         void *newCallbackParam);
00610 
00611 
00612 /****************** Writing MKMD data to the driver *********************/
00613 
00634 PERFORM_API MKMDReturn 
00635     MKMDSendData(MKMDPort driver, MKMDOwnerPort owner, short unit, MKMDRawEvent *data, unsigned int count);
00636 
00653 PERFORM_API MKMDReturn 
00654     MKMDGetAvailableQueueSize(MKMDPort driver, MKMDOwnerPort owner, short unit, int *size);
00655 
00670 PERFORM_API MKMDReturn 
00671     MKMDClearQueue(MKMDPort driver, MKMDOwnerPort owner, short unit);
00672 
00687 PERFORM_API MKMDReturn 
00688     MKMDFlushQueue(MKMDPort device_port, MKMDOwnerPort owner_port, short unit);
00689 
00699 PERFORM_API MKMDReturn 
00700     MKMDDownloadDLSInstruments(unsigned int *patches, int patchCount);
00701 
00714 PERFORM_API const char **
00715     MKMDGetAvailableDrivers(BOOL inputDrivers, unsigned int *selectedDriver);
00716 
00717 /********************* Controling how incoming data is formatted ***********/
00737 PERFORM_API MKMDReturn 
00738     MKMDFilterMessage(MKMDPort driver, MKMDOwnerPort owner, short unit, unsigned char statusByte, boolean_t filterIt);
00739 
00756 PERFORM_API MKMDReturn 
00757     MKMDParseInput(MKMDPort driver, MKMDOwnerPort owner, short unit, boolean_t parseIt);
00758 
00764 PERFORM_API char *MKMDErrorString(MKMDReturn errorCode);
00765 
00782 PERFORM_API MKMDReturn 
00783     MKMDSetSystemIgnores(MKMDPort driver, MKMDOwnerPort owner, short unit, unsigned int ignoreBits);
00784 
00785 
00786 #endif /* _MKMD_ */
00787