| | Open Sound System |
| Do you have problems with sound/audio application development? Don't panic! Click here for help! |
midi_expresswrite_buf_t buf;
ioctl(fd, SNDCTL_MIDI_EXPRESS_WRITE, &buf);
The above code fragment lacks all error checks for clarity. Real world applications must always check for the errors and handle them as described below. Also most OSS ioctl calls will return information in the argument variable and it's usually necessary to check it too.
This ioctl call makes it possible to place a block of one or more MIDI messages to the front of the device output queue. In this way it's possible to implement features like local echo in application level.
The point where this data is inserted is not necessarily the very top of the queue. If the device is already sending some message block then the express block will be placed immediately after the active block. However it's quaranteed that the data gets inserted before all buffers which are waiting for the right transmission time. The express data will be placed after all the previously sent express blocks which quarantees that the express blocks (out of band data) are sent in the right order.
Due to the above there will be some latency before the express data actually gets sent. This may become noticeable if there are lot's of events waiting to be sent at the same moment of time. However in normal operation the delays should not be longer than few milliseconds.
Most MIDI messages consist of several bytes that need to be sent together. The espress send feature inserts extra bytes to the stream. So special care must be taken in applications that use this feature.
First of all make sure no MIDI message is broken by a write call. All bytes of the message must be written together. In this way OSS will never insert anything (except possible MIDI real-time messages) between the bytes. However to avoid noticeable latencies you should avoid sending too many bytes together Sending one MIDI byte takes about 0.3 millliseconds). OTOH don't try to obtain shorter latencies than actually necessary since large number of very short writes increases the system load unnecessarily.
Another MIDI feature that may cause problems with merging of express messages is running status. Don't use running status across buffers written separately. In that way an express message may get inserted to a point where it breaks integrity of running status. So every time you start assembling a new write buffer you should reset the variables related with running status handling.
Equally well don't use running status across express buffer boundaries. It's possible that two subsequent express buffers don't get placed together in the queue which breaks running status.
SNDCTL_MIDI_EXPRESS_WRITE is a new call introduced in OSS 4.0. No earlier OSS versions support it. There is no alternative way to do the same so applications using SNDCTL_MIDI_EXPRESS_WRITE cannot be made to work with older OSS versions.
The return value from the OSS ioctl calls will be -1 if a fatal error occurred. Other values mean that the ioctl call was more or less successful. However in most cases the application must check the value returned in the argument to see what was the accepted value.
Please see the Possible error codes (errno) returned by OSS calls section for more info about the error codes returned by OSS.