Public Member Functions | List of all members
BMidiEndpoint Class Reference

Base class for all MIDI endpoints. More...

Inherited by BMidiConsumer, and BMidiProducer.

Public Member Functions

status_t Acquire ()
 Increments the endpoint's reference count. More...
 
status_t GetProperties (BMessage *properties) const
 Reads the properties of the endpoint. More...
 
int32 ID () const
 Returns the ID of the endpoint. More...
 
bool IsConsumer () const
 Determines whether this endpoint is a BMidiConsumer. More...
 
bool IsLocal () const
 Determines whether this endpoint represents a local object. More...
 
bool IsPersistent () const
 Not used. More...
 
bool IsProducer () const
 Determines whether this endpoint is a BMidiProducer. More...
 
bool IsRemote () const
 Determines whether this endpoint is a proxy for a remote object. More...
 
bool IsValid () const
 Determines whether the endpoint still exists. More...
 
const char * Name () const
 Returns the name of the endpoint. More...
 
status_t Register ()
 Publishes the endpoint on the roster. More...
 
status_t Release ()
 Decrements the endpoint's reference count. More...
 
void SetName (const char *name)
 Changes the name of the endpoint. More...
 
status_t SetProperties (const BMessage *properties)
 Changes the properties of the endpoint. More...
 
status_t Unregister ()
 Hides the endpoint from the roster/. More...
 

Detailed Description

Base class for all MIDI endpoints.

BMidiEndpoint is the abstract base class that represents either a producer or consumer endpoint. It may be used to obtain the state, name, properties, or system-wide ID of the object. BMidiEndpoint also provides the ability to change the name and properties of endpoints that were created locally.

Remember, you cannot call the destructor of BMidiEndpoint and its subclasses directly. Endpoint objects are destructed automatically when their reference count drops to zero. If necessary, the destructor of a local endpoint first breaks off any connections and Unregister()'s the endpoint before it is deleted. However, for good style and bonus points you should really Disconnect() and Unregister() the object yourself and not rely on the destructor to do this.

Member Function Documentation

◆ Acquire()

status_t BMidiEndpoint::Acquire ( )

Increments the endpoint's reference count.

Each BMidiEndpoint has a reference count associated with it, so that BMidiRoster can do proper bookkeeping. Acquire() increments this reference count, and Release() decrements it. Once the count reaches zero, the endpoint is deleted.

When you are done with the endpoint, whether local or remote, you should always Release() it!

Upon construction, local endpoints start with a reference count of 1. Any objects you obtain from BMidiRoster using the NextXXX() or FindXXX() functions have their reference counts incremented in the process. If you forget to call Release(), the objects won't be properly cleaned up and you'll make a fool out of yourself.

After you Release() an object, you are advised not to use it any further. If you do, your app will probably crash. That also happens if you Release() an object too many times.

Typically, you don't need to call Acquire(), unless you have two disparate parts of your application working with the same endpoint, and you don't want to have to keep track of who needs to Release() the endpoint. Now you simply have both of them release it.

Returns
Always returns B_OK
See also
Release()

◆ GetProperties()

status_t BMidiEndpoint::GetProperties ( BMessage props) const

Reads the properties of the endpoint.

Usage example:

BMessage props;
if (endpoint->GetProperties(&props) == B_OK)
{
...examine the contents of the message...
}

Note that GetProperties() overwrites the contents of your BMessage.

See also
SetProperties()

◆ ID()

int32 BMidiEndpoint::ID ( ) const

Returns the ID of the endpoint.

An ID uniquely identifies an endpoint in the system. The ID is a signed 32-bit number that is assigned by the Midi Server when the endpoint is created. (So even if a local endpoint is not published, it still has a unique ID.) Valid IDs range from 1 to 0x7FFFFFFF, the largest value an int32 can have. 0 and negative values are not valid IDs.

◆ IsConsumer()

bool BMidiEndpoint::IsConsumer ( ) const

Determines whether this endpoint is a BMidiConsumer.

If it is, you can use a dynamic_cast to convert this object into a consumer:

if (endp->IsConsumer())
{
BMidiConsumer* cons = dynamic_cast<BMidiConsumer*>(endp);
....
}

◆ IsLocal()

bool BMidiEndpoint::IsLocal ( ) const

Determines whether this endpoint represents a local object.

An endpoint is "local" when it is created by this application; in other words, a BMidiLocalConsumer or BMidiLocalProducer.

◆ IsPersistent()

bool BMidiEndpoint::IsPersistent ( ) const

Not used.

The purpose of this function is unclear, and as a result it doesn't do anything in the Haiku Midi Kit implementation.

Returns
false always.

◆ IsProducer()

bool BMidiEndpoint::IsProducer ( ) const

