<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>PortMidi: Reading and Writing Midi Messages</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
</head>
<body>
<div id="top"><!-- do not remove this div! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">PortMidi
 <span id="projectnumber">2.2.x</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.0 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
initNavTree('group__grp__io.html','');
</script>
<div id="doc-content">
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Reading and Writing Midi Messages</div> </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga3d59225bc890ede974f245ada3de6456"><td class="memItemLeft" align="right" valign="top">PMEXPORT int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__grp__io.html#ga3d59225bc890ede974f245ada3de6456">Pm_Read</a> (PortMidiStream *stream, <a class="el" href="structPmEvent.html">PmEvent</a> *buffer, int32_t length)</td></tr>
<tr class="memdesc:ga3d59225bc890ede974f245ada3de6456"><td class="mdescLeft"> </td><td class="mdescRight"><a class="el" href="group__grp__io.html#ga3d59225bc890ede974f245ada3de6456" title="Pm_Read() retrieves midi data into a buffer, and returns the number of events read.">Pm_Read()</a> retrieves midi data into a buffer, and returns the number of events read. <a href="#ga3d59225bc890ede974f245ada3de6456"></a><br/></td></tr>
<tr class="memitem:ga54198ca9dc1af9d82ec5f44f661faeea"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga54198ca9dc1af9d82ec5f44f661faeea"></a>
PMEXPORT PmError </td><td class="memItemRight" valign="bottom"><a class="el" href="group__grp__io.html#ga54198ca9dc1af9d82ec5f44f661faeea">Pm_Poll</a> (PortMidiStream *stream)</td></tr>
<tr class="memdesc:ga54198ca9dc1af9d82ec5f44f661faeea"><td class="mdescLeft"> </td><td class="mdescRight"><a class="el" href="group__grp__io.html#ga54198ca9dc1af9d82ec5f44f661faeea" title="Pm_Poll() tests whether input is available, returning TRUE, FALSE, or an error value.">Pm_Poll()</a> tests whether input is available, returning TRUE, FALSE, or an error value. <br/></td></tr>
<tr class="memitem:ga82950117f003d28f9ca6536c00af985a"><td class="memItemLeft" align="right" valign="top">PMEXPORT PmError </td><td class="memItemRight" valign="bottom"><a class="el" href="group__grp__io.html#ga82950117f003d28f9ca6536c00af985a">Pm_Write</a> (PortMidiStream *stream, <a class="el" href="structPmEvent.html">PmEvent</a> *buffer, int32_t length)</td></tr>
<tr class="memdesc:ga82950117f003d28f9ca6536c00af985a"><td class="mdescLeft"> </td><td class="mdescRight"><a class="el" href="group__grp__io.html#ga82950117f003d28f9ca6536c00af985a" title="Pm_Write() writes midi data from a buffer.">Pm_Write()</a> writes midi data from a buffer. <a href="#ga82950117f003d28f9ca6536c00af985a"></a><br/></td></tr>
<tr class="memitem:ga4a8cdd77e5b2ad4c16338eed475dfc6b"><td class="memItemLeft" align="right" valign="top">PMEXPORT PmError </td><td class="memItemRight" valign="bottom"><a class="el" href="group__grp__io.html#ga4a8cdd77e5b2ad4c16338eed475dfc6b">Pm_WriteShort</a> (PortMidiStream *stream, PmTimestamp when, int32_t msg)</td></tr>
<tr class="memdesc:ga4a8cdd77e5b2ad4c16338eed475dfc6b"><td class="mdescLeft"> </td><td class="mdescRight"><a class="el" href="group__grp__io.html#ga4a8cdd77e5b2ad4c16338eed475dfc6b" title="Pm_WriteShort() writes a timestamped non-system-exclusive midi message.">Pm_WriteShort()</a> writes a timestamped non-system-exclusive midi message. <a href="#ga4a8cdd77e5b2ad4c16338eed475dfc6b"></a><br/></td></tr>
<tr class="memitem:ga4bd5753bdfb53a1611bcdf5ba159fc87"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga4bd5753bdfb53a1611bcdf5ba159fc87"></a>
PMEXPORT PmError </td><td class="memItemRight" valign="bottom"><a class="el" href="group__grp__io.html#ga4bd5753bdfb53a1611bcdf5ba159fc87">Pm_WriteSysEx</a> (PortMidiStream *stream, PmTimestamp when, unsigned char *msg)</td></tr>
<tr class="memdesc:ga4bd5753bdfb53a1611bcdf5ba159fc87"><td class="mdescLeft"> </td><td class="mdescRight"><a class="el" href="group__grp__io.html#ga4bd5753bdfb53a1611bcdf5ba159fc87" title="Pm_WriteSysEx() writes a timestamped system-exclusive midi message.">Pm_WriteSysEx()</a> writes a timestamped system-exclusive midi message. <br/></td></tr>
</table>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga3d59225bc890ede974f245ada3de6456"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">PMEXPORT int <a class="el" href="group__grp__io.html#ga3d59225bc890ede974f245ada3de6456">Pm_Read</a> </td>
<td>(</td>
<td class="paramtype">PortMidiStream * </td>
<td class="paramname"><em>stream</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structPmEvent.html">PmEvent</a> * </td>
<td class="paramname"><em>buffer</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"><em>length</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="group__grp__io.html#ga3d59225bc890ede974f245ada3de6456" title="Pm_Read() retrieves midi data into a buffer, and returns the number of events read.">Pm_Read()</a> retrieves midi data into a buffer, and returns the number of events read. </p>
<p>Result is a non-negative number unless an error occurs, in which case a PmError value will be returned.</p>
<p>Buffer Overflow</p>
<p>The problem: if an input overflow occurs, data will be lost, ultimately because there is no flow control all the way back to the data source. When data is lost, the receiver should be notified and some sort of graceful recovery should take place, e.g. you shouldn't resume receiving in the middle of a long sysex message.</p>
<p>With a lock-free fifo, which is pretty much what we're stuck with to enable portability to the Mac, it's tricky for the producer and consumer to synchronously reset the buffer and resume normal operation.</p>
<p>Solution: the buffer managed by PortMidi will be flushed when an overflow occurs. The consumer (<a class="el" href="group__grp__io.html#ga3d59225bc890ede974f245ada3de6456" title="Pm_Read() retrieves midi data into a buffer, and returns the number of events read.">Pm_Read()</a>) gets an error message (pmBufferOverflow) and ordinary processing resumes as soon as a new message arrives. The remainder of a partial sysex message is not considered to be a "new
message" and will be flushed as well. </p>
<p>Definition at line <a class="el" href="portmidi_8c_source.html#l00357">357</a> of file <a class="el" href="portmidi_8c_source.html">portmidi.c</a>.</p>
</div>
</div>
<a class="anchor" id="ga82950117f003d28f9ca6536c00af985a"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">PMEXPORT PmError <a class="el" href="group__grp__io.html#ga82950117f003d28f9ca6536c00af985a">Pm_Write</a> </td>
<td>(</td>
<td class="paramtype">PortMidiStream * </td>
<td class="paramname"><em>stream</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structPmEvent.html">PmEvent</a> * </td>
<td class="paramname"><em>buffer</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"><em>length</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="group__grp__io.html#ga82950117f003d28f9ca6536c00af985a" title="Pm_Write() writes midi data from a buffer.">Pm_Write()</a> writes midi data from a buffer. </p>
<p>This may contain:</p>
<ul>
<li>short messages or</li>
<li>sysex messages that are converted into a sequence of <a class="el" href="structPmEvent.html" title="All midi data comes in the form of PmEvent structures.">PmEvent</a> structures, e.g. sending data from a file or forwarding them from midi input.</li>
</ul>
<p>Use <a class="el" href="group__grp__io.html#ga4bd5753bdfb53a1611bcdf5ba159fc87" title="Pm_WriteSysEx() writes a timestamped system-exclusive midi message.">Pm_WriteSysEx()</a> to write a sysex message stored as a contiguous array of bytes.</p>
<p>Sysex data may contain embedded real-time messages. </p>
<p>Definition at line <a class="el" href="portmidi_8c_source.html#l00448">448</a> of file <a class="el" href="portmidi_8c_source.html">portmidi.c</a>.</p>
<p>Referenced by <a class="el" href="portmidi_8c_source.html#l00581">Pm_WriteShort()</a>, and <a class="el" href="portmidi_8c_source.html#l00591">Pm_WriteSysEx()</a>.</p>
</div>
</div>
<a class="anchor" id="ga4a8cdd77e5b2ad4c16338eed475dfc6b"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">PMEXPORT PmError <a class="el" href="group__grp__io.html#ga4a8cdd77e5b2ad4c16338eed475dfc6b">Pm_WriteShort</a> </td>
<td>(</td>
<td class="paramtype">PortMidiStream * </td>
<td class="paramname"><em>stream</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">PmTimestamp </td>
<td class="paramname"><em>when</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int32_t </td>
<td class="paramname"><em>msg</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="group__grp__io.html#ga4a8cdd77e5b2ad4c16338eed475dfc6b" title="Pm_WriteShort() writes a timestamped non-system-exclusive midi message.">Pm_WriteShort()</a> writes a timestamped non-system-exclusive midi message. </p>
<p>Messages are delivered in order as received, and timestamps must be non-decreasing. (But timestamps are ignored if the stream was opened with latency = 0.) </p>
<p>Definition at line <a class="el" href="portmidi_8c_source.html#l00581">581</a> of file <a class="el" href="portmidi_8c_source.html">portmidi.c</a>.</p>
<p>References <a class="el" href="portmidi_8c_source.html#l00448">Pm_Write()</a>.</p>
</div>
</div>
</div><!-- contents -->
</div>
<div id="nav-path" class="navpath">
<ul>
<hr size="1"><address style="text-align: right;"><small>
Generated for PortMidi by <a href="http://www.doxygen.org/
index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a>
1.8.0</small></address>
</body>
</html>
