The Midi Kit: BMidiPort

The Midi Kit Table of Contents | The Midi Kit Index

# BMidiPort

Derived from: public BMidi

Declared in: be/midi/MidiPort.h

Library: libmidi.so

###### Summary

A BMidiPort object reads and writes MIDI data through a MIDI hardware port. A MIDI hardware port has an input side (MIDI-In) and an output side (MIDI-Out); you can use a single BMidiPort object to communicate with both sides. Also, you can create and use any number of BMidiPort objects in your application—multiple BMidiPort objects can open and use the same hardware port at the same time.

You identify a MIDI port by name, passing it to the BMidiPort constructor or `Open()` function. Use the `GetDeviceName()` function to retrieve the names of the MIDI ports. The ports are closed through `Close()`; they're automatically closed when the BMidiPort object is destroyed.

On a Macintosh, there are two midi ports:

- "midi1" is the modem port.

- "midi2" is the printer port.

On Intel hardware....

A BMidiPort object can only open one port at a time.

### Running and the MIDI Hook Functions

- Running a BMidiPort corresponds to MIDI-In: When you tell a BMidiPort to run (through the `Start()` function) the object begins reading from MIDI-In and spraying the MIDI messages to its connected objects.

- On the other side, the MIDI hook functions (`NoteOn()`, `NoteOff()`, etc.) send MIDI messages to MIDI-Out.

It's possible to use the same BMidiPort object to accept data from MIDI-In and broadcast different data to MIDI-Out. You can even connect a BMidiPort object to itself to create a "MIDI through" effect: Anything that shows up at the MIDI-In port will automatically be sent out the MIDI-Out port.

## Constructor and Destructor

### BMidiPort()

`BMidiPort(`const char *name = NULL`) `

Creates a new BMidiPort object and opens it on the named port. If no name is given, the object remains unopened until `Open()` is called.

### ~BMidiPort()

virtual`~BMidiPort() `

Closes the connections to the MIDI ports.

## Member Functions

### AllNotesOff()

bool `AllNotesOff(`bool controlOnly, uint32 time = B_NOW`) `

Commands the BMidiPort object to issue an All Notes Off MIDI message to the MIDI-Out port. If controlOnly is `true`, only the All Notes Off message is sent. If it's `false`, a Note Off message is also sent for every key number on every channel.

### Close()

void `Close(`void`) `

Closes the object's MIDI port. The port should have been previously opened through a call to `Open()`.

### CountDevices() , GetDeviceName()

int32 `CountDevices(`void`) `
status_t `GetDeviceName(`int32 n, char *name, size_t bufSize = B_OS_NAME_LENGTH`) `

These two function work together to let you retrieve the names of all MIDI ports. `CountDevices()` returns the number of MIDI ports that are supported by the machine. `GetDeviceName()` returns, in name, the name of the n'th MIDI port. bufSize is the length of the name buffer, in bytes. It needn't be longer than `B_OS_NAME_LENGTH` (defined in OS.h).

RETURN CODES

`GetDeviceName()` returns...

- `B_OK`. Success.

- `B_BAD_VALUE`. n is out of range.

- `B_NAME_TOO_LONG`. The device name length is greater than bufSize.

### InitCheck()

status_t`InitCheck()` const

Returns the status of the previous port-opening call. This function is provided primarily so you can get the status after opening the port through the constructor.

RETURN CODES

`B_OK`. The port was successfully opened.

- POSIX errors. The open was thwarted.

### Open()

status_t`Open(`const char *name`) `

Opens the MIDI port identified by name, so the object can read and write MIDI data. Use the `GetDeviceName()` function to get the names of the MIDI ports. The object isn't given exclusive access to the ports that it has opened—other BMidiPort objects, potentially from other applications, can open the same MIDI ports. When you're finished with the ports, you should close them through a (single) call to `Close().`

The MIDI-Out connection is active from the moment the object is opened: Messages that arrive through the MIDI hook functions are automatically sent to the MIDI-Out port. To begin reading from the MIDI-In port, you have to invoke the object's `Start()` function.

The function returns `B_OK` if the port was successfully opened.

### Start() , Stop()

virtual status_t `Start(`void`) `
virtual void `Stop(`void`) `

`Start()` tells the object to begin listening to MIDI-In. For each MIDI message that it hears, the object calls the appropriate spray function.

`Stop()` tells the object to stop listening to MIDI-In.

Neither of these functions affects the MIDI-Out side of the port.

## MIDI Hook Functions

The BMidiPort class implements the MIDI hook functions to send MIDI data to the MIDI-Out side of the port. For the syntax of the MIDI hook functions, see the BMidi class.

The Midi Kit Table of Contents | The Midi Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..