home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 200-299 / ff227.lzh / MidiLib / docs / midi.doc < prev    next >
Text File  |  1989-06-25  |  27KB  |  944 lines
  1. midi.library - October 27, 1988
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. midi.library/CreateMDest
  6. midi.library/CreateMListSignal
  7. midi.library/CreateMRoute
  8. midi.library/CreateMSource
  9. midi.library/DeleteMDest
  10. midi.library/DeleteMListSignal
  11. midi.library/DeleteMRoute
  12. midi.library/DeleteMSource
  13. midi.library/FindMDest
  14. midi.library/FindMSource
  15. midi.library/FlushMDest
  16. midi.library/FreeMidiMsg
  17. midi.library/FreeMidiPacket
  18. midi.library/GetMidiMsg
  19. midi.library/GetMidiPacket
  20. midi.library/LockMidiBase
  21. midi.library/LockMRoutes
  22. midi.library/MidiMsgLength
  23. midi.library/MidiMsgType
  24. midi.library/ModifyMRoute
  25. midi.library/MRouteDest
  26. midi.library/MRoutePublic
  27. midi.library/MRouteSource
  28. midi.library/PutMidiMsg
  29. midi.library/PutMidiStream
  30. midi.library/SetDefaultMRouteInfo
  31. midi.library/UnlockMidiBase
  32. midi.library/UnlockMRoutes
  33. midi.library/CreateMDest                        midi.library/CreateMDest
  34.  
  35. NAME
  36.     CreateMDest -- Create a MIDI destination node
  37.  
  38. SYNOPSIS
  39.     dest = CreateMDest (name,image)
  40.     d0            a0   a1
  41.     struct MDest *dest;
  42.     char *name;
  43.     struct Image *image;
  44.  
  45. FUNCTION
  46.     Creates a new MIDI destination node.  A MsgPort is created and
  47.     linked into the new MDest that will signal you when this MDest gets
  48.     a message (see msg routines for more info).  If a name is given,
  49.     this node will be placed in the library's public destination list
  50.     (so it can be located with FindMDest()).  If name is NULL a private
  51.     node is created. The image supplied can be used by graphics-based
  52.     patch bay applications and will only be used for public nodes. image
  53.     may be NULL if no image is to be supplied.    You are responsible for
  54.     deleting any nodes you create when you are done with them.
  55.  
  56.     The default MRouteInfo structure attached to the new MDest is
  57.     iniitialized to pass all normal messages (MMF_ALL) and all channels
  58.     w/o any processing.  You can modify the default MRouteInfo by
  59.     calling SetDefaultMRouteInfo().
  60.  
  61. INPUTS
  62.     name - pointer to a null-terminated string or NULL
  63.     image - pointer to an Intuition Image structure or NULL
  64.  
  65. RESULTS
  66.     dest - pointer to the new MDest node or NULL on failure.
  67.  
  68. SEE ALSO
  69.     DeleteMDest, FindMDest, SetDefaultMRouteInfo
  70. midi.library/CreateMListSignal            midi.library/CreateMListSignal
  71.  
  72. NAME
  73.     CreateMListSignal -- Create a signal to inform caller of public list
  74.              changes
  75.  
  76. SYNOPSIS
  77.     signal = CreateMListSignal (flags)
  78.     d0                d0
  79.     struct MListSignal *signal;
  80.     ULONG flags;
  81.  
  82. FUNCTION
  83.     Creates a new MListSignal structure to inform the caller of changes
  84.     made to the public node list (by itself or other programs).
  85.  
  86.     The flags specify which list(s) to watch:
  87.  
  88.         MLSF_SOURCE   to watch SourceList
  89.         MLSF_DEST      to watch DestList
  90.  
  91.     They may be combined to watch both lists.
  92.  
  93.     A new signal bit will be allocated (if available) and the caller's
  94.     task will be used.    Interrogate signal->Sigbit to find out the
  95.     signal bit in use.
  96.  
  97.         Wait (1L << signal->SigBit);
  98.  
  99.     Your task is not informed of what changed, just merely that
  100.     something changed.    It's your tasks responsibility, if it's
  101.     interested, to scan the public node lists to find out what changed.
  102.  
  103.     The intent of this is to provide a mechanism to synchronize public
  104.     node changes with patch bay systems that need to be kept informed of
  105.     the currently available public nodes.  By using this system, a patch
  106.     bay system need only scan the lists when it gets signalled rather
  107.     than having to poll it periodically.
  108.  
  109.     Be sure to call DeleteMListSignal() when you are done using the
  110.     signal provided by this function.
  111.  
  112. INPUTS
  113.     flags - flags indicating which list(s) to watch
  114.  
  115. RESULTS
  116.     signal - pointer to the new MListSignal or NULL on failure.
  117.  
  118. SEE ALSO
  119.     DeleteMListSignal
  120. midi.library/CreateMRoute                      midi.library/CreateMRoute
  121.  
  122. NAME
  123.     CreateMRoute -- Create an MRoute
  124.  
  125. SYNOPSIS
  126.     route = CreateMRoute (source,dest,routeinfo)
  127.     d0              a0     a1   a2
  128.     struct MRoute *route;
  129.     struct MSource *source;
  130.     struct MDest *dest;
  131.     struct MRouteInfo *routeinfo;
  132.  
  133. FUNCTION
  134.     Creates and links a new MRoute into an MSource node and an MDest
  135.     node. This routine assumes that both source and dest are private
  136.     nodes that you created or that you have called LockMidiBase() to
  137.     prevent public nodes from moving around.  To route to public nodes
  138.     use one of the other MRoute creation routines.  The MRouteInfo
  139.     structure defines the new connection. You need not preserve the
  140.     MRouteInfo structure after calling this routine since it is copied
  141.     into the newly created MRoute structure.  You are responsible for
  142.     deleting any MRoute's you create.
  143.  
  144.     routeinfo may be NULL which indicates that dest->DefaultRouteInfo
  145.     should be used instead.
  146.  
  147. INPUT
  148.     source - pointer to an MSource node
  149.     dest - pointer to an MDest node
  150.     routeinfo - pointer to an MRouteInfo structure defining this MRoute
  151.         (or NULL to use dest->DefaultRouteInfo)
  152.  
  153. RESULTS
  154.     route - a pointer to a new MRoute structure or NULL on failure.
  155.  
  156. SEE ALSO
  157.     MRouteSource, MRouteDest, MRoutePublic, ModifyMRoute, DeleteMRoute
  158. midi.library/CreateMSource                    midi.library/CreateMSource
  159.  
  160. NAME
  161.     CreateMSource -- Create a MIDI source node
  162.  
  163. SYNOPSIS
  164.     source = CreateMSource (name,image)
  165.     d0                a0     a1
  166.     struct MSource *source;
  167.     char *name;
  168.     struct Image *image;
  169.  
  170. FUNCTION
  171.     Creates a new MIDI source node.  If a name is given, this node will
  172.     be placed in the library's public source list (so it can be located
  173.     with FindMSource()).  If name is NULL a private node is created. The
  174.     image supplied can be used by graphics-based patch bay applications
  175.     and will only be used for public nodes.  image may be NULL if no
  176.     image is to be supplied.  You are responsible for deleting any nodes
  177.     you create when you are done with them.
  178.  
  179. INPUTS
  180.     name - pointer to a null-terminated string or NULL
  181.     image - pointer to an Intuition Image structure or NULL
  182.  
  183. RESULTS
  184.     source - pointer to the new MSource node or NULL on failure.
  185.  
  186. SEE ALSO
  187.     DeleteMSource, FindMSource
  188. midi.library/DeleteMDest                        midi.library/DeleteMDest
  189.  
  190. NAME
  191.     DeleteMDest -- Delete a MIDI destination node
  192.  
  193. SYNOPSIS
  194.     DeleteMDest (dest)
  195.          a0
  196.     struct MDest *dest;
  197.  
  198. FUNCTION
  199.     Removes and frees an MDest created by CreateMDest().  Any MRoute's
  200.     connected to this MDest will be unlinked.  Any messages waiting at
  201.     this MDest will be freed.  You should only delete nodes that you
  202.     created.
  203.  
  204. INPUTS
  205.     dest - pointer to the MDest node to delete
  206.  
  207.  
  208. RESULTS
  209.     none
  210.  
  211. SEE ALSO
  212.     CreateMDest, FindMDest
  213. midi.library/DeleteMListSignal            midi.library/DeleteMListSignal
  214.  
  215. NAME
  216.     DeleteMListSignal -- Delete a signal created by CreateMListSignal
  217.  
  218. SYNOPSIS
  219.     DeleteMListSignal (signal)
  220.                a0
  221.     struct MListSignal *signal;
  222.  
  223. FUNCTION
  224.     Removes and frees an MListSignal created by CreateMListSignal().
  225.     You must call this to free any MListSignals that you have allocated
  226.     when you are done with them.
  227.  
  228. INPUTS
  229.     signal - pointer to MListSignal to delete
  230.  
  231. RESULTS
  232.     none
  233.  
  234. SEE ALSO
  235.     CreateMListSignal
  236. midi.library/DeleteMRoute                      midi.library/DeleteMRoute
  237.  
  238. NAME
  239.     DeleteMRoute -- Delete an MRoute
  240.  
  241. SYNOPSIS
  242.     DeleteMRoute (route)
  243.           a0
  244.     struct MRoute *route;
  245.  
  246. FUNCTION
  247.     Unlinks and frees a route previously created with one of the routing
  248.     functions.    You should only delete routes that you created.  You
  249.     will still need to do this even if both the source and dest have
  250.     been deleted in order to free up the memory allocated to the route.
  251.  
  252. INPUTS
  253.     route - pointer to the MRoute to delete
  254.  
  255. RESULTS
  256.     none
  257.  
  258. SEE ALSO
  259.     CreateMRoute, MRouteSource, MRouteDest, MRoutePublic, ModifyMRoute
  260. midi.library/DeleteMSource                    midi.library/DeleteMSource
  261.  
  262. NAME
  263.     DeleteMSource -- Delete a MIDI source node
  264.  
  265. SYNOPSIS
  266.     DeleteMSource (source)
  267.            a0
  268.     struct MSource *source;
  269.  
  270. FUNCTION
  271.     Removes and frees an MSource created by CreateMSource().  Any
  272.     MRoute's connected to this MSource will be unlinked.  You should
  273.     only delete nodes that you created.
  274.  
  275. INPUTS
  276.     source - pointer to the MSource node to delete
  277.  
  278. RESULTS
  279.     none
  280.  
  281. SEE ALSO
  282.     CreateMSource, FindMSource
  283. midi.library/FindMDest                            midi.library/FindMDest
  284.  
  285. NAME
  286.     FindMDest -- Find a public MIDI destination node
  287.  
  288. SYNOPSIS
  289.     dest = FindMDest (name)
  290.     d0              a0
  291.     struct MDest *dest;
  292.     char *name;
  293.  
  294. FUNCTION
  295.     Finds a public MIDI destination node by name if it exists.    In
  296.     order to ensure that this node remains valid you should call
  297.     LockMidiBase() prior to calling this routine.
  298.  
  299. INPUTS
  300.     name - pointer to the null-terminated name to find
  301.  
  302. RESULTS
  303.     dest - pointer to the requested MDest node or NULL if not found.
  304.  
  305. SEE ALSO
  306.     CreateMDest, DeleteMDest, LockMidiBase, UnlockMidiBase
  307. midi.library/FindMSource                        midi.library/FindMSource
  308.  
  309. NAME
  310.     FindMSource -- Find a public MIDI source node
  311.  
  312. SYNOPSIS
  313.     source = FindMSource (name)
  314.     d0              a0
  315.     struct MSource *source;
  316.     char *name;
  317.  
  318. FUNCTION
  319.     Finds a public MIDI source node by name if it exists.  In order to
  320.     ensure that this node remains valid you should call LockMidiBase()
  321.     prior to calling this routine.
  322.  
  323. INPUTS
  324.     name - pointer to the null-terminated name to find
  325.  
  326. RESULTS
  327.     source - pointer to the requested MSource node or NULL if not found.
  328.  
  329. SEE ALSO
  330.     CreateMSource, DeleteMSource, LockMidiBase, UnlockMidiBase
  331. midi.library/FlushMDest                          midi.library/FlushMDest
  332.  
  333. NAME
  334.     FlushMDest -- Flush MIDI messages
  335.  
  336. SYNOPSIS
  337.     FlushMDest (dest)
  338.         a0
  339.     struct MDest *dest;
  340.  
  341. FUNCTION
  342.     Disploses of all MidiPackets (or messages) pending at a MIDI
  343.     destination node. Additionally causes the expunging any currently
  344.     unused PacketArrays which may free some memory depending on prior
  345.     message traffic.  This gets called automatically by DeleteMDest().
  346.  
  347. INPUTS
  348.     dest - pointer to MDest to flush
  349.  
  350. RESULTS
  351.     none
  352.  
  353. SEE ALSO
  354.     GetMidiMsg, FreeMidiMsg
  355. midi.library/FreeMidiMsg                        midi.library/FreeMidiMsg
  356.  
  357. NAME
  358.     FreeMidiMsg -- Free a MIDI message returned by GetMidiMsg
  359.  
  360. SYNOPSIS
  361.     FreeMidiMsg (msg)
  362.          a0
  363.     UBYTE *msg;
  364.  
  365. FUNCTION
  366.     Frees a message returned by GetMidiMsg().
  367.  
  368. INPUTS
  369.     msg - pointer to a UBYTE array containing one MIDI message
  370.  
  371. RESULTS
  372.     none
  373.  
  374. SEE ALSO
  375.     GetMidiMsg
  376. midi.library/FreeMidiPacket                  midi.library/FreeMidiPacket
  377.  
  378. NAME
  379.     FreeMidiPacket -- Free a MIDI packet message returned by
  380.               GetMidiPacket
  381.  
  382. SYNOPSIS
  383.     FreeMidiPacket (packet)
  384.             a0
  385.     struct MidiPacket *packet;
  386.  
  387. FUNCTION
  388.     Frees a MidiPacket returned by GetMidiPacket().
  389.  
  390. INPUTS
  391.     packet - pointer to a MidiPacket structure
  392.  
  393. RESULTS
  394.     none
  395.  
  396. SEE ALSO
  397.     GetMidiPacket, FreeMidiMsg
  398. midi.library/GetMidiMsg                          midi.library/GetMidiMsg
  399.  
  400. NAME
  401.     GetMidiMsg -- Get the next MIDI message from an MDest
  402.  
  403. SYNOPSIS
  404.     msg = GetMidiMsg (dest)
  405.     d0              a0
  406.     UBYTE *msg;
  407.     struct MDest *dest;
  408.  
  409. FUNCTION
  410.     Returns the next message received at a MIDI destination or NULL if
  411.     no more messages are present.
  412.  
  413.     This function does little more than call GetMidiPacket() and offset
  414.     the return value to the address of the contained MidiMsg.  It exists
  415.     mainly for backwards compatibility and for some simple cases.
  416.     Chances are that you'll want to know more about messages that you
  417.     receive; you can save yourself the trouble of calling MidiMsgType()
  418.     and MidiMsgLength() by receiving MidiPackets with GetMidiPacket()
  419.     instead.
  420.  
  421.     Once you have dealt with the messages you have received you should
  422.     dispose of them by calling FreeMidiMsg().  midi.library is not
  423.     halted until you free these messages so you can hang on to them as
  424.     long as you like.  Just free them when you are done with them.
  425.  
  426.     Be aware that the more messages you keep without freeing the more
  427.     fragmented the Amiga's memory will become.  If you plan to keep a
  428.     large number of messages you are probably better off allocating a
  429.     buffer and copying the messages to it.
  430.  
  431.     The recommended approach to dealing with messages is:
  432.  
  433.     Wait (1L << dest->DestPort->mp_SigBit);
  434.  
  435.         /* loop to pick up all messages for this signal */
  436.     while (msg = GetMidiMsg(dest)) {
  437.  
  438.         /* do something with message.  for example: */
  439.         length = MidiMsgLength(msg);
  440.         type = MidiMsgType(msg);
  441.  
  442.         /* then free the message when done */
  443.         FreeMidiMsg (msg);
  444.     }
  445.  
  446. INPUTS
  447.     dest - pointer to the MDest node to receive from
  448.  
  449. RESULTS
  450.     msg - pointer to a UBYTE array containing one MIDI message or NULL
  451.       if there are no more messages at this MDest
  452.  
  453. SEE ALSO
  454.     GetMidiPacket, FreeMidiMsg, MidiMsgType, MidiMsgLength, PutMidiMsg
  455. midi.library/GetMidiPacket                    midi.library/GetMidiPacket
  456.  
  457. NAME
  458.     GetMidiPacket -- Get the next MIDI packet from an MDest
  459.  
  460. SYNOPSIS
  461.     packet = GetMidiPacket (dest)
  462.     d0                a0
  463.     struct MidiPacket *packet;
  464.     struct MDest *dest;
  465.  
  466. FUNCTION
  467.     Returns the next packet received at a MIDI destination or NULL if
  468.     no more packets are present.
  469.  
  470.     This is the new preferred method of receiving MIDI messages since
  471.     the packet contains information about the message (type and length)
  472.     that already had to be determined prior to sending it to you.  See
  473.     midi.h and midi.i for descriptions of the MidiPacket structure.
  474.  
  475.     As previously permitted with messages returned by GetMidiMsg(), you
  476.     are permitted to cache as many MidiPackets as you like.  Just
  477.     remember to free them when you are done (call FreeMidiPacket()).
  478.     MidiPackets for short messages are managed in groups known as
  479.     PacketArrays rather than singly.  Because of this, caching them may
  480.     have a performance impact on message routing.
  481.  
  482.     NOTE: You must consider the entire contents of the MidiPacket to be
  483.     READ ONLY!    The only exception is that packet->MidiMsg may be
  484.     changed as long as it doesn't affect the type or length of the
  485.     message.
  486.  
  487.     The recommended approach to dealing with MidiPackets is:
  488.  
  489.     Wait (1L << dest->DestPort->mp_SigBit);
  490.  
  491.         /* loop to pick up all messages for this signal */
  492.     while (packet = GetMidiPacket(dest)) {
  493.  
  494.         /*
  495.         Do something with packet like examine packet->Type and
  496.         packet->Length to read the message type or length.  The
  497.         actual message is pointed to by packet->MidiMsg.
  498.         */
  499.  
  500.         /* then free the message when done */
  501.         FreeMidiPacket (packet);
  502.     }
  503.  
  504. INPUTS
  505.     dest - pointer to the MDest node to receive from
  506.  
  507. RESULTS
  508.     packet - pointer to a MidiPacket structure or NULL if there are no
  509.          more messages at this MDest
  510.  
  511. SEE ALSO
  512.     FreeMidiPacket, FreeMidiMsg, MidiMsgType, MidiMsgLength, PutMidiRaw
  513. midi.library/LockMidiBase                      midi.library/LockMidiBase
  514.  
  515. NAME
  516.     LockMidiBase -- lock the lists in the library base
  517.  
  518. SYNOPSIS
  519.     LockMidiBase()
  520.  
  521. FUNCTION
  522.     Gains exclusive access to the Source and Dest lists in the library
  523.     base.  This will block any other tasks attempts to Create, Delete,
  524.     or Find MSource and MDest nodes.  Use this if you wish to examine a
  525.     public node.  The route linkages within the nodes are not protected
  526.     by this.  Use LockMRoutes() to block message routining and route
  527.     management.
  528.  
  529.     Calls to LockMidiBase() may be nested, but each call must be matched
  530.     with a call to UnlockMidiBase().
  531.  
  532. INPUTS
  533.     none
  534.  
  535. RESULTS
  536.     none
  537.  
  538. SEE ALSO
  539.     UnlockMidiBase, LockMRoutes
  540. midi.library/LockMRoutes                        midi.library/LockMRoutes
  541.  
  542. NAME
  543.     LockMRoutes -- locks routes (blocks msg routing and route
  544.            management)
  545.  
  546. SYNOPSIS
  547.     LockMRoutes()
  548.  
  549. FUNCTION
  550.     Blocks all message routing and route management activity so that the
  551.     routes may be inspected.  Calls to LockMRoutes() may be nested, but
  552.     each call must be matched with a call to UnlockMRoutes().
  553.  
  554.     Calling this routine implies that you also want to lock the public
  555.     node list, thus effectively disabling all operation performed by the
  556.     MIDI Library.
  557.  
  558.     If you just wish to examine the public node list without blocking
  559.     messages, use LockMidiBase().
  560.  
  561. INPUTS
  562.     none
  563.  
  564. RESULTS
  565.     none
  566.  
  567. SEE ALSO
  568.     UnlockMRoutes, LockMidiBase
  569. midi.library/MidiMsgLength                    midi.library/MidiMsgLength
  570.  
  571. NAME
  572.     MidiMsgLength -- Determine the length of a MIDI message
  573.  
  574. SYNOPSIS
  575.     length = MidiMsgLength(msg)
  576.     d0               a0
  577.     ULONG length;
  578.     UBYTE *msg;
  579.  
  580. FUNCTION
  581.     Returns the length in bytes of a MIDI message.  The message length
  582.     includes the status byte.  For system exclusive messages the EOX
  583.     status byte at the end is also included.
  584.  
  585. INPUTS
  586.     msg - pointer to a UBYTE array containing one MIDI message
  587.  
  588. RESULTS
  589.     length - length of the message in bytes.  For valid messages this
  590.          will be at least 1.  0 is returned for invalid messages.
  591.          The maximum length permitted here is 65535 bytes although
  592.          the return value is packed into a long (ie the upper word
  593.          is always 0)
  594.  
  595. SEE ALSO
  596.     MidiMsgType
  597. midi.library/MidiMsgType                        midi.library/MidiMsgType
  598.  
  599. NAME
  600.     MidiMsgType -- Determine the type of a MIDI message
  601.  
  602. SYNOPSIS
  603.     type = MidiMsgType(msg)
  604.     d0               a0
  605.     UWORD type;
  606.     UBYTE *msg;
  607.  
  608. FUNCTION
  609.     Returns the type a MIDI message.  The flags are defined in
  610.     midi/midi.h (or midi/midi.i) and are the same ones used in
  611.     MRouteInfo.MsgFlags.  Other than the obvious, some special message
  612.     handling takes place:
  613.  
  614.     Controller changes for ctrl # 121 - 127 return MMF_MODE.
  615.  
  616.     Note On messages with velocity == 0 return MMF_NOTEOFF.
  617.  
  618.     EOX and all invalid messages return 0 (an EOX by itself is not
  619.     considered a valid message)
  620.  
  621. INPUTS
  622.     msg - pointer to a UBYTE array containing one MIDI message
  623.  
  624. RESULTS
  625.     type - message type
  626.  
  627. SEE ALSO
  628.     MidiMsgLength
  629. midi.library/ModifyMRoute                      midi.library/ModifyMRoute
  630.  
  631. NAME
  632.     ModifyMRoute -- Modify an existing an MRoute
  633.  
  634. SYNOPSIS
  635.     ModifyMRoute (route,newrouteinfo)
  636.           a0    a1
  637.     struct MRoute *route;
  638.     struct MRouteInfo *newrouteinfo;
  639.  
  640. FUNCTION
  641.     Modifies the MRouteInfo structure in an existing route.  Any
  642.     messages already delivered to this MRoute's MDest, whether received
  643.     or not, are not affected.  As with CreateMRoute, the supplied
  644.     MRouteInfo structure need not be kept after calling this routine:
  645.     it is merely a template that is copied to the MRoute.
  646.  
  647. INPUT
  648.     route - pointer to an MRoute to modify
  649.     routeinfo - pointer to the new MRouteInfo for this MRoute
  650.  
  651. RESULTS
  652.     none
  653.  
  654. SEE ALSO
  655.     CreateMRoute, MRouteSource, MRouteDest, MRoutePublic, DeleteMRoute
  656. midi.library/MRouteDest                          midi.library/MRouteDest
  657.  
  658. NAME
  659.     MRouteDest -- Create an MRoute from a public MSource to a private
  660.           MDest
  661.  
  662. SYNOPSIS
  663.     route = MRouteDest (sourcename,dest,routeinfo)
  664.     d0            a0       a1    a2
  665.     struct MRoute *route;
  666.     char *sourcename;
  667.     struct MDest *dest;
  668.     struct MRouteInfo *routeinfo;
  669.  
  670. FUNCTION
  671.     Routes an MDest to a public MSource.  This is shorthand for:
  672.  
  673.     LockMidiBase();
  674.     if (source = FindMSource(sourcename))
  675.         route = CreateMRoute(source,dest,routeinfo);
  676.     UnlockMidiBase();
  677.  
  678. INPUT
  679.     sourcename - pointer to null-terminated name of a public MSource
  680.     dest - pointer to an MDest node
  681.     routeinfo - pointer to an MRouteInfo structure defining this MRoute
  682.         (or NULL to use dest->DefaultRouteInfo)
  683.  
  684. RESULTS
  685.     route - a pointer to a new MRoute structure or NULL on failure.
  686.  
  687. SEE ALSO
  688.     CreateMRoute, MRouteSource, MRoutePublic, ModifyMRoute, DeleteMRoute
  689. midi.library/MRoutePublic                      midi.library/MRoutePublic
  690.  
  691. NAME
  692.     MRoutePublic -- Create an MRoute from a public MSource to a public
  693.             MDest
  694.  
  695. SYNOPSIS
  696.     route = MRoutePublic (sourcename,destname,routeinfo)
  697.     d0              a0         a1       a2
  698.     struct MRoute *route;
  699.     char *sourcename;
  700.     char *destname;
  701.     struct MRouteInfo *routeinfo;
  702.  
  703. FUNCTION
  704.     Routes a public MSource to a public MDest.    This is shorthand for:
  705.  
  706.     LockMidiBase();
  707.     if ( (source = FindMSource(sourcename) &&
  708.         (dest = FindMDest(destname)) )
  709.         route = CreateMRoute(source,dest,routeinfo);
  710.     UnlockMidiBase();
  711.  
  712. INPUT
  713.     sourcename - pointer to null-terminated name of a public MSource
  714.     destname - pointer to null-terminated name of a public MDest
  715.     routeinfo - pointer to an MRouteInfo structure defining this MRoute
  716.         (or NULL to use dest->DefaultRouteInfo)
  717.  
  718. RESULTS
  719.     route - a pointer to a new MRoute structure or NULL on failure.
  720.  
  721. SEE ALSO
  722.     CreateMRoute, MRouteSource, MRouteDest, ModifyMRoute, DeleteMRoute
  723. midi.library/MRouteSource                      midi.library/MRouteSource
  724.  
  725. NAME
  726.     MRouteSource -- Create an MRoute from a private MSource to a public
  727.             MDest
  728.  
  729. SYNOPSIS
  730.     route = MRouteSource (source,destname,routeinfo)
  731.     d0              a0     a1      a2
  732.     struct MRoute *route;
  733.     struct MSource *source;
  734.     char *destname;
  735.     struct MRouteInfo *routeinfo;
  736.  
  737. FUNCTION
  738.     Routes an MSource to a public MDest.  This is shorthand for:
  739.  
  740.     LockMidiBase();
  741.     if (dest = FindMDest(destname))
  742.         route = CreateMRoute(source,dest,routeinfo);
  743.     UnlockMidiBase();
  744.  
  745. INPUT
  746.     source - pointer to an MSource node
  747.     destname - pointer to null-terminated name of a public MDest
  748.     routeinfo - pointer to an MRouteInfo structure defining this MRoute
  749.         (or NULL to use dest->DefaultRouteInfo)
  750.  
  751. RESULTS
  752.     route - a pointer to a new MRoute structure or NULL on failure.
  753.  
  754. SEE ALSO
  755.     CreateMRoute, MRouteDest, MRoutePublic, ModifyMRoute, DeleteMRoute
  756. midi.library/PutMidiMsg                          midi.library/PutMidiMsg
  757.  
  758. NAME
  759.     PutMidiMsg -- Place a MIDI message at an MSource
  760.  
  761. SYNOPSIS
  762.     PutMidiMsg (source,msg)
  763.         a0     a1
  764.     struct MSource *source;
  765.     UBYTE *msg;
  766.  
  767. FUNCTION
  768.     Sends a MIDI message off to an MSource to be distributed to any
  769.     MDest's that are routed to this source.  Once sent the message
  770.     buffer can be recycled since copies are made of it as necessary.
  771.     This routine assumes that it is getting a valid message.  If you
  772.     wish to send data that is not necessarily valid (and don't wish to
  773.     process it yourself) or your message buffer contains more than one
  774.     message you should consider using PutMidiStream() instead.
  775.  
  776. INPUTS
  777.     source - pointer to the MSource node to place the message at
  778.     msg - pointer to a UBYTE array containing one MIDI message
  779.  
  780. RESULTS
  781.     none
  782.  
  783. SEE ALSO
  784.     PutMidiStream, MidiMsgLength, MidiMsgType, GetMidiMsg
  785. midi.library/PutMidiStream                    midi.library/PutMidiStream
  786.  
  787. NAME
  788.     PutMidiStream -- Send an unformatted stream
  789.  
  790. SYNOPSIS
  791.     PutMidiStream (source,fillbuffer,buf,bufsize,cursize)
  792.            a0      a1         a2  d0     d1
  793.     struct MSource *source;
  794.     ULONG (*fillbuffer)();
  795.     UBYTE *buf;
  796.     ULONG bufsize,cursize;
  797.  
  798. FUNCTION
  799.     Converts an unformatted stream into MIDI messages and calls
  800.     PutMidiMsg() to the specified MSource for each one.
  801.  
  802.     The user supplied fillbuffer routine is called to place data in the
  803.     user supplied buffer.  It can be written in C, assembly or whatever
  804.     as long as it abides by the rules:
  805.  
  806.     On entry the following registers will be set:
  807.  
  808.         D0 - indicates the size of user supplied buffer
  809.         A0 - points to the user supplied buffer
  810.         A4 - contains its value prior to calling PutMidiStream()
  811.          (useful for Aztec C small data model)
  812.         A6 - MidiBase
  813.  
  814.     On return D0 should be set to the number of bytes placed in the
  815.     buffer.  A value of 0 indicates the end of the stream has been
  816.     reached and that PutMidiStream() should return.
  817.  
  818.     Any registers that the PutMidiStream() needs are preserved
  819.     before calling the user's fillbuffer routine so fillbuffer need
  820.     not preserve any registers.
  821.  
  822.     In C the routine should be declared something like:
  823.  
  824.     long fillbuffer()
  825.     {
  826.         long len;
  827.           .
  828.           .         /* whatever it takes to fill up */
  829.           .         /* buffer and set len */
  830.           .
  831.         return len;     /* sets D0 accordingly */
  832.     }
  833.  
  834.     There are two basic ways of using calling PutMidiStream:
  835.  
  836.     1.    The stream length is unknown or just simply too large to put
  837.     into a single buffer (like transferring from a file to an
  838.     MSource).
  839.  
  840.     Assuming that the buffer is initially empty you would use a call
  841.     similar to:
  842.  
  843.         PutMidiStream (source, fillmybuf, mybuf,
  844.                      (long)sizeof mybuf, 0L);
  845.  
  846.     fillmybuf() will be called immediately to put some data into the
  847.     buffer (mybuf).  Processing will continue until fillmybuf()
  848.     indicates that it's time to quit by returning a 0.
  849.  
  850.     2.    The stream length is known and it is small enough to place in
  851.     the buffer.
  852.  
  853.         PutMidiStream (source,NULL,mybuf,(long)sizeof mybuf,
  854.                          (long)sizeof mybuf);
  855.  
  856.     The NULL fillbuffer routine indicates that the buffer contains
  857.     all it's ever going to.  The current size is set to the size of
  858.     the buffer to indicate that the buffer is full of data to be
  859.     processed.  Once the buffer is exhausted, PutMidiStream will
  860.     return.
  861.  
  862. INPUTS
  863.     source - pointer to the MSource to send messages to
  864.     fillbuffer - user supplied routine to fill the user supplied buffer
  865.          can be NULL if no buffer filling is to be done
  866.     buf - user supplied buffer
  867.     bufsize - size of user supplied buffer
  868.     cursize - amount of data currently in the buffer upon entry to this
  869.           function.  If non-zero this data will be processed before
  870.           trying to call (*fillbuffer)().
  871.  
  872. RESULTS
  873.     none
  874.  
  875. SEE ALSO
  876.     PutMidiMsg
  877. midi.library/SetDefaultMRouteInfo      midi.library/SetDefaultMRouteInfo
  878.  
  879. NAME
  880.     SetDefaultMRouteInfo -- Set default MRouteInfo in an MDest
  881.  
  882. SYNOPSIS
  883.     SetDefaultMRouteInfo (dest,routeinfo)
  884.               a0   a1
  885.     struct MDest *dest;
  886.     struct MRouteInfo *routeinfo;
  887.  
  888. FUNCTION
  889.     Copies the supplied routeinfo into dest->DefaultRouteInfo.    Any new
  890.     routes created w/o a RouteInfo structure will use this RouteInfo
  891.     structure instead.    The source routeinfo structure need not be
  892.     preserved after calling this since it's copied.
  893.  
  894. INPUTS
  895.     dest - MDest to modify
  896.     routeinfo - new default MRouteInfo for MDest
  897.  
  898. RESULTS
  899.     none
  900.  
  901. SEE ALSO
  902.     CreateMRoute
  903.  
  904. midi.library/UnlockMidiBase                  midi.library/UnlockMidiBase
  905.  
  906. NAME
  907.     UnlockMidiBase -- unlock the lists in the library base
  908.  
  909. SYNOPSIS
  910.     UnlockMidiBase()
  911.  
  912. FUNCTION
  913.     Releases exclusive access to the Source and Dest lists in the
  914.     library base.  Each call to this must be matched with a call to
  915.     LockMidiBase().
  916.  
  917. INPUTS
  918.     none
  919.  
  920. RESULTS
  921.     none
  922.  
  923. SEE ALSO
  924.     LockMidiBase
  925. midi.library/UnlockMRoutes                    midi.library/UnlockMRoutes
  926.  
  927. NAME
  928.     UnlockMRoutes -- unlocks routes
  929.  
  930. SYNOPSIS
  931.     UnlockMRoutes()
  932.  
  933. FUNCTION
  934.     Unblocks message routing and route management activity.
  935.  
  936. INPUTS
  937.     none
  938.  
  939. RESULTS
  940.     none
  941.  
  942. SEE ALSO
  943.     LockMRoutes
  944.