<!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: PmEvent Struct Reference</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 class="current"><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="navrow2" class="tabs2">
<ul class="tablist">
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="classes.html"><span>Data Structure Index</span></a></li>
<li><a href="functions.html"><span>Data Fields</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('structPmEvent.html','');
</script>
<div id="doc-content">
<div class="header">
<div class="summary">
<a href="#pub-attribs">Data Fields</a> </div>
<div class="headertitle">
<div class="title">PmEvent Struct Reference<div class="ingroups"><a class="el" href="group__grp__events__filters.html">Events and Filters Handling</a></div></div> </div>
</div><!--header-->
<div class="contents">
<p>All midi data comes in the form of <a class="el" href="structPmEvent.html" title="All midi data comes in the form of PmEvent structures.">PmEvent</a> structures.
<a href="structPmEvent.html#details">More...</a></p>
<p><code>#include <<a class="el" href="portmidi_8h_source.html">portmidi.h</a>></code></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="pub-attribs"></a>
Data Fields</h2></td></tr>
<tr class="memitem:a2c8c12542447fdd566401fbf1a83d4e2"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a2c8c12542447fdd566401fbf1a83d4e2"></a>
<a class="el" href="group__grp__events__filters.html#gad8455e4afe978a74c68e345bef99761d">PmMessage</a> </td><td class="memItemRight" valign="bottom"><b>message</b></td></tr>
<tr class="memitem:a3854d39e3b89e1e2a4e1fda8d85c2f16"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a3854d39e3b89e1e2a4e1fda8d85c2f16"></a>
PmTimestamp </td><td class="memItemRight" valign="bottom"><b>timestamp</b></td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>All midi data comes in the form of <a class="el" href="structPmEvent.html" title="All midi data comes in the form of PmEvent structures.">PmEvent</a> structures. </p>
<p>A sysex message is encoded as a sequence of <a class="el" href="structPmEvent.html" title="All midi data comes in the form of PmEvent structures.">PmEvent</a> structures, with each structure carrying 4 bytes of the message, i.e. only the first <a class="el" href="structPmEvent.html" title="All midi data comes in the form of PmEvent structures.">PmEvent</a> carries the status byte.</p>
<p>Note that MIDI allows nested messages: the so-called "real-time" MIDI messages can be inserted into the MIDI byte stream at any location, including within a sysex message. MIDI real-time messages are one-byte messages used mainly for timing (see the MIDI spec). PortMidi retains the order of non-real-time MIDI messages on both input and output, but it does not specify exactly how real-time messages are processed. This is particulary problematic for MIDI input, because the input parser must either prepare to buffer an unlimited number of sysex message bytes or to buffer an unlimited number of real-time messages that arrive embedded in a long sysex message. To simplify things, the input parser is allowed to pass real-time MIDI messages embedded within a sysex message, and it is up to the client to detect, process, and remove these messages as they arrive.</p>
<p>When receiving sysex messages, the sysex message is terminated by either an EOX status byte (anywhere in the 4 byte messages) or by a non-real-time status byte in the low order byte of the message. If you get a non-real-time status byte but there was no EOX byte, it means the sysex message was somehow truncated. This is not considered an error; e.g., a missing EOX can result from the user disconnecting a MIDI cable during sysex transmission.</p>
<p>A real-time message can occur within a sysex message. A real-time message will always occupy a full <a class="el" href="structPmEvent.html" title="All midi data comes in the form of PmEvent structures.">PmEvent</a> with the status byte in the low-order byte of the <a class="el" href="structPmEvent.html" title="All midi data comes in the form of PmEvent structures.">PmEvent</a> message field. (This implies that the byte-order of sysex bytes and real-time message bytes may not be preserved -- for example, if a real-time message arrives after 3 bytes of a sysex message, the real-time message will be delivered first. The first word of the sysex message will be delivered only after the 4th byte arrives, filling the 4-byte <a class="el" href="structPmEvent.html" title="All midi data comes in the form of PmEvent structures.">PmEvent</a> message field.</p>
<p>The timestamp field is observed when the output port is opened with a non-zero latency. A timestamp of zero means "use the current time", which in turn means to deliver the message with a delay of latency (the latency parameter used when opening the output port.) Do not expect PortMidi to sort data according to timestamps -- messages should be sent in the correct order, and timestamps MUST be non-decreasing. See also "Example" for Pm_OpenOutput() above.</p>
<p>A sysex message will generally fill many <a class="el" href="structPmEvent.html" title="All midi data comes in the form of PmEvent structures.">PmEvent</a> structures. On output to a PortMidiStream with non-zero latency, the first timestamp on sysex message data will determine the time to begin sending the message. PortMidi implementations may ignore timestamps for the remainder of the sysex message.</p>
<p>On input, the timestamp ideally denotes the arrival time of the status byte of the message. The first timestamp on sysex message data will be valid. Subsequent timestamps may denote when message bytes were actually received, or they may be simply copies of the first timestamp.</p>
<p>Timestamps for nested messages: If a real-time message arrives in the middle of some other message, it is enqueued immediately with the timestamp corresponding to its arrival time. The interrupted non-real-time message or 4-byte packet of sysex data will be enqueued later. The timestamp of interrupted data will be equal to that of the interrupting real-time message to insure that timestamps are non-decreasing. </p>
<p>Definition at line <a class="el" href="portmidi_8h_source.html#l00577">577</a> of file <a class="el" href="portmidi_8h_source.html">portmidi.h</a>.</p>
</div><hr/>The documentation for this struct was generated from the following file:<ul>
<li><a class="el" href="portmidi_8h_source.html">portmidi.h</a></li>
</ul>
</div><!-- contents -->
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="structPmEvent.html">PmEvent</a> </li>
<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>
