mdOpenInPort(3dm)mdOpenInPort(3dm)NAME
mdOpenInPort, mdOpenOutPort, mdClosePort, mdGetFd - open and close
MDports
SYNOPSIS
#include <dmedia/midi.h>
MDport mdOpenInPort(char *name)
MDport mdOpenOutPort(char *name)
int mdClosePort(MDport port)
int mdGetFd(MDport port)
DESCRIPTION
mdOpenInPort and mdOpenOutPort create an MDport for a specified
interface. An MDport maintains the state of the communications path
between the application and a MIDI interface. An MDport is passed as the
first argument to most MIDI library routines.
The name parameter contains the name of the MIDI interface to which the
newly opened port is connected. The mdGetName(3dm) function returns
strings which can be used as valid values of name. If NULL is passed in
for name, the default MIDI interface will be opened.
When a port is first opened, its default stamp mode is MD_DELTASTAMP and
the origin of the port is set to the time at which it was opened (see
mdSetStartPoint(3dm)). If the application changes the stamp mode to one
of the tick modes (either MD_RELATIVETICK or MD_DELTATICK), the port will
use a default tempo of 500000 and a default division of 384. However, an
application should explicitly set any port parameters it depends on
rather than depending on the default values.
mdClosePort closes the connection to the MIDI interface and frees all
resources associated with the connection. When a port is closed, all
events that have been queued but not yet transmitted are discarded. As a
result, the application may need to insure that all desired events have
been transmitted before closing the port. One way the application can do
this is for it to wait until mdTellNow(3dm) returns the stamp of the last
transmitted event.
The application must call mdInit(3dm) before calling either mdOpenInPort
or mdOpenOutPort. Failing to do so will produce indeterminant results.
mdGetFd returns a file descriptor that an application can use to
construct the arguments for a select(2) or poll(2) call. These calls are
used when the application wants to give up control of the CPU (letting
other processes use the CPU) until a port becomes ready for input or
output. MIDI input ports are considered to be ready when one or more
events are available for reception. Output ports are ready when they are
capable of accepting additional events. Once a port becomes ready,
select and poll return, and the application can continue processing.
Page 1
mdOpenInPort(3dm)mdOpenInPort(3dm)
When using select, an input port's file descriptor is used in a read
fdset and an output port's file descriptor is used in a write fdset.
When using poll, an input port's file descriptor is used with the POLLIN
event flag and an output port's file descriptor is used with a POLLOUT
event flag.
mdGetFd should only be used in select or poll; the results of passing it
as an argument to any other system calls are undefined.
RETURN VALUE
mdOpenInPort and mdOpenOutPort return an MDport on success or NULL in
event of failure. mdClosePort returns 0 on success and -1 on failure.
On an error, errno will be set to one of the following:
ENOMEM - No memory was available for the MDport data structure
ENODEV - The MIDI driver wasn't present
EINVAL - An undefined operation was called.
mdGetFd returns a file descriptor. On an error it returns -1.
SEE ALSOmdIntro(3dm), mdSetStampMode(3dm), mdGetName(3dm), mdTellNow(3dm),
mdSetStartPoint
Page 2
