1/*! 2 \file MidiEndpoint.h 3 \ingroup midi2 4 \ingroup libbe 5 \brief Defines the Baseclass of all MIDI consumers and producers. 6*/ 7 8 9/*! 10 \class BMidiEndpoint 11 \ingroup midi2 12 \ingroup libmidi2 13 \ingroup libbe 14 \brief Base class for all MIDI endpoints. 15 16 BMidiEndpoint is the abstract base class that represents either a 17 producer or consumer endpoint. It may be used to obtain the state, name, 18 properties, or system-wide ID of the object. BMidiEndpoint also provides 19 the ability to change the name and properties of endpoints that were 20 created locally. 21 22 Remember, you cannot call the destructor of BMidiEndpoint and its 23 subclasses directly. Endpoint objects are destructed automatically when 24 their reference count drops to zero. If necessary, the destructor of a 25 local endpoint first breaks off any connections and Unregister()'s the 26 endpoint before it is deleted. However, for good style and bonus points 27 you should really \link BMidiProducer::Disconnect() Disconnect() \endlink 28 and Unregister() the object yourself and not rely on the destructor to 29 do this. 30*/ 31 32/*! 33 \fn const char* BMidiEndpoint::Name() const 34 \brief Returns the name of the endpoint. 35 36 The function never returns NULL. If you created a local endpoint by 37 passing a \c NULL name into its constructor (or passing no name, 38 which is the same thing), then Name() will return an empty string, 39 not \c NULL. 40 41 \sa SetName() 42*/ 43 44/*! 45 \fn void BMidiEndpoint::SetName(const char* name) 46 \brief Changes the name of the endpoint. 47 48 Names don't have to be unique, but it is recommended that you give any 49 endpoints you publish meaningful and unique names, so users can easily 50 recognize what each endpoint does. There is no limit to the size of 51 endpoint names. 52 53 Even though you can call this function on both remote and local objects, 54 you are only allowed to change the names of local endpoints; SetName() 55 calls on remote endpoints are ignored. 56 57 \param name The new name. If you pass \c NULL the name won't be changed. 58 59 \sa Name() 60*/ 61 62/*! 63 \fn int32 BMidiEndpoint::ID() const 64 \brief Returns the ID of the endpoint 65 66 An ID uniquely identifies an endpoint in the system. The ID is a signed 67 32-bit number that is assigned by the Midi Server when the endpoint is 68 created. (So even if a local endpoint is not published, it still has a 69 unique ID.) Valid IDs range from 1 to 0x7FFFFFFF, the largest value an 70 int32 can have. 0 and negative values are <b>not</b> valid IDs. 71*/ 72 73 74/*! 75 \fn bool BMidiEndpoint::IsProducer() const 76 \brief Determines whether this endpoint is a BMidiProducer 77 78 If it is, you can use a dynamic_cast to convert this object into a 79 producer: 80 81\code 82if (endp->IsProducer()) 83{ 84 BMidiProducer* prod = dynamic_cast<BMidiProducer*>(endp); 85 86 .... 87 88} 89\endcode 90 91*/ 92 93 94/*! 95 \fn bool BMidiEndpoint::IsConsumer() const 96 \brief Determines whether this endpoint is a BMidiConsumer 97 98 If it is, you can use a dynamic_cast to convert this object into a consumer: 99 100\code 101if (endp->IsConsumer()) 102{ 103 BMidiConsumer* cons = dynamic_cast<BMidiConsumer*>(endp); 104 105 .... 106 107} 108\endcode 109 110*/ 111 112 113/*! 114 \fn bool BMidiEndpoint::IsRemote() const 115 \brief Determines whether this endpoint is a proxy for a remote object. 116 117 An endpoint is "remote" when it is created by another application. 118 Obviously, the remote object is Register()'ed as well, otherwise you would 119 not be able to see it. 120*/ 121 122 123/*! 124 \fn bool BMidiEndpoint::IsLocal() const 125 \brief Determines whether this endpoint represents a local object 126 127 An endpoint is "local" when it is created by this application; in other 128 words, a BMidiLocalConsumer or BMidiLocalProducer. 129*/ 130 131 132/*! 133 \fn bool BMidiEndpoint::IsPersistent() const 134 \brief Not used. 135 136 The purpose of this function is unclear, and as a result it doesn't do 137 anything in the Haiku Midi Kit implementation. 138 139 \return \c false always. 140*/ 141 142 143/*! 144 \fn bool BMidiEndpoint::IsValid() const 145 \brief Determines whether the endpoint still exists. 146 147 Suppose you obtained a proxy object for a remote endpoint by querying the 148 BMidiRoster. What if the application that published this endpoint quits, 149 or less drastically, Unregister()'s that endpoint? Even though you still 150 have a BMidiEndpoint proxy object, the real endpoint no longer exists. 151 You can use IsValid() to check for this. 152 153 Don't worry, operations on invalid objects, such as GetProperties(), will 154 return an error code (typically B_ERROR), but not cause a crash. Local 155 objects are always are considered to be valid, even if you did not 156 Register() them. (The only time a local endpoint is not valid is when there 157 was a problem constructing it.) 158 159 If the application that created the remote endpoint crashes, then there is 160 no guarantee that the Midi Server immediately recognizes this. In that 161 case, IsValid() may still return true. Eventually, the stale endpoint will 162 be removed from the roster, though. From then on, IsValid() correctly 163 returns \c false. 164*/ 165 166 167/*! 168 \fn status_t BMidiEndpoint::Acquire() 169 \brief Increments the endpoint's reference count 170 171 Each BMidiEndpoint has a reference count associated with it, so that 172 BMidiRoster can do proper bookkeeping. Acquire() increments this reference 173 count, and Release() decrements it. Once the count reaches zero, the 174 endpoint is deleted. 175 176 When you are done with the endpoint, whether local or remote, you should 177 always Release() it! 178 179 Upon construction, local endpoints start with a reference count of 1. Any 180 objects you obtain from BMidiRoster using the NextXXX() or FindXXX() 181 functions have their reference counts incremented in the process. If you 182 forget to call Release(), the objects won't be properly cleaned up and 183 you'll make a fool out of yourself. 184 185 After you Release() an object, you are advised not to use it any further. 186 If you do, your app will probably crash. That also happens if you Release() 187 an object too many times. 188 189 Typically, you don't need to call Acquire(), unless you have two disparate 190 parts of your application working with the same endpoint, and you don't 191 want to have to keep track of who needs to Release() the endpoint. Now you 192 simply have both of them release it. 193 194 \return Always returns B_OK 195 196 \sa Release() 197*/ 198 199/*! 200 \fn status_t BMidiEndpoint::Release() 201 \brief Decrements the endpoint's reference count. 202 203 \return Always returns B_OK 204 205 \sa Acquire() 206*/ 207 208/*! 209 \fn status_t BMidiEndpoint::Register() 210 \brief Publishes the endpoint on the roster 211 212 MIDI objects created by an application are invisible to other applications 213 until they are published. To publish an object use the Register() method. 214 The corresponding Unregister() method will cause an object to once again 215 become invisible to remote applications. 216 217 BMidiRoster also has Register() and Unregister() methods. You may also use 218 those methods to publish or hide your endpoints; both do the same thing. 219 220 Although it is considered bad style, calling Register() on local endpoints 221 that are already registered won't mess things up. The Midi Server will 222 simply ignore your request. Likewise for Unregister()'ing more than once. 223 Attempts to Register() or Unregister() remote endpoints will fail, of 224 course. 225 226 If you are \link BMidiRoster::StartWatching() watching \endlink, you will 227 <b>not</b> receive notifications for any local endpoints you register or 228 unregister. Of course, other applications <I>will</I> be notified about 229 your endpoints. 230 231 Existing connections will not be broken when an object is unregistered, 232 but future remote connections will be denied. When objects are destroyed, 233 they automatically become unregistered. 234 235 \returns B_OK on success, or an error code (typically \c B_ERROR) if 236 something went wrong. 237 238 \sa Unregister() 239*/ 240 241/*! 242 \fn status_t BMidiEndpoint::Unregister() 243 \brief Hides the endpoint from the roster/ 244 245 \sa Register() 246*/ 247 248/*! 249 \fn status_t BMidiEndpoint::SetProperties(const BMessage* props) 250 \brief Changes the properties of the endpoint 251 252 Endpoints can have properties, which is any kind of information that 253 might be useful to associate with a MIDI object. The properties are 254 stored in a BMessage. 255 256 Usage example: 257 258\code 259BMessage props; 260if (endpoint->GetProperties(&props) == B_OK) 261{ 262 ...add data to the message... 263 endpoint->SetProperties(&props); 264} 265\endcode 266 267 You are only allowed to call SetProperties() on a local object. 268 269 Properties should follow a protocol, so different applications will know 270 how to read each other's properties. The current protocol is very limited 271 -- it only allows you to associate icons with your endpoints. Be planned 272 to publish a more complete protocol that included additional information, 273 such as vendor/model names, copyright/version info, category, etc., but 274 they never got around to it. 275 276 <TABLE BORDER="1"> 277 <TR><TD>property</TD><TD>Vector icon (raw data)</TD></TR> 278 <TR><TD>field name</TD><TD>"icon"</TD></TR> 279 <TR><TD>field type</TD><TD>'VICN'</TD></TR> 280 </TABLE> 281 282 This vector icon is available under Haiku only, and comes as raw data, 283 not a BBitmap. Before being able to display it, you first must render 284 the vector icon in the size of your choice. 285 286 <TABLE BORDER="1"> 287 <TR><TD>property</TD><TD>Large (32x32) icon</TD></TR> 288 <TR><TD>field name</TD><TD>"be:large_icon"</TD></TR> 289 <TR><TD>field type</TD><TD>'ICON'</TD></TR> 290 </TABLE> 291 292 <TABLE BORDER="1"> 293 <TR><TD>property</TD><TD>Small (16x16) icon</TD></TR> 294 <TR><TD>field name</TD><TD>"be:mini_icon"</TD></TR> 295 <TR><TD>field type</TD><TD>'MICN'</TD></TR> 296 </TABLE> 297 298 The MidiUtil package (downloadable from the OpenBeOS website) contains a 299 number of convenient functions to associate icons with endpoints, so you 300 don't have to write that code all over again. 301 302 \sa GetProperties() 303*/ 304 305/*! 306 \fn status_t BMidiEndpoint::GetProperties(BMessage* props) const 307 \brief Reads the properties of the endpoint 308 309 Usage example: 310 311\code 312BMessage props; 313if (endpoint->GetProperties(&props) == B_OK) 314{ 315 ...examine the contents of the message... 316} 317\endcode 318 319 Note that GetProperties() overwrites the contents of your BMessage. 320 321 \sa SetProperties() 322*/ 323