home *** CD-ROM | disk | FTP | other *** search
/ Computer Music Interactif…cial Edition 1999 Winter / cd 3.iso / pc / Mac / Shares / Midishare™1.68 / Development Tools / Libraries / MidiFiles / MIDIFilesLibHelp < prev    next >
Encoding:
Text File  |  1996-04-18  |  12.7 KB  |  394 lines
  1. æKY CopyrightNotice
  2. æC  Copyright GRAME, Inc. 1989-1992, All rights reserved.
  3. 411 - MidiShare Help - MPW 3.2 Beta Release.
  4. Friday, January 24, 1992 9:57:37 AM
  5.  
  6. æKY Help
  7. MIDIFilesLibHelp
  8. æKL Summary
  9.  
  10. isTrackOpen
  11. MidiFileChooseTrack
  12. MidiFileClose
  13. MidiFileCloseTrack
  14. MidiFileCreate
  15. MidiFileGetVersion
  16. MidiFileNewTrack
  17. MidiFileOpen
  18. MidiFileOpenTrack
  19. MidiFileReadEv
  20. MidiFileReadTrack
  21. MidiFileWriteEv
  22. MidiFileWriteTrack
  23. MidiFileGetMFErrno
  24. MidiFileGetErrno
  25.  
  26.  
  27. æKY Summary
  28. æC :
  29.  
  30.                Functions to read and write MIDIFile format files
  31. ______________________________________________________________________________
  32. MidiFileGetVersion       * return the version numbers (src and format)    *
  33.  
  34. MidiFileOpen             * open an existing MIDI file                     *
  35. MidiFileClose            * close a file opened with MidiFileOpen          *
  36. MidiFileCreate           * create a MIDI file                             *
  37.  
  38. MidiFileOpenTrack        * open an existing track                         *
  39. MidiFileNewTrack         * create a new track                             *
  40. MidiFileCloseTrack       * close a track                                  *
  41. MidiFileSetPos           * locate to the beginning of a track             *
  42.  
  43. MidiFileReadEv           * read an event within the current track         *
  44. MidiFileReadTrack        * read a track                                   *
  45.  
  46. MidiFileWriteEv          * write an event to the current track            *
  47. MidiFileWriteTrack       * write a sequence to a track                    *
  48.  
  49. MidiFileGetMFErrno       * returns the MidiFile_errno code                *
  50. MidiFileGetErrno         * returns the errno code                         *
  51.  
  52. Warning: these functions doesn't check for the consistency of the datas, 
  53. according to the MIDIFile specifications, they write the datas without 
  54. worring about the format (tempo map for the format 1, for example)
  55.  
  56.  
  57.  
  58. æKY isTrackOpen
  59. æC macro
  60.  
  61. File {CIncludes}MidiFile.h
  62.  
  63. #ifdef __cplusplus
  64. inline Boolean isTrackOpen( midiFILE *fd) { return (fd->trkHeadOffset > 0) }
  65. #else
  66. #define isTrackOpen(fd)    (fd->trkHeadOffset > 0)
  67. #endif
  68.  
  69.                            Description
  70. Returns the current track state: closed or opened.
  71.  
  72. æKY MidiFileChooseTrack
  73. æT Function
  74. æDT Boolean ret= MidiFileChooseTrack( (midiFILE *)fd, (short)numPiste);
  75. æC File {CIncludes}MidiFile.h
  76. Synopsis
  77.  
  78. #include <MidiFile.h>
  79. Boolean MidiFileChooseTrack( midiFILE *fd, short numTrack);
  80.  
  81.                            Description
  82.  
  83. Locate at the beginning of the track numTrack within the file pointed to by fd.
  84. An error occur if the function returns false:
  85.   it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  86.   otherwise, the error code is in errno.
  87.  
  88. æKY MidiFileClose
  89. æT Function
  90. æDT Boolean ret= MidiFileClose( (midiFILE *)fd);
  91. æC File {CIncludes}MidiFile.h
  92. Synopsis
  93.  
  94. #include <MidiFile.h>
  95. Boolean MidiFileClose( midiFILE *fd);
  96.  
  97.                            Description
  98.  
  99. Close the file pointed to by fd, previously opened with MidiFileOpen
  100. or MidiFileCreate. If a track is still opened, the function closes it
  101. by calling MidiFileCloseTrack.
  102.  
  103. see also : MidiFileOpen MidiFileCreate
  104.  
  105. æKY MidiFileCloseTrack
  106. æT Function
  107. æDT Boolean ret= MidiFileCloseTrack( (midiFILE *)fd);
  108. æC File {CIncludes}MidiFile.h
  109. Synopsis
  110.  
  111. #include <MidiFile.h>
  112. Boolean   MidiFileCloseTrack( midiFILE *fd);
  113.  
  114.                            Description
  115.  
  116. Close a track previously opened with MidiFileOpenTrack or created with
  117. MidiFileNewTrack.
  118. If the file is opened for reading, MidiFileCloseTrack locate the file
  119. pointeur at the beginning of the next track.
  120. If the file is opened for writing, MidiFileCloseTrack flush the KeyOff
  121. sequence (coming from typeNote events), update the track header and the
  122. file header.
  123. The function does nothing and returns true if the track is still closed.
  124.  
  125. An error occur if the function returns false:
  126.   it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  127.   otherwise, the error code is in errno.
  128.  
  129. see also : MidiFileOpenTrack MidiFileNewTrack
  130.  
  131. æKY MidiFileCreate
  132. æT Function
  133. æDT midiFILE *myFile= MidiFileCreate( (const char *)filename, (short)format, (short)timeDef, (short)ticks);
  134. æC File {CIncludes}MidiFile.h
  135. Synopsis
  136.  
  137. #include <MidiFile.h>
  138. midiFILE *MidiFileCreate( const char *filename, short format, short timeDef, short ticks);
  139.  
  140.                            Description
  141.  
  142. Create a MIDIFile format file. The function parameters are as follow:
  143.      filename :  name of the file to create.
  144.      format   :  MIDIFile format of the file, it can takes the
  145.                   following values:
  146.                  - midifile0 : format 0 (one track)
  147.                  - midifile1 : format 1 (several tracks, to read according
  148.                                to the tempo map contained in the track #0)
  149.                  - midifile2 : format 2 (several independant patterns
  150.                                one per track, every track contains its
  151.                                own tempo map)
  152.      timeDef  : specify the time representation, it can takes the
  153.                   following values:
  154.                 - TicksPerQuarterNote : MIDI measured time.
  155.                 - Smpte24             : smpte time 24 frame/sec.
  156.                 - Smpte25             : smpte time 25 frame/sec.
  157.                 - Smpte29             : smpte time 29 frame/sec.
  158.                 - Smpte30             : smpte time 30 frame/sec.
  159.      ticks    : for MIDI time: represents the tick count per quarter note.
  160.                 for smpte time: represents the tick count per frame.
  161.  
  162. The function returns a pointer to the following structure:
  163.     typedef struct midiFILE{
  164.         short     format;                    /* file format                          */
  165.         unsigned short ntrks;            /* track count                          */
  166.         short    time;                    /* time representation :                */
  167.                         /* for MIDI time: tick count per quarter note           */
  168.                         /* for smpte time: b. 15  = 1                           */
  169.                         /*                 b.8-14 = frame count per sec         */
  170.                         /*                   b.0-7  = tick count per frame        */
  171.         FILE     *fd;                    /* standard file descriptor             */    
  172.         fpos_t  trkHeadOffset;            /* track header offset                  */
  173.                                         /* nil if the track is closed           */
  174.         long    _cnt;
  175.         MidiSeqPtr keyOff;                /* keyOff coming from typeNote events   */
  176.         long     curDate;                /* current date                         */
  177.         Boolean mode;                    /* 0/1 : reading/writing                */
  178.     }midiFILE;
  179.  
  180.  
  181. An error occur if the function returns null:
  182.   it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  183.   otherwise, the error code is in errno.
  184.  
  185. see also : MidiFileOpen MidiFileClose
  186.  
  187. æKY MidiFileGetVersion
  188. æT Function
  189. æDT const MDF_versions *myPtr= MidiFileGetVersion();
  190. æC File {CIncludes}MidiFile.h
  191. Synopsis
  192.  
  193. #include <MidiFile.h>
  194. const MDF_versions *MidiFileGetVersion(void);
  195.  
  196.                            Description
  197.  
  198. Return the version number of the implemented MIDIFile format and of 
  199. the source code.
  200.  
  201. MidiFileGetVersion returns a pointer on the following structure:
  202.     typedef struct MDF_versions{
  203.         short    src;                /* source code version              */
  204.         short     MidiFile;            /* MIDIFile format version          */
  205.     }MDF_versions;
  206.  
  207. æKY MidiFileNewTrack
  208. æT Function
  209. æDT Boolean ret= MidiFileNewTrack( (midiFILE *)fd);
  210. æC File {CIncludes}MidiFile.h
  211. Synopsis
  212.  
  213. #include <MidiFile.h>
  214. Boolean  MidiFileNewTrack( midiFILE *fd);
  215.  
  216.                            Description
  217.  
  218. MidiFileNewTrack adds a new track header at the end of the file and open the 
  219. corresponding track. You can use this function only if the file is opened for
  220. writing. A previously opened track will first been closed.
  221.  
  222. An error occur if the function returns false:
  223.   it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  224.   otherwise, the error code is in errno.
  225.  
  226. see also : MidiFileOpenTrack MidiFileCloseTrack
  227.  
  228. æKY MidiFileOpen
  229. æT Function
  230. æDT midiFILE *myFile= MidiFileOpen( (const char *)filename, (short)mode);
  231. æC File {CIncludes}MidiFile.h
  232. Synopsis
  233.  
  234. #include <MidiFile.h>
  235. midiFILE *MidiFileOpen( const char *filename, short mode);
  236.  
  237.                            Description
  238.  
  239. Open an existing MIDI file. The function parameters are as follow:
  240.      filename :  name of the file.
  241.      mode     :  can takes the following values :
  242.                  - MidiFileRead   : to read the file
  243.                  - MidiFileAppend : to append to the file
  244.  
  245. The function returns a pointer to the following structure:
  246.     typedef struct midiFILE{
  247.         short     format;                    /* file format                          */
  248.         unsigned short ntrks;            /* track count                          */
  249.         short    time;                    /* représentation du temps :            */
  250.                         /* for MIDI time: tick count per quarter note           */
  251.                         /* for smpte time: b. 15  = 1                           */
  252.                         /*                 b.8-14 = frame count per sec         */
  253.                         /*                   b.0-7  = tick count per frame        */
  254.         FILE     *fd;                    /* standard file descriptor             */    
  255.         fpos_t  trkHeadOffset;            /* track header offset                  */
  256.                                         /* nil if the track is closed           */
  257.         long    _cnt;
  258.         MidiSeqPtr keyOff;                /* keyOff coming from typeNote events   */
  259.         long     curDate;                /* current date                         */
  260.         Boolean mode;                    /* 0/1 : reading/writing                */
  261.     }midiFILE;
  262.  
  263. An error occur if the function returns nil:
  264.   it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  265.   otherwise, the error code is in errno.
  266.  
  267. see also : MidiFileClose MidiFileCreate
  268.  
  269. æKY MidiFileOpenTrack
  270. æT Function
  271. æDT Boolean ret= MidiFileOpenTrack( (midiFILE *)fd);
  272. æC File {CIncludes}MidiFile.h
  273. Synopsis
  274.  
  275. #include <MidiFile.h>
  276. Boolean  MidiFileOpenTrack( midiFILE *fd);
  277.  
  278.                            Description
  279.  
  280. Open the track if the file is opened for reading, otherwise the function returns
  281. false and MidiFile_errno is set to MidiFileErrNoTrack. 
  282. The function does nothing and returns true if the track is still opened.
  283. The purpose of this function consists essentially in data initialization
  284. to facilitate the track handling.
  285.  
  286.  
  287. see also : MidiFileNewTrack MidiFileCloseTrack
  288.  
  289. æKY MidiFileReadEv
  290. æT Function
  291. æDT MidiEvPtr ev= MidiFileReadEv( (midiFILE *)fd);
  292. æC File {CIncludes}MidiFile.h
  293. Synopsis
  294.  
  295. #include <MidiFile.h>
  296. MidiEvPtr  MidiFileReadEv( midiFILE *fd);
  297.  
  298.                            Description
  299.  
  300. MidiFileReadEv returns the next event within the current track. The track
  301. must be opened using MidiFileOpenTrack before reading an event. When you
  302. reach the end of the current track, it is automaticaly closed and the function 
  303. returns nil.
  304.  
  305. An error occur if the function returns nil when the track is still opened:
  306.   it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  307.   otherwise, the error code is in errno.
  308.  
  309. see also : MidiFileReadTrack isTrackOpen
  310.  
  311. æKY MidiFileReadTrack
  312. æT Function
  313. æDT MidiSeqPtr mySeq= MidiFileReadTrack( (midiFILE *)fd);
  314. æC File {CIncludes}MidiFile.h
  315. Synopsis
  316.  
  317. #include <MidiFile.h>
  318. MidiSeqPtr MidiFileReadTrack( midiFILE *fd);
  319.  
  320.                            Description
  321.  
  322. The function reads the current track from the file and returns the result in
  323. a MidiShare sequence. MidiFileReadTrack automaticaly opens and closes the track
  324. to read.
  325.  
  326. An error occur if the function returns nil when the track is still opened:
  327.   it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  328.   otherwise, the error code is in errno.
  329.  
  330. Warning: in case of error, the track remains opened.
  331.  
  332. æKY MidiFileWriteEv
  333. æT Function
  334. æDT Boolean ret= MidiFileWriteEv( (midiFILE *)fd, (MidiEvPtr)ev);
  335. æC File {CIncludes}MidiFile.h
  336. Synopsis
  337.  
  338. #include <MidiFile.h>
  339. Boolean    MidiFileWriteEv( midiFILE *fd, MidiEvPtr ev);
  340.  
  341.                            Description
  342.  
  343. MidiFileWriteEv writes the event ev to the current track. The track must be
  344. previously opened using the MidiFileNewTrack function.
  345.  
  346. An error occur if the function returns false:
  347.   it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  348.   otherwise, the error code is in errno.
  349.  
  350. see also : MidiFileWriteTrack
  351.  
  352. æKY MidiFileWriteTrack
  353. æT Function
  354. æDT Boolean ret= MidiFileWriteTrack( (midiFILE *)fd, (MidiSeqPtr)seq);
  355. æC File {CIncludes}MidiFile.h
  356. Synopsis
  357.  
  358. #include <MidiFile.h>
  359. Boolean MidiFileWriteTrack( midiFILE *fd, MidiSeqPtr seq);
  360.  
  361.                            Description
  362.  
  363. Writes in order all the events of the sequence seq to the file pointed to 
  364. by fd. MidiFileWriteTrack automaticaly create and close the written track. 
  365.  
  366. An error occur if the function returns false:
  367.   it is a MidiShare error if MidiFile_errno is not equal to MidiFileNoErr,
  368.   otherwise, the error code is in errno.
  369.  
  370.  
  371. æKY MidiFileGetMFErrno
  372. æT Function
  373. æDT int ret= MidiFileGetMFErrno();
  374. æC File {CIncludes}MidiFile.h
  375. Synopsis
  376.  
  377. #include <MidiFile.h>
  378. int MidiFileGetMFErrno( void);
  379.  
  380.                            Description
  381. returns the MidiFile_errno code
  382.  
  383.  
  384. æKY MidiFileGetErrno
  385. æT Function
  386. æDT int ret= MidiFileGetMFErrno();
  387. æC File {CIncludes}MidiFile.h
  388. Synopsis
  389.  
  390. #include <MidiFile.h>
  391. int MidiFileGetErrno( void);
  392.  
  393.                            Description
  394. returns the errno code