Input/Output Devices Handling

Functions
const PmDeviceInfo *	Pm_GetDeviceInfo (PmDeviceID id)
	Pm_GetDeviceInfo() returns a pointer to a PmDeviceInfo structure referring to the device specified by id.
PmError	Pm_OpenInput (PortMidiStream **stream, PmDeviceID inputDevice, void *inputDriverInfo, long bufferSize, PmTimeProcPtr time_proc, void *time_info)
	Pm_OpenInput() and Pm_OpenOutput() open devices.
PmError	Pm_OpenOutput (PortMidiStream **stream, PmDeviceID outputDevice, void *outputDriverInfo, long bufferSize, PmTimeProcPtr time_proc, void *time_info, long latency)

---

Function Documentation

const PmDeviceInfo* Pm_GetDeviceInfo

(

PmDeviceID

id

)

Pm_GetDeviceInfo() returns a pointer to a PmDeviceInfo structure referring to the device specified by id.

If id is out of range the function returns NULL.

The returned structure is owned by the PortMidi implementation and must not be manipulated or freed. The pointer is guaranteed to be valid between calls to Pm_Initialize() and Pm_Terminate().

Definition at line 178 of file portmidi.c.

PmError Pm_OpenInput	(	PortMidiStream **	stream,
		PmDeviceID	inputDevice,
		void *	inputDriverInfo,
		long	bufferSize,
		PmTimeProcPtr	time_proc,
		void *	time_info
	)

Pm_OpenInput() and Pm_OpenOutput() open devices.

stream is the address of a PortMidiStream pointer which will receive a pointer to the newly opened stream.

inputDevice is the id of the device used for input (see PmDeviceID above).

inputDriverInfo is a pointer to an optional driver specific data structure containing additional information for device setup or handle processing. inputDriverInfo is never required for correct operation. If not used inputDriverInfo should be NULL.

outputDevice is the id of the device used for output (see PmDeviceID above.)

outputDriverInfo is a pointer to an optional driver specific data structure containing additional information for device setup or handle processing. outputDriverInfo is never required for correct operation. If not used outputDriverInfo should be NULL.

For input, the buffersize specifies the number of input events to be buffered waiting to be read using Pm_Read(). For output, buffersize specifies the number of output events to be buffered waiting for output. (In some cases -- see below -- PortMidi does not buffer output at all and merely passes data to a lower-level API, in which case buffersize is ignored.)

latency is the delay in milliseconds applied to timestamps to determine when the output should actually occur. (If latency is < 0, 0 is assumed.) If latency is zero, timestamps are ignored and all output is delivered immediately. If latency is greater than zero, output is delayed until the message timestamp plus the latency. (NOTE: the time is measured relative to the time source indicated by time_proc. Timestamps are absolute, not relative delays or offsets.) In some cases, PortMidi can obtain better timing than your application by passing timestamps along to the device driver or hardware. Latency may also help you to synchronize midi data to audio data by matching midi latency to the audio buffer latency.

time_proc is a pointer to a procedure that returns time in milliseconds. It may be NULL, in which case a default millisecond timebase (PortTime) is used. If the application wants to use PortTime, it should start the timer (call Pt_Start) before calling Pm_OpenInput or Pm_OpenOutput. If the application tries to start the timer *after* Pm_OpenInput or Pm_OpenOutput, it may get a ptAlreadyStarted error from Pt_Start, and the application's preferred time resolution and callback function will be ignored. time_proc result values are appended to incoming MIDI data, and time_proc times are used to schedule outgoing MIDI data (when latency is non-zero).

time_info is a pointer passed to time_proc.

Example: If I provide a timestamp of 5000, latency is 1, and time_proc returns 4990, then the desired output time will be when time_proc returns timestamp+latency = 5001. This will be 5001-4990 = 11ms from now.

return value: Upon success Pm_Open() returns PmNoError and places a pointer to a valid PortMidiStream in the stream argument. If a call to Pm_Open() fails a nonzero error code is returned (see PMError above) and the value of port is invalid.

Any stream that is successfully opened should eventually be closed by calling Pm_Close().

Definition at line 664 of file portmidi.c.

References PM_FILT_ACTIVE.