Determines whether this endpoint is a BMidiProducer.

If it is, you can use a dynamic_cast to convert this object into a producer:

if (endp->IsProducer())
{
BMidiProducer* prod = dynamic_cast<BMidiProducer*>(endp);
....
}

◆ IsRemote()

bool BMidiEndpoint::IsRemote ( ) const

Determines whether this endpoint is a proxy for a remote object.

An endpoint is "remote" when it is created by another application. Obviously, the remote object is Register()'ed as well, otherwise you would not be able to see it.

◆ IsValid()

bool BMidiEndpoint::IsValid ( ) const

Determines whether the endpoint still exists.

Suppose you obtained a proxy object for a remote endpoint by querying the BMidiRoster. What if the application that published this endpoint quits, or less drastically, Unregister()'s that endpoint? Even though you still have a BMidiEndpoint proxy object, the real endpoint no longer exists. You can use IsValid() to check for this.

Don't worry, operations on invalid objects, such as GetProperties(), will return an error code (typically B_ERROR), but not cause a crash. Local objects are always are considered to be valid, even if you did not Register() them. (The only time a local endpoint is not valid is when there was a problem constructing it.)

If the application that created the remote endpoint crashes, then there is no guarantee that the Midi Server immediately recognizes this. In that case, IsValid() may still return true. Eventually, the stale endpoint will be removed from the roster, though. From then on, IsValid() correctly returns false.

◆ Name()

const char * BMidiEndpoint::Name ( ) const

Returns the name of the endpoint.

The function never returns NULL. If you created a local endpoint by passing a NULL name into its constructor (or passing no name, which is the same thing), then Name() will return an empty string, not NULL.

See also
SetName()

◆ Register()

status_t BMidiEndpoint::Register ( )

Publishes the endpoint on the roster.

MIDI objects created by an application are invisible to other applications until they are published. To publish an object use the Register() method. The corresponding Unregister() method will cause an object to once again become invisible to remote applications.

BMidiRoster also has Register() and Unregister() methods. You may also use those methods to publish or hide your endpoints; both do the same thing.

Although it is considered bad style, calling Register() on local endpoints that are already registered won't mess things up. The Midi Server will simply ignore your request. Likewise for Unregister()'ing more than once. Attempts to Register() or Unregister() remote endpoints will fail, of course.

If you are watching , you will not receive notifications for any local endpoints you register or unregister. Of course, other applications will be notified about your endpoints.

Existing connections will not be broken when an object is unregistered, but future remote connections will be denied. When objects are destroyed, they automatically become unregistered.

Returns
B_OK on success, or an error code (typically B_ERROR) if something went wrong.
See also
Unregister()

◆ Release()

status_t BMidiEndpoint::Release ( )

Decrements the endpoint's reference count.

Returns
Always returns B_OK
See also
Acquire()

◆ SetName()

void BMidiEndpoint::SetName ( const char *  name)

Changes the name of the endpoint.

Names don't have to be unique, but it is recommended that you give any endpoints you publish meaningful and unique names, so users can easily recognize what each endpoint does. There is no limit to the size of endpoint names.

Even though you can call this function on both remote and local objects, you are only allowed to change the names of local endpoints; SetName() calls on remote endpoints are ignored.

Parameters
nameThe new name. If you pass NULL the name won't be changed.
See also
Name()

◆ SetProperties()

status_t BMidiEndpoint::SetProperties ( const BMessage props)

Changes the properties of the endpoint.

Endpoints can have properties, which is any kind of information that might be useful to associate with a MIDI object. The properties are stored in a BMessage.

Usage example:

BMessage props;
if (endpoint->GetProperties(&props) == B_OK)
{
...add data to the message...
endpoint->SetProperties(&props);
}

You are only allowed to call SetProperties() on a local object.

Properties should follow a protocol, so different applications will know how to read each other's properties. The current protocol is very limited – it only allows you to associate icons with your endpoints. Be planned to publish a more complete protocol that included additional information, such as vendor/model names, copyright/version info, category, etc., but they never got around to it.

propertyVector icon (raw data)
field name"icon"
field type'VICN'

This vector icon is available under Haiku only, and comes as raw data, not a BBitmap. Before being able to display it, you first must render the vector icon in the size of your choice.

propertyLarge (32x32) icon
field name"be:large_icon"
field type'ICON'
propertySmall (16x16) icon
field name"be:mini_icon"
field type'MICN'

The MidiUtil package (downloadable from the OpenBeOS website) contains a number of convenient functions to associate icons with endpoints, so you don't have to write that code all over again.

See also
GetProperties()

◆ Unregister()

status_t BMidiEndpoint::Unregister ( )

Hides the endpoint from the roster/.

See also
Register()