i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Big docs cleanup.

Browse Source 
* Fixed headers including:
  - All rights reserved not All Rights Reserved.
  - name, [email protected] not name <[email protected]>
  - tabs and spaces
  - Authors: not Documented by:
* Renamed string.dox to String.dox
* Renamed midixxx.dox files to MidiXxx.dox
* Moved images into images subdirectories and updated Doxfile.
* Re-format all files with tabs instead of spaces.
* Fix many spelling mistakes.
* Added all files, classes, structs, and enums to libbe group.
This commit is contained in:
John Scipione
2013-02-07 02:01:19 -05:00
parent 8cf4ba89b6
commit 820dca4df6
109 changed files with 6698 additions and 5170 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/Doxyfile
+3 -3
View File
@@ -738,10 +738,10 @@ EXAMPLE_RECURSIVE = NO
# the \image command).
IMAGE_PATH = . \
interface \
interface/images \
keyboard \
midi2 \
storage
midi2/images \
storage/images
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
docs/user/apidoc.dox
+97 -74
View File
@@ -1,9 +1,12 @@
/*
* Copyright 2007 Niels Sascha Reedijk. All rights reserved.
* Copyright 2008-2013 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* John Scipione, [email protected]
*
* Proofreaders:
* Alan Smale, [email protected]
*/
@@ -67,8 +70,8 @@
not only means that they get the same name, but also that the order
of the methods, variables, functions, etc. will have to be the same.
-# The root directory of the public API headers is at \c
/trunk/headers/os. In a similar vein, the root of the documentation
files is at \c /trunk/docs/user. The subdirectory
headers/os. In a similar vein, the root of the documentation
files is at \c docs/user. The subdirectory
structure, or the division of kits, will also be replicated.
-# The name of the files is the same as the base of the header files,
with the \c dox extension. So \c Something.h becomes \c
@@ -80,41 +83,52 @@
copyright block, with a reference to the author(s) and against which
revision the documentation was written.
\verbatim
\verbatim
/*
* Copyright 2007 Niels Sascha Reedijk. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* Proofreaders:
* Alan Smale, [email protected]
* Corresponds to:
* /trunk/headers/os/support/String.h rev 19731
* /trunk/src/kits/support/String.cpp rev 19731
*/
\endverbatim
* Copyright 2007-2013 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Proofreaders:
* Alan Smale, [email protected]
*
* Corresponds to:
* headers/os/support/String.h rev 19731
* src/kits/support/String.cpp rev 19731
*/
\endverbatim
The example above has a few elements that you should take note of:
-# The header is put in a standard C comment, which is enclosed between \c
/* and \c *\/.
-# Every line starts with a whitespace and an asterix, followed by another
-# The header is put in a standard C comment, which is enclosed between
\verbatim
/*
\endverbatim
and
\verbatim
*/
\endverbatim
-# Every line starts with a whitespace and an asterisk followed by another
space. If the text is part of a category, such as <tt>Authors</tt>, put
three spaces after the delimiter.
-# The first line is empty, then we get to the copyright notice. You may
either retain the copyright yourself, or you can attribute to to Haiku
Inc. It's your choice. The next line is the \e MIT licence notice,
Inc. It's your choice. The next line is the \e MIT License notice,
followed by an empty line.
-# Then there is a label <tt>Authors:</tt>, which is followed by
lines with names and email addresses. The latter one is optional, but
recommended. Each author is preceeded by two tabs after the asterix.
recommended. Each author is proceeded by two tabs after the asterisk.
-# In the same vein there is the label <tt>Proofreaders:</tt> in case the
file has been proofread.
-# The final part is underneath the label <tt>Corresponds to:</tt>.
Underneath there is a list of files and their svn revisions that the
current documentation is known to correspond with.
-# The header block ends with the \c *\/, where the asterix is aligned with
the ones above it.
-# The header block ends with the
\verbatim
*/
\endverbatim
where the asterisk is aligned with the ones above it.
\subsection formalrequirements_blocks Blocks
@@ -126,27 +140,34 @@
we need to reproduce them in our \c dox files.
Blocks should adhere to the following standards:
-# All blocks open with \c /*! and close with \c * /
-# All blocks open with
\verbatim
/*!
\endverbatim
and close with
\verbatim
*/
\endverbatim
-# The documentation is placed in between these markers.
-# All the contents in between the markers is indented by tabs. The tab
length should be four.
-# Between blocks, there should be two empty lines.
-# The maximum width of the contents between blocks is 80 columns. <em>Try
not to cross this limit</em>, because it will severely limit
-# The maximum width of the contents between blocks is 80 columns. <b>Try
not to cross this limit</b>, because it will severely limit
readability.
Example:
\verbatim
\verbatim
/*!
\fn bool BList::AddItem(void *item)
\brief Append an item to the list.
\param item The item to add.
\retval true The item was appended.
\retval false Item was not appended, since resizing the list failed.
\sa AddItem(void *item, int32 index)
\fn bool BList::AddItem(void *item)
\brief Append an item to the list.
\param item The item to add.
\retval true The item was appended.
\retval false Item was not appended, since resizing the list failed.
\sa AddItem(void *item, int32 index)
*/
\endverbatim
\endverbatim
\note Doxygen also allows the use of single line comments, starting with
\c //!, however, we won't use these \b except for group markers, which
@@ -253,7 +274,6 @@
There are also a number of things that can be used in pages and member
documentation. See the style section to find out the appropriate situations
in which to use them.
- \c \\note {text}
- \c \\attention {text}
- \c \\warning {text}
@@ -312,7 +332,7 @@
same arguments as \c \\page, namely the \c \<name\> and the
<tt>(title)</tt>. If you need a deeper hierarchy you may use \c \\subsection
and \c \\subsubsection, again, both with the same syntax. If you need to
distinguish between sections in subsubsections, you are able to use
distinguish between sections in sub-sub-sections, you are able to use
\c \\paragraph, which takes the same arguments.
\note Before and after each of the commands above, you need to have an empty
@@ -349,17 +369,20 @@
\verbatim
/*!
\\name Appending Methods
These methods append things to the object.
\name Appending Methods
These methods append things to the object.
*/
//! \@{
... names of the methods ...
... methods ...
//! \@}
\endverbatim
The block preceding the block opening marker, <tt>//! \@{</tt>, contains a
@@ -401,7 +424,7 @@
Modules are defined in the main book, and you can add classes to them by
using the \c \\ingroup command. This commands adds the class to the module
and groups it on a separate page. At this moment, the group handling has yet
to be finalised. For now, add the classes to the kit they belong in. In the
to be finalized. For now, add the classes to the kit they belong in. In the
future this might change.
Finally, it is a good idea to link between parts of the documentation. There
@@ -431,10 +454,10 @@
here, which means you should use the right names. So use \b method
instead of function, and data member instead of variable (where
appropriate).
- Avoid informalism. Avoid constructs like 'if you want to
- Avoid in-formalism. Avoid constructs like 'if you want to
disconnect the object', but rather use 'to disconnect the object'. Avoid
familiarisms, or jokes.
familiarizes, or jokes.
\remarks It isn't the goal to create dry, legal-style documentation. Just
try to find a balance. Read through documentation that's already been
approved to get a hint of what you should be aiming for.
@@ -497,15 +520,15 @@
\verbatim
/*!
\file String.h
\brief Defines the BString class and global operators and functions for
handling strings.
\file String.h
\brief Defines the BString class and global operators and functions for
handling strings.
*/
/*!
\file SupportDefs.h
\brief Defines basic types and definitions for the Haiku API.
\file SupportDefs.h
\brief Defines basic types and definitions for the Haiku API.
*/
\endverbatim
@@ -619,15 +642,15 @@
They are a short phrase that mention what the variable contains. Example:
\verbatim
/*!
\var char* BString::fPrivateData
\brief BString's storage for data.
This member is deprecated and might even become \c private in future
releases.
If you are planning to derive from this object and you want to manipulate
the raw string data, please have a look at LockBuffer() and UnlockBuffer().
/*!
\var char* BString::fPrivateData
\brief BString's storage for data.
This member is deprecated and might even become \c private in future
releases.
If you are planning to derive from this object and you want to manipulate
the raw string data, please have a look at LockBuffer() and UnlockBuffer().
*/
\endverbatim
@@ -667,18 +690,18 @@
documentation belongs to the class description, not to the enumeration.
\subsection style_groups Groups
If you subdivide members of classes into groups, you have the ability to
apply some general information that will be listed above the listing of the
members in that group. See the section \ref commands_grouping on how to
define groups. This section is on what to put in the header block.
First of all, it's probably a good idea to give your group a name. This name
will be printed as a title and will enhance the clarity of what the group
contains. If you put the \c \\name command as the first command of a group,
the rest of the words on that line will be used as the title. You should
choose simple titles of no more than three words.
It's possible to add one or two paragraphs of information. These paragraphs
should contain some quick notes on which of the members in that group to use
for what purpose. See it as a quick subdivision that a developer could use
@@ -688,17 +711,18 @@
\verbatim
/*!
\name Comparison Methods
There are two different comparison methods. First of all there is the whole
range of operators that return a boolean value, secondly there are methods
that return an integer value, both case sensitive and case insensitive.
There are also global comparison operators and global compare functions.
You might need these in case you have a sort routine that takes a generic
comparison function, such as BList::SortItems().
See the String.h documentation file to see the specifics, as they are
basically the same as implemented in this class.
\name Comparison Methods
There are two different comparison methods. First of all there is the whole
range of operators that return a boolean value, secondly there are methods
that return an integer value, both case sensitive and case insensitive.
There are also global comparison operators and global compare functions.
You might need these in case you have a sort routine that takes a generic
comparison function, such as BList::SortItems().
See the String.h documentation file to see the specifics, as they are
basically the same as implemented in this class.
*/
\endverbatim
@@ -706,5 +730,4 @@
the members up into two groups and refers to other functions the developer
might be looking for. The hard limit is two (short) paragraphs. Using more
will not improve clarity.
*/
docs/user/app/Application.dox
+5 -3
View File
@@ -1,18 +1,20 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/app/Application.h rev 42794
* /trunk/src/kits/app/Application.cpp rev 42794
* headers/os/app/Application.h rev 42794
* src/kits/app/Application.cpp rev 42794
*/
/*!
\file Application.h
\ingroup app
\ingroup libroot
\brief Provides the BApplication class.
*/
docs/user/app/Clipboard.dox
+6 -3
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -7,13 +7,15 @@
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/app/Clipboard.h rev 42274
* /trunk/src/kits/app/Clipboard.cpp rev 42274
* headers/os/app/Clipboard.h rev 42274
* src/kits/app/Clipboard.cpp rev 42274
*/
/*!
\file Clipboard.h
\ingroup app
\ingroup libroot
\brief Provides the BClipboard class.
*/
@@ -27,6 +29,7 @@
/*!
\class BClipboard
\ingroup app
\ingroup libbe
\brief Used for short-term data storage between documents and
applications via copy and paste operations.
docs/user/app/Cursor.dox
+6 -3
View File
@@ -1,18 +1,20 @@
/*
* Copyright 2012 Haiku, Inc. All Rights Reserved.
* Copyright 2012 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/app/Cursor.h hrev45039
* /trunk/src/kits/app/Cursor.cpp hrev45039
* headers/os/app/Cursor.h hrev45039
* src/kits/app/Cursor.cpp hrev45039
*/
/*!
\file Cursor.h
\ingroup app
\ingroup libroot
\brief Provides the BCursor class.
*/
@@ -200,6 +202,7 @@
/*!
\class BCursor
\ingroup app
\ingroup libbe
\brief BCursor describes a view-wide or application-wide cursor.
\note As BeOS only supports 16x16 monochrome cursors, to see a nice
docs/user/app/Handler.dox
+8 -3
View File
@@ -1,22 +1,26 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/app/Handler.h rev 22577
* /trunk/src/kits/app/Handler.cpp rev 21332
* headers/os/app/Handler.h rev 22577
* src/kits/app/Handler.cpp rev 21332
*/
/*!
\file Handler.h
\ingroup app
\ingroup libroot
\brief Provides the BHandler class.
*/
///// Globals /////
/*!
\def B_OBSERVE_WHAT_CHANGE
\brief Internal.
@@ -51,6 +55,7 @@
/*!
\class BHandler
\ingroup app
\ingroup libbe
\brief Handles messages that are passed on by a BLooper.
The BHandler class implements two important pieces of functionality. It
docs/user/app/Looper.dox
+6 -3
View File
@@ -1,17 +1,19 @@
/*
* Copyright 2008, Haiku, Inc. All Rights Reserved.
* Copyright 2008 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/app/Looper.h rev 21863
* /trunk/src/kits/app/Looper.cpp rev 21864
* headers/os/app/Looper.h rev 21863
* src/kits/app/Looper.cpp rev 21864
*/
/*!
\file Looper.h
\ingroup app
\ingroup libroot
\brief Provides the BLooper class.
*/
@@ -25,6 +27,7 @@
/*!
\class BLooper
\ingroup app
\ingroup libbe
\brief Receive and process messages in a separate thread.
When an object of this class is created, the message loop can be started
docs/user/app/Message.dox
+200 -197
View File
File diff suppressed because it is too large Load Diff
docs/user/app/MessageFilter.dox
+9 -2
View File
@@ -1,14 +1,20 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* headers/os/app/MessageFilter.h
* src/kits/app/MessageFilter.cpp
*/
/*!
\file MessageFilter.h
\ingroup app
\ingroup libroot
\brief Provides BMessageFilter class.
*/
@@ -18,7 +24,7 @@
\brief Return Codes and Protocol of the #filter_hook.
These return codes should be used in your own filter_hook function, or by
your overrided BMessageFilter::Filter() function.
your overridden BMessageFilter::Filter() method.
*/
@@ -137,6 +143,7 @@
/*!
\class BMessageFilter
\ingroup app
\ingroup libbe
\brief Describes a message filter for BLooper and BHandler.
Objects of this class serve as a description of properties that incoming
docs/user/app/MessageQueue.dox
+5 -3
View File
@@ -1,10 +1,10 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007, Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/app/MessageQueue.h rev 19956
* /trunk/src/kits/app/MessageQueue.cpp rev 19956
@@ -12,6 +12,8 @@
/*!
\file MessageQueue.h
\ingroup app
\ingroup libroot
\brief Provides the BMessageQueue class.
*/
docs/user/app/_app_intro.dox
+6 -6
View File
@@ -1,21 +1,21 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk, [email protected]
*/
/*!
\page app_intro Introduction to the Application Kit.
The Application Kit should be your starting point if you want to write
native Haiku applications with a GUI. The application kit does
exactly as its name suggests; it is the basis for Haiku applications. You
should read through this document and the documents referenced here before
moving on to any other part of the API.
The Application Kit classes can be divided into two groups: the "messaging"
classes and the "system interaction" classes. The larger group contains
the messaging classes. Have a look at the \link app_messaging
@@ -29,7 +29,7 @@
- BMessageQueue
- BMessageRunner
- BMessenger
The second group is the system interaction classes. These classes
provide hooks for your application to interact with the rest of the system.
The most important class is BApplication. This is a list of all the
docs/user/app/_app_messaging.dox
+27 -30
View File
@@ -1,15 +1,14 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
*/
/*!
\page app_messaging Messaging Foundations
One of the foundations of the Haiku API is the messaging system. This
framework is the basis for the efficient multithreaded Haiku applications,
because it solves one of the fundamental issues of multithreading: it
@@ -17,21 +16,21 @@
framework allows inter-application messaging as well as
intra-application messaging, and it will always use the most effective
mechanism for the communication automatically.
This page will introduce you to the subject of messaging. It is meant as a
broad overview to the classes, rather than a tutorial. If you are looking
for effective messaging techniques or a tutorial on messaging, have a look
at the developer section of the Haiku website.
<b>Table of contents</b>
- Overview of the Messaging Classes
- Receiving and Handling Messages
- Sending messages
\section app_messaging_overview Overview of the Messaging Classes
\subsection app_messaging_overview_bmessage BMessage
The BMessage class is the class that is in the center of all the messenger
operations, because it represents a message. A message is nothing more than
an object that contains:
@@ -49,15 +48,15 @@
context. The Haiku API defines several messages and their required data
members. Several applications provide a scripting interface with defined
message syntax. You can do the same for your application.
\subsection app_messaging_overview_blooper BLooper
Objects of the BLooper type are objects that run message loops. Every
object runs in its own thread. The BLooper objects continually check for
incoming messages. To process the messages, the looper looks for message
handlers that handle the messages within the thread's context. Message
handling within a looper is synchronous.
BLooper inherits BHandler, the base class for message handling. However, it
is possible to chain additional handlers to the object. For example, if you
have an application that understands different networking protocols, and
@@ -65,23 +64,23 @@
can provide handlers that you can chain in your general message parser
thread. See AddHandler() and SetPreferredHandler() for information on
handlers.
Messages can be posted to the looper by using the object's PostMessage()
method. This method puts the message in the BMessageQueue of the looper.
Since PostMessage() is asynchronous, the message might not be handled
immediately. See \ref app_messaging_overview_bmessenger "BMessenger"
for a synchronous implementation.
Loopers can have a generic filter that discards messages based on
user-definable characteristics. The BMessageFilter class provides the
foundation for the qualifying of messages. See AddCommonFilterList() and
SetCommonFilterList() for more information.
To get the most out of the functionality of BLooper, it is usually
subclassed to create a self-contained event 'machine'. Most of the time,
these subclasses also perform the message handling, which is possible
due to the fact that it is also a subclass of BHandler.
In the Haiku API, there are two major classes that inherit BLooper:
the base application class, BApplication, and the window class, BWindow.
Because they inherit BLooper, each application and each window has its
@@ -90,47 +89,47 @@
event handling that requires more processing power, is done within its own
BLooper context. Networking usually qualifies as a candidate for its own
thread.
\subsection app_messaging_overview_bhandler BHandler
Objects of the BHandler type are associated to BLoopers. When they are
created, they should be passed to the BLooper::AddHandler() method of the
looper they want to handle messages for. They can then either be set as
preferred handlers (by chaining them with BLooper::SetPreferredHandler()),
or they can be added to other BHandlers with the SetNextHandler() method.
The magic of the class happens in the MessageReceived() method. In your
subclasses you override this method, to check the incoming BMessage.
Usually, you check the \c what member of the message in a switch statement.
If your handler cannot handle the object, it will pass the message on to
the parent class.
\warning Don't forget to actuall call the MessageReceived() method of the
base class. Failing to do this will mean that the message chain will
not completely be followed, which can lead to unhandled messages. There
might be some internal system messages that the Haiku API classes
handle, and not actually handling these messages could lead to
inconsistent internal behavior.
\subsection app_messaging_overview_bmessenger BMessenger
BMessenger objects can send messages to both local and remote targets. For
local targets, a BMessenger provides an advantage over directly calling
the BLooper::PostMessage() method: some variants of the
BMessenger::SendMessage() methods allow for synchronous replies. So, the
call will actually verify the handling thread processes the message, and
reply to the sender.
The other feature of BMessenger is that it is able to be constructed with
the signature of another application as argument. This allows the messenger
to pass messages to other applications. It facilitates inter-application
communication.
\subsection app_messaging-overview-other Other messaging classes
There are several convenience classes supplied with the application kit,
which can make your life easier in some specific cases.
- BInvoker binds together a message and a target. By calling
BInvoker::Invoke(), the message will be sent. This class is inherited by
the controls in the interface kit, such as BButton.
@@ -146,12 +145,10 @@
Filter() \endlink method.
\section app-messaging-receiving Receiving Messages
To do...
\section app-messaging-sending Sending Messages
To do...
*/
docs/user/book.css
+6 -6
View File
@@ -1,13 +1,13 @@
/*
* Copyright 2008, Haiku. All rights reserved.
* Copyright 2008-2013 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* François Revol <[email protected]>
* Stephan Aßmus <[email protected]>
* Braden Ewing <[email protected]>
* Humdinger <[email protected]>
* John Scipione <[email protected]>
* François Revol, [email protected]
* Stephan Aßmus, [email protected]
* Braden Ewing, [email protected]
* Humdinger, [email protected]
* John Scipione, [email protected]
*/
/* color names provided by: http://chir.ag/projects/name-that-color */
docs/user/drivers/USB3.dox
+785 -674
View File
File diff suppressed because it is too large Load Diff
docs/user/drivers/USB_spec.dox
+221 -159
View File
@@ -1,296 +1,358 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/drivers/USB_spec.h rev 19915
* headers/os/drivers/USB_spec.h rev 19915
*/
/*!
\file USB_spec.h
\brief General definitions as defined by the USB standard.
*/
/*!
\name Request Types: targets and direction
These request types can be used in the usb_module_info::send_request()
and usb_module_info::queue_request() methods. They specifiy both the type
of interface and the direction of the transfer.
These are usually combined with a category (found on this page).
\file USB_spec.h
\ingroup drivers
\ingroup libbe
\brief General definitions as defined by the USB standard.
*/
/*!
\name Request Types: targets and direction
These request types can be used in the usb_module_info::send_request()
and usb_module_info::queue_request() methods. They specifiy both the type
of interface and the direction of the transfer.
These are usually combined with a category (found on this page).
*/
//! @{
/*!
\def USB_REQTYPE_DEVICE_IN
\brief Device. In.
\def USB_REQTYPE_DEVICE_IN
\brief Device. In.
*/
/*!
\def USB_REQTYPE_DEVICE_OUT
\brief Device. Out.
\def USB_REQTYPE_DEVICE_OUT
\brief Device. Out.
*/
/*!
\def USB_REQTYPE_INTERFACE_IN
\brief Interface. In.
\def USB_REQTYPE_INTERFACE_IN
\brief Interface. In.
*/
/*!
\def USB_REQTYPE_INTERFACE_OUT
\brief Interface. Out.
\def USB_REQTYPE_INTERFACE_OUT
\brief Interface. Out.
*/
/*!
\def USB_REQTYPE_ENDPOINT_IN
\brief Endpoint. In.
*/
/*!
\def USB_REQTYPE_ENDPOINT_OUT
\brief Endpoint. Out.
\def USB_REQTYPE_ENDPOINT_IN
\brief Endpoint. In.
*/
/*!
\def USB_REQTYPE_OTHER_OUT
\brief Other. Out.
*/
/*!
\def USB_REQTYPE_OTHER_IN
\brief Other. In.
\def USB_REQTYPE_ENDPOINT_OUT
\brief Endpoint. Out.
*/
/*!
\def USB_REQTYPE_OTHER_OUT
\brief Other. Out.
*/
/*!
\def USB_REQTYPE_OTHER_IN
\brief Other. In.
*/
//! @}
/*!
\name Request Types: categories
These request types can be used in the usb_module_info::send_request()
and usb_module_info::queue_request() methods. They specifiy the category
of the transfer.
These are usually combined with a target and direction (found on this page).
/*!
\name Request Types: categories
These request types can be used in the usb_module_info::send_request()
and usb_module_info::queue_request() methods. They specifiy the category
of the transfer.
These are usually combined with a target and direction (found on this page).
*/
//! @{
/*!
\def USB_REQTYPE_STANDARD
\brief Request that adheres to the USB specifications.
*/
/*!
\def USB_REQTYPE_CLASS
\brief Request that adheres to the specifications of the class.
\def USB_REQTYPE_STANDARD
\brief Request that adheres to the USB specifications.
*/
/*!
\def USB_REQTYPE_VENDOR
\brief Request that is defined by the specifications of the vendor.
*/
/*!
\def USB_REQTYPE_RESERVED
\brief Reserved for special implementations.
\def USB_REQTYPE_CLASS
\brief Request that adheres to the specifications of the class.
*/
/*!
\def USB_REQTYPE_MASK
\brief Constant that can be used as mask over the requesttype field.
\def USB_REQTYPE_VENDOR
\brief Request that is defined by the specifications of the vendor.
*/
/*!
\def USB_REQTYPE_RESERVED
\brief Reserved for special implementations.
*/
/*!
\def USB_REQTYPE_MASK
\brief Constant that can be used as mask over the requesttype field.
*/
//! @}
/*!
\name Standard Request Values
These request values are defined by the USB standard. You can use these
constants in both the usb_module_info::send_request() and
usb_module_info::queue_request() methods.
\warning The stack handles most of these standard requests for you. Use the
supplied convenience functions the the usb_module_info interface rather than
doing the requests yourself. Some of these request may actually interfere
with the inner workings of the USB stack!
\name Standard Request Values
These request values are defined by the USB standard. You can use these
constants in both the usb_module_info::send_request() and
usb_module_info::queue_request() methods.
\warning The stack handles most of these standard requests for you. Use the
supplied convenience functions the the usb_module_info interface rather than
doing the requests yourself. Some of these request may actually interfere
with the inner workings of the USB stack!
*/
//! @{
/*!
\def USB_REQUEST_GET_STATUS
\brief Get the status of a device.
*/
/*!
\def USB_REQUEST_CLEAR_FEATURE
\brief Clear a feature.
\def USB_REQUEST_GET_STATUS
\brief Get the status of a device.
*/
/*!
\def USB_REQUEST_SET_FEATURE
\brief Set a feature.
*/
/*!
\def USB_REQUEST_SET_ADDRESS
\brief Set the device address.
\def USB_REQUEST_CLEAR_FEATURE
\brief Clear a feature.
*/
/*!
\def USB_REQUEST_GET_DESCRIPTOR
\brief Get a descriptor.
*/
/*!
\def USB_REQUEST_SET_DESCRIPTOR
\brief Update a descriptor to a supplied one.
\def USB_REQUEST_SET_FEATURE
\brief Set a feature.
*/
/*!
\def USB_REQUEST_GET_CONFIGURATION
\brief Get a configuration.
*/
/*!
\def USB_REQUEST_SET_CONFIGURATION
\brief Set the configuration.
\def USB_REQUEST_SET_ADDRESS
\brief Set the device address.
*/
/*!
\def USB_REQUEST_GET_INTERFACE
\brief Request an interface descriptor.
*/
/*!
\def USB_REQUEST_SET_INTERFACE
\brief Set a specific interface.
\def USB_REQUEST_GET_DESCRIPTOR
\brief Get a descriptor.
*/
/*!
\def USB_REQUEST_SYNCH_FRAME
\brief Synchronize a frame.
\def USB_REQUEST_SET_DESCRIPTOR
\brief Update a descriptor to a supplied one.
*/
/*!
\def USB_REQUEST_GET_CONFIGURATION
\brief Get a configuration.
*/
/*!
\def USB_REQUEST_SET_CONFIGURATION
\brief Set the configuration.
*/
/*!
\def USB_REQUEST_GET_INTERFACE
\brief Request an interface descriptor.
*/
/*!
\def USB_REQUEST_SET_INTERFACE
\brief Set a specific interface.
*/
/*!
\def USB_REQUEST_SYNCH_FRAME
\brief Synchronize a frame.
*/
//! @}
/*!
\name Descriptor Constants
These constants refer to a specific descriptor. They can be used when
building a standard USB request for a descriptor, or in the
usb_module_info::get_descriptor() method.
\name Descriptor Constants
These constants refer to a specific descriptor. They can be used when
building a standard USB request for a descriptor, or in the
usb_module_info::get_descriptor() method.
*/
//! @{
/*!
\def USB_DESCRIPTOR_DEVICE
\brief Constant for the device descriptor.
*/
/*!
\def USB_DESCRIPTOR_CONFIGURATION
\brief Constant for a configuration descriptor.
\def USB_DESCRIPTOR_DEVICE
\brief Constant for the device descriptor.
*/
/*!
\def USB_DESCRIPTOR_STRING
\brief Constant for a string descriptor.
*/
/*!
\def USB_DESCRIPTOR_INTERFACE
\brief Constant for an interface descriptor.
\def USB_DESCRIPTOR_CONFIGURATION
\brief Constant for a configuration descriptor.
*/
/*!
\def USB_DESCRIPTOR_ENDPOINT
\brief Constant for an endpoint descriptor.
\def USB_DESCRIPTOR_STRING
\brief Constant for a string descriptor.
*/
/*!
\def USB_DESCRIPTOR_INTERFACE
\brief Constant for an interface descriptor.
*/
/*!
\def USB_DESCRIPTOR_ENDPOINT
\brief Constant for an endpoint descriptor.
*/
//! @}
/*!
\name Feature Requests
These constants refer to standard feature requests. You can use these using
the convenient usb_module_info::set_feature() and
usb_module_info::clear_feature() methods.
\name Feature Requests
These constants refer to standard feature requests. You can use these
using the convenient usb_module_info::set_feature() and
usb_module_info::clear_feature() methods.
*/
//! @{
/*!
\def USB_FEATURE_DEVICE_REMOTE_WAKEUP
\brief Request a device to wakeup from remote calls.
*/
/*!
\def USB_FEATURE_ENDPOINT_HALT
\brief Request for a specific endpoint to halt.
\def USB_FEATURE_DEVICE_REMOTE_WAKEUP
\brief Request a device to wakeup from remote calls.
*/
/*!
\def USB_FEATURE_ENDPOINT_HALT
\brief Request for a specific endpoint to halt.
*/
//! @}
/*!
\name Endpoint Attributes
These constants refer to values in the usb_endpoint_descriptor::attributes
field.
\name Endpoint Attributes
These constants refer to values in the usb_endpoint_descriptor::attributes
field.
*/
//! @{
/*!
\def USB_ENDPOINT_ATTR_CONTROL
\brief Endpoint facilitates control transfers.
*/
/*!
\def USB_ENDPOINT_ATTR_ISOCHRONOUS
\brief Endpoint facilitates isochronous transfers.
\def USB_ENDPOINT_ATTR_CONTROL
\brief Endpoint facilitates control transfers.
*/
/*!
\def USB_ENDPOINT_ATTR_BULK
\brief Endpoint facilitates bulk transfers.
*/
/*!
\def USB_ENDPOINT_ATTR_INTERRUPT
\brief Endpoint facilitates interrupt transfers.
\def USB_ENDPOINT_ATTR_ISOCHRONOUS
\brief Endpoint facilitates isochronous transfers.
*/
/*!
\def USB_ENDPOINT_ATTR_MASK
\brief Constant to mask out transfer types.
\def USB_ENDPOINT_ATTR_BULK
\brief Endpoint facilitates bulk transfers.
*/
/*!
\def USB_ENDPOINT_ATTR_INTERRUPT
\brief Endpoint facilitates interrupt transfers.
*/
/*!
\def USB_ENDPOINT_ATTR_MASK
\brief Constant to mask out transfer types.
*/
//! @}
/*!
\name Endpoint Address
These constants refer to the direction that is embedded in the
usb_endpoint_descriptor::address field.
\name Endpoint Address
These constants refer to the direction that is embedded in the
usb_endpoint_descriptor::address field.
*/
//! @{
/*!
\def USB_ENDPOINT_ADDR_DIR_IN
\brief The endpoint provides data for the driver.
*/
/*!
\def USB_ENDPOINT_ADDR_DIR_OUT
\brief The endpoint accepts data from the host.
\def USB_ENDPOINT_ADDR_DIR_IN
\brief The endpoint provides data for the driver.
*/
/*!
\def USB_ENDPOINT_ADDR_DIR_OUT
\brief The endpoint accepts data from the host.
*/
//! @}
docs/user/drivers/drivers.dox
+4 -6
View File
@@ -1,9 +1,7 @@
/*!
\page drivers Drivers
\section topics Topics
- \ref fs_modules
- \ref usb_modules
\page drivers Drivers
\section topics Topics
- \ref fs_modules
- \ref usb_modules
*/
docs/user/drivers/fs_interface.dox
+1
View File
@@ -14,6 +14,7 @@
/*!
\file fs_interface.h
\ingroup drivers
\ingroup libbe
\brief Provides an interface for file system modules.
See the \ref fs_modules "introduction to file system modules" for a guide on
docs/user/drivers/fs_modules.dox
-1
View File
@@ -17,7 +17,6 @@
a simple mechanism for one-time module initializations. The same module is
used for accessing any volume of that FS type.
\section objects File System Objects
There are several types of objects a FS module has to deal with directly or
docs/user/drivers/usb_modules.dox
+387 -386
View File
@@ -1,386 +1,387 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
*/
/*!
\page usb_modules Writing drivers for USB devices
The introduction of USB standardized the way many devices connected to a
whole range of different computers and operating systems. It introduced a
standard that was capable of getting rid of all the legacy systems, such as
the LPT, the PS/2 and serial ports. The plug and play nature of the standard
were revolutional at the time of it's introduction, and it changed the way
in which operating systems interacted with devices.
With the grand standard that USB has become, Haiku has an implementation
of it. It supports both the USB 1.1 and USB 2.0 specifications, and when
Haiku R1 is released, it will support the three host controller standards:
UHCI, OHCI and EHCI. The modularized design of Haiku's USB stack also paves
the way for easy implementation of any future specifications, such as
Wireless USB.
\section usb_modules_scope The Scope of this Document
This document is written for driver developers that need to interact with
USB devices. The USB specification standardizes the communication between
the host controller and the devices, and how devices should transfer data,
but it does not prescribe a standard environment that Operating Systems
should provide to the driver interfaces. As such, every operating system has
it's own interface for drivers, and so does Haiku.
This document will point driver developers to relevant parts of the USB
module API and give a general impression of the workings of the USB stack.
This document will not give information on the basics of writing drivers, or
on how to use modules. Have a look elsewhere in this documentation for that.
This document also assumes a basic knowledge of the USB specification, and on
how you are supposed to interact with devices. See \ref usb_modules_resources
for tutorials on the web if you are looking for a basic introduction on
communication with the USB protocol.
\section usb_modules_structure Structure of the Stack
This section will outline how Haiku's USB stack is structured, and how you
can interact with this stack.
The goal of the USB stack is to provide a few basic features for drivers
interacting with USB devices. It is important that the stack maintains a
continually updated device grid, so that the driver modules are always
aware of the latest status. The stack should also facilitate communication
between drivers and the devices, by abstracting the actual transfering of
bits via the host controller hardware in the computer. The stack therefore
should implement a inituitive interface to give driver developers access to
all features and possibilities the USB specification offers, and at the same
time it should abstract many of the small requirements and peculiarities of
that specification.
The stack internally can be divided into two parts. The first part is the
core module. This module, called \c usb_busmanager, performs all the
operations required by the USB specification. For example, it performs the
necessary lowlevel initialization when new devices are connected, or all the
requirements when it comes to performing transfers. The core module also
is the module that provides the abstractions to driver developers. The other
part of the USB stack are the individual modules that control the different
host controllers. Haiku supports the three types in existence: UHCI, OHCI
and EHCI. These modules perform the communication between the core module
and the hardware. As driver developer, you won't have to interact with these
modules: the core module provides all the abstractions you need.
Thus, as a driver developer you are interfacing with the \c usb_busmanager
module. On Haiku, this module implements two API's. The \c v2 API, identical
to the API offered by BeOS R5, can be found in the \c USB2.h file. However,
for new drivers, or for ports, the recomended API is the \c v3 API, defined
in the USB3.h file. This API is identical to the one provided by Zeta. The
\c v2 API should be considered to be deprecated.
\section usb_modules_registration Initial Steps: Driver Registration
In order to be able to start using the USB stack to communicate with your
devices, you will need to perform some actions. This section will outline
those actions and will point you to their appropriate locations.
\note The code examples are based on the \c usb_hid driver written by
Jerome Duval. Have a look at this driver for a complete working example.
The following example gives an overview of the requirements to open the
USB module, and to start your driver registration in order to receive
connect and disconnect events.
\code
// Global variables and constants
usb_module_info *gUsb;
const char *kDriverName = "usb_hid";
static usb_support_descriptor sSupportedDevices[1] = {
{ USB_HID_DEVICE_CLASS, 0, 0, 0, 0 },
};
// Prototype for the hooks that are called when devices are added or removed
static status_t hid_device_added(const usb_device *dev, void **cookie);
static status_t hid_device_removed(void *cookie);
static usb_notify_hooks sNotifyHooks = {
hid_device_added,
hid_device_removed
};
// Driver initialization, called by the kernel when the driver is loaded
status_t
init_driver(void)
{
if (get_module(B_USB_MODULE_NAME, (module_info **)&gUsb) != B_OK)
return B_ERROR;
gUsb->register_driver(kDriverName, sSupportedDevices,
1, NULL);
gUsb->install_notify(kDriverName, &sNotifyHooks);
return B_OK;
}
\endcode
Basically, this boils down to three steps. The first step is to acquire the
usb_module_info module. This struct contains a set of function pointers that
you use to communicate with the stack. You can retrieve it like you would
retrieve any other module.
As soon as you have done that you can start registering your driver in the
stack. What you do is you pass a unique identifier to identify your driver,
zero or more \link usb_support_descriptor support descriptors \endlink
to provide the stack with information on which devices you support, and the
number of support descriptors you provided. The stack is very flexible with
what patterns it accepts, so even the most complex driver will be able to
pass it's credentials. Have a look at the \c usb_support_descriptor struct
and the \c usb_module_info::register_driver() call for all the details.
The last step in initialization is to provide the stack with notification
hooks. These are functions in your driver that the stack should call as soon
as a device is attached or removed. Please perform this call after your
internal driver data structures are initialized, because as soon as you
perform this call, the usb stack will start searching for already attached
devices that match the credentials. Have a look at
\c usb_module_info::install_notify() and the structure \c usb_notify_hooks
for the details on the signatures of your hooks.
\section usb_modules_changes Handling Device Changes
The USB stack will notify you of device connects and disconnects when they
occur. You will receive notifications as soon as you have supplied the hooks
to the stack, using \c usb_module_info::install_notify() . This section will
explain some of the details when it comes to handling device changes.
When a device is added, your supplied usb_notify_hooks::device_added() hook
will be called if its credentials matches one of your support descriptors.
Because the stack runs through all the registered drivers, it could be that
two or more drivers operate on the same device. The stack does not provide
a locking mechanism to prevent two conflicting drivers to get in each others
way. It is up to the device maker to have supplied such a mechanism.
\note In reality, it is very likely that your device will match at least one
other driver, because Haiku supplies the \c usb_raw driver. This driver
provides userland access to the usb devices and therefore it has a blank
support descriptor that matches everything. The \c usb_raw driver will
not conflict with your device interaction though (except when there is an
userland application that tries to meddle with your device).
If your driver is willing to accept the supplied device, and your
device_added() hook returns B_OK, the USB stack will ask the kernel to reload
your published devices, so that your device is visible in userspace in the
\c /dev tree.
The other event that the stack reports, device disconnection, should be
handled by your \c usb_notify_hooks::device_removed() hook. Because "plug and
play" also means "unplug and leave", you should make sure your driver is
capable of cleaning up in the likely event that the user removes their
device, even during transfers. In your hook function, you have the ability to
do clean up whatever there is to clean up, however, make sure that you cancel
all the pending transfers. Use the usb_module_info::cancel_queued_transfers()
call for that end. Also, don't forget to free the cookie you supplied in your
device_added() hook.
\section usb_modules_standard Standard USB Operations
One of the many conveniences of the Haiku USB API is the fact that many of
the standard operations can be performed by simple function calls. As such,
you won't have to build many of the standard requests the USB specification
defines by hand. This section will outline all the different conveniences and
will point you to where to look if you do need something more advanced.
\subsection usb_modules_standard_descriptors Configurations, Interfaces and Descriptors
Many standard USB operations have to do with configurations, interfaces and
descriptors. All these operations are accessible by convenience functions.
The device descriptor is one of the first things you will be interested in if
you want to check out a device. The device descriptor can be retrieved quite
easily using the \c usb_module_info::get_device_descriptor() call. The
retrieved descriptor complies to the one dictated by the USB standard.
Also important are configurations. Since every device has at least one
configuration, you should be able to retrieve and manipulate configurations.
You can use \c usb_module_info::get_nth_configuration() to get them. To set
a configuration, you should use \c usb_module_info::set_configuration(). To
get the active configuration, use \c usb_module_info::get_configuration().
\attention By default, Haiku's stack will set the configuration at offset
zero, which is according to the standard, the default configuration.
Do not rely on that if you first get the device, that the currently active
configuration is the default configuration though. Another driver might
have manipulated this device already.
Every configuration has associated interfaces. To make life easier, the stack
automatically gets the interface descriptors (and their associated
endpoints), and stores them in the \c usb_configuration_info structure. This
structure has a member called \link usb_configuration_info::interface
\c interface \endlink which is of the type \c usb_interface_list. That object
containts all the interfaces, including a pointer to the interface that is
currently active. Each interface is described as a \c usb_interface_info,
which is a container for the interface, its associated endpoints and any
unparsed descriptors. In order to change the active interface, you can use
the stack's \c usb_module_info::set_alt_interface() call.
Endpoints, the basic units with which you can communicate, are stored as
\c usb_endpoint_info structures. Each of these structures carries the actual
endpoint descriptor, and the accompanying usb_pipe handle that you can use to
actually send and receive data.
The last point of interest are descriptors. As you have seen, Haiku caches
all the relevant descriptors itself, however, you might want to retrieve any
other type of descriptor that could be relevant for your device. The
convenience function to use in such a case is the
\c usb_module_info::get_descriptor() call. This function takes all the
parameters needed to build the actual descriptor, and performs the request
over the default control pipe.
\subsection usb_modules_standard_features Features
Another one of the building blocks of USB are features. Every device should
provide for a number of standard features, but the USB specification also
leaves the option to using custom device specific features. Feature requests
can be performed on devices, interfaces and pipes (which are tied to
endpoints).
To set a feature, you can use the \c usb_module_info::set_feature() call. To
clear a feature, use the \c usb_module_info::clear_feature() call. One of the
most used feature calls is the call to clear a \c USB_FEATURE_ENDPOINT_HALT .
\subsection usb_modules_standard_other Other Standard Calls
To get the status of a device, an interface or an endpoint, you can use the
\c usb_module_info::get_status() call.
If you are using isochronous transfers, you can use the
\c usb_module_info::set_pipe_policy() to set the properties of the
isochronous pipe.
\section usb_modules_transfers Data Transfers
Transfering data is one of the basic building blocks of the USB protocol.
This section will demonstrate how to perform transfers via the four different
protocols the USB stack offers.
But first it is essential to show how to perform the transfers using the
\c usb_module_info interface. The interface provides five \c queue_*
functions, with the asterix being one of the following: \c bulk, \c bulk_v
(bulk transfers using a vector), \c interrupt, \c isochronous or \c request
(over the standard control pipe). These five functions work asynchronously,
which means that your driver is called back from a different thread when your
transfer is finished.
The five functions share some arguments. The first argument is always the
pipe that is associated with the endpoint (except for control transfers,
these only work on the device in general). All of the functions accept a data
buffer, and the length of that buffer. All of the functions require a
\c #usb_callback_func, a function in your driver that can be called in case a
transfer is finished. The functions also require a cookie that is provided to
the callback function.
The working order is as follows: first you queue a transfer, then you handle
the result in the callback function when it's done. The callback function
will be called with a \a status argument, in which you can check whether or
not the transfer actually succeeded. See this \link #usb_callback_func
description \endlink for how your callback function should behave and what
kind of status there might have been.
Finally, before going into the different transfer types, a note on buffer
ownership. The usb stack keeps the internal buffers tidy, but the buffer you
provide to the \c queue_* functions are yours. You are responsible for
allocating and freeing them, and you may do with them whatever you like,
\e except between queueing your transfer and the callback. During that period
you should consider the USB stack the owner of the buffer.
\subsection usb_modules_transfers_control Control Requests
Control requests are done over the device wide control pipe which is provided
by every device. Haiku's stack has two functions that you can use to perform
custom requests (opposed to many of the \ref usb_modules_standard
"standard operations"). Control transfers are the only transfers that you can
perform synchronously as well as asynchronously. The functions you can use
are \c usb_module_info::send_request() for synchronous requests and
\c usb_module_info::queue_request() for asynchronous requests.
Many of the constants that you should use when performing can be found in
the USB_spec.h file which is automatically included if you include the main
USB header. Have a look of how to use these constants in the following
example:
\code
// Send a request that is defined by the standard of this class. We retrieve
// a report from the device on one of its interfaces.
// This request is specified by the HID specification.
status = usb->send_request(dev,
USB_REQTYPE_INTERFACE_IN | USB_REQTYPE_CLASS,
USB_REQUEST_HID_GET_REPORT,
0x0100 | report_id, interfaceNumber, device->total_report_size,
device->buffer, &actual);
\endcode
\warning Both the \link usb_module_info::send_request() \a send_request()
\endlink and \link usb_module_info::queue_request() \a queue_request()
\endlink functions can be used to perform standard usb requests. Avoid
low-level operations, because the stack needs to keep its internal
data structures consistent. If you need to perform one of the
\ref usb_modules_standard "standard operations", use the provided
convenience functions.
\subsection usb_modules_transfers_interrupt Interrupt
Interrupt transfers apply to endpoints that receive data, or that can be
polled in several instances of time. The intervals are determined by the
endpoint descriptor.
To schedule a transfer, use usb_module_info::queue_interrupt(). You only have
to supply a buffer, the stack schedule the transfer in such a way that it
will be performed within a certain timeframe. To create a continuous
interrupt system, you should queue the next transfer in the callback function
of the previous. The stack will make sure that the new transfer will be
performed exactly after the required interval.
\subsection usb_modules_transfers_bulk Bulk
Bulk transfers are very similar to control transfers. They will be performed
as soon as possible without stalling other transfers, and they transfer data.
Bulk transfers are designed to transfer up to large amounts of data as
efficiently as possible. Performing bulk transfers isn't difficult, you
merely supply a buffer and the endpoint that should execute the request, and
you're set.
Bulk transfers come in two flavours. The first is
usb_module_info::queue_bulk(), which takes a standard data buffer. The second
flavour is the usb_module_info::queue_bulk_v() function, which is designed to
operate on (an array of) POSIX vectors. These functions only differ in the
buffer they accept, they function in exactly the same way.
\subsection usb_modules_transfers_isochronous Isochronous
Isochronous transfers are not implemented on Haiku yet. As soon as they are,
this section should contain information on how to queue them.
\section usb_modules_cleanup Cleaning Up
This section describes how to gracefully leave the stack after your driver is
requested to shut down.
There are truely only two simple actions to perform. The first is to
uninstall your notification hooks, using
\c usb_module_info::uninstall_notify(). The second action is to 'put' the
module.
\code
void
uninit_driver(void)
{
usb->uninstall_notify(kDriverName);
put_module(B_USB_MODULE_NAME);
}
\endcode
\section usb_modules_resources More Resources
This section should list more resources on the web.
*/
/*
* Copyright 2007 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
*/
/*!
\page usb_modules Writing drivers for USB devices
The introduction of USB standardized the way many devices connected to a
whole range of different computers and operating systems. It introduced a
standard that was capable of getting rid of all the legacy systems, such as
the LPT, the PS/2 and serial ports. The plug and play nature of the standard
was revolutionary at the time of its introduction, and it changed the way
which operating systems interacted with devices.
With the grand standard that USB has become, Haiku has an implementation
of it. It supports both the USB 1.1 and USB 2.0 specifications, and when
Haiku R1 is released, it will support the three host controller standards:
UHCI, OHCI and EHCI. The modularized design of Haiku's USB stack also paves
the way for easy implementation of any future specifications, such as
Wireless USB.
\section usb_modules_scope The Scope of this Document
This document is written for driver developers that need to interact with
USB devices. The USB specification standardizes the communication between
the host controller and the devices, and how devices should transfer data,
but it does not prescribe a standard environment that Operating Systems
should provide to the driver interfaces. As such, every operating system has
it's own interface for drivers, and so does Haiku.
This document will point driver developers to relevant parts of the USB
module API and give a general impression of the workings of the USB stack.
This document will not give information on the basics of writing drivers, or
on how to use modules. Have a look elsewhere in this documentation for that.
This document also assumes a basic knowledge of the USB specification, and on
how you are supposed to interact with devices. See \ref usb_modules_resources
for tutorials on the web if you are looking for a basic introduction on
communication with the USB protocol.
\section usb_modules_structure Structure of the Stack
This section will outline how Haiku's USB stack is structured, and how you
can interact with this stack.
The goal of the USB stack is to provide a few basic features for drivers
interacting with USB devices. It is important that the stack maintains a
continually updated device grid, so that the driver modules are always
aware of the latest status. The stack should also facilitate communication
between drivers and the devices, by abstracting the actual transferring of
bits via the host controller hardware in the computer. The stack therefore
should implement a intuitive interface to give driver developers access to
all features and possibilities the USB specification offers, and at the same
time it should abstract many of the small requirements and peculiarities of
that specification.
The stack internally can be divided into two parts. The first part is the
core module. This module, called \c usb_busmanager, performs all the
operations required by the USB specification. For example, it performs the
necessary low-level initialization when new devices are connected, or all the
requirements when it comes to performing transfers. The core module also
is the module that provides the abstractions to driver developers. The other
part of the USB stack are the individual modules that control the different
host controllers. Haiku supports the three types in existence: UHCI, OHCI
and EHCI. These modules perform the communication between the core module
and the hardware. As driver developer, you won't have to interact with these
modules: the core module provides all the abstractions you need.
Thus, as a driver developer you are interfacing with the \c usb_busmanager
module. On Haiku, this module implements two API's. The \c v2 API, identical
to the API offered by BeOS R5, can be found in the \c USB2.h file. However,
for new drivers, or for ports, the recommended API is the \c v3 API, defined
in the USB3.h file. This API is identical to the one provided by Zeta. The
\c v2 API should be considered to be deprecated.
\section usb_modules_registration Initial Steps: Driver Registration
In order to be able to start using the USB stack to communicate with your
devices, you will need to perform some actions. This section will outline
those actions and will point you to their appropriate locations.
\note The code examples are based on the \c usb_hid driver written by
Jerome Duval. Have a look at this driver for a complete working
example.
The following example gives an overview of the requirements to open the
USB module, and to start your driver registration in order to receive
connect and disconnect events.
\code
// Global variables and constants
usb_module_info *gUsb;
const char *kDriverName = "usb_hid";
static usb_support_descriptor sSupportedDevices[1] = {
{ USB_HID_DEVICE_CLASS, 0, 0, 0, 0 },
};
// Prototype for the hooks that are called when devices are added or removed
static status_t hid_device_added(const usb_device *dev, void **cookie);
static status_t hid_device_removed(void *cookie);
static usb_notify_hooks sNotifyHooks = {
hid_device_added,
hid_device_removed
};
// Driver initialization, called by the kernel when the driver is loaded
status_t
init_driver(void)
{
if (get_module(B_USB_MODULE_NAME, (module_info **)&gUsb) != B_OK)
return B_ERROR;
gUsb->register_driver(kDriverName, sSupportedDevices,
1, NULL);
gUsb->install_notify(kDriverName, &sNotifyHooks);
return B_OK;
}
\endcode
Basically, this boils down to three steps. The first step is to acquire the
usb_module_info module. This struct contains a set of function pointers that
you use to communicate with the stack. You can retrieve it like you would
retrieve any other module.
As soon as you have done that you can start registering your driver in the
stack. What you do is you pass a unique identifier to identify your driver,
zero or more \link usb_support_descriptor support descriptors \endlink
to provide the stack with information on which devices you support, and the
number of support descriptors you provided. The stack is very flexible with
what patterns it accepts, so even the most complex driver will be able to
pass it's credentials. Have a look at the \c usb_support_descriptor struct
and the \c usb_module_info::register_driver() call for all the details.
The last step in initialization is to provide the stack with notification
hooks. These are functions in your driver that the stack should call as soon
as a device is attached or removed. Please perform this call after your
internal driver data structures are initialized, because as soon as you
perform this call, the usb stack will start searching for already attached
devices that match the credentials. Have a look at
\c usb_module_info::install_notify() and the structure \c usb_notify_hooks
for the details on the signatures of your hooks.
\section usb_modules_changes Handling Device Changes
The USB stack will notify you of device connects and disconnects when they
occur. You will receive notifications as soon as you have supplied the hooks
to the stack, using \c usb_module_info::install_notify() . This section will
explain some of the details when it comes to handling device changes.
When a device is added, your supplied usb_notify_hooks::device_added() hook
will be called if its credentials matches one of your support descriptors.
Because the stack runs through all the registered drivers, it could be that
two or more drivers operate on the same device. The stack does not provide
a locking mechanism to prevent two conflicting drivers to get in each others
way. It is up to the device maker to have supplied such a mechanism.
\note In reality, it is very likely that your device will match at least one
other driver, because Haiku supplies the \c usb_raw driver. This driver
provides userland access to the usb devices and therefore it has a blank
support descriptor that matches everything. The \c usb_raw driver will
not conflict with your device interaction though (except when there is an
userland application that tries to meddle with your device).
If your driver is willing to accept the supplied device, and your
device_added() hook returns B_OK, the USB stack will ask the kernel to reload
your published devices, so that your device is visible in userspace in the
\c /dev tree.
The other event that the stack reports, device disconnection, should be
handled by your \c usb_notify_hooks::device_removed() hook. Because "plug and
play" also means "unplug and leave", you should make sure your driver is
capable of cleaning up in the likely event that the user removes their
device, even during transfers. In your hook function, you have the ability to
do clean up whatever there is to clean up, however, make sure that you cancel
all the pending transfers. Use the usb_module_info::cancel_queued_transfers()
call for that end. Also, don't forget to free the cookie you supplied in your
device_added() hook.
\section usb_modules_standard Standard USB Operations
One of the many conveniences of the Haiku USB API is the fact that many of
the standard operations can be performed by simple function calls. As such,
you won't have to build many of the standard requests the USB specification
defines by hand. This section will outline all the different conveniences and
will point you to where to look if you do need something more advanced.
\subsection usb_modules_standard_descriptors Configurations, Interfaces and Descriptors
Many standard USB operations have to do with configurations, interfaces and
descriptors. All these operations are accessible by convenience functions.
The device descriptor is one of the first things you will be interested in if
you want to check out a device. The device descriptor can be retrieved quite
easily using the \c usb_module_info::get_device_descriptor() call. The
retrieved descriptor complies to the one dictated by the USB standard.
Also important are configurations. Since every device has at least one
configuration, you should be able to retrieve and manipulate configurations.
You can use \c usb_module_info::get_nth_configuration() to get them. To set
a configuration, you should use \c usb_module_info::set_configuration(). To
get the active configuration, use \c usb_module_info::get_configuration().
\attention By default, Haiku's stack will set the configuration at offset
zero, which is according to the standard, the default configuration.
Do not rely on that if you first get the device, that the currently active
configuration is the default configuration though. Another driver might
have manipulated this device already.
Every configuration has associated interfaces. To make life easier, the stack
automatically gets the interface descriptors (and their associated
endpoints), and stores them in the \c usb_configuration_info structure. This
structure has a member called \link usb_configuration_info::interface
\c interface \endlink which is of the type \c usb_interface_list. That object
containts all the interfaces, including a pointer to the interface that is
currently active. Each interface is described as a \c usb_interface_info,
which is a container for the interface, its associated endpoints and any
unparsed descriptors. In order to change the active interface, you can use
the stack's \c usb_module_info::set_alt_interface() call.
Endpoints, the basic units with which you can communicate, are stored as
\c usb_endpoint_info structures. Each of these structures carries the actual
endpoint descriptor, and the accompanying usb_pipe handle that you can use to
actually send and receive data.
The last point of interest are descriptors. As you have seen, Haiku caches
all the relevant descriptors itself, however, you might want to retrieve any
other type of descriptor that could be relevant for your device. The
convenience function to use in such a case is the
\c usb_module_info::get_descriptor() call. This function takes all the
parameters needed to build the actual descriptor, and performs the request
over the default control pipe.
\subsection usb_modules_standard_features Features
Another one of the building blocks of USB are features. Every device should
provide for a number of standard features, but the USB specification also
leaves the option to using custom device specific features. Feature requests
can be performed on devices, interfaces and pipes (which are tied to
endpoints).
To set a feature, you can use the \c usb_module_info::set_feature() call. To
clear a feature, use the \c usb_module_info::clear_feature() call. One of the
most used feature calls is the call to clear a \c USB_FEATURE_ENDPOINT_HALT .
\subsection usb_modules_standard_other Other Standard Calls
To get the status of a device, an interface or an endpoint, you can use the
\c usb_module_info::get_status() call.
If you are using isochronous transfers, you can use the
\c usb_module_info::set_pipe_policy() to set the properties of the
isochronous pipe.
\section usb_modules_transfers Data Transfers
Transfering data is one of the basic building blocks of the USB protocol.
This section will demonstrate how to perform transfers via the four different
protocols the USB stack offers.
But first it is essential to show how to perform the transfers using the
\c usb_module_info interface. The interface provides five \c queue_*
functions, with the asterix being one of the following: \c bulk, \c bulk_v
(bulk transfers using a vector), \c interrupt, \c isochronous or \c request
(over the standard control pipe). These five functions work asynchronously,
which means that your driver is called back from a different thread when your
transfer is finished.
The five functions share some arguments. The first argument is always the
pipe that is associated with the endpoint (except for control transfers,
these only work on the device in general). All of the functions accept a data
buffer, and the length of that buffer. All of the functions require a
\c #usb_callback_func, a function in your driver that can be called in case a
transfer is finished. The functions also require a cookie that is provided to
the callback function.
The working order is as follows: first you queue a transfer, then you handle
the result in the callback function when it's done. The callback function
will be called with a \a status argument, in which you can check whether or
not the transfer actually succeeded. See this \link #usb_callback_func
description \endlink for how your callback function should behave and what
kind of status there might have been.
Finally, before going into the different transfer types, a note on buffer
ownership. The usb stack keeps the internal buffers tidy, but the buffer you
provide to the \c queue_* functions are yours. You are responsible for
allocating and freeing them, and you may do with them whatever you like,
\e except between queueing your transfer and the callback. During that period
you should consider the USB stack the owner of the buffer.
\subsection usb_modules_transfers_control Control Requests
Control requests are done over the device wide control pipe which is provided
by every device. Haiku's stack has two functions that you can use to perform
custom requests (opposed to many of the \ref usb_modules_standard
"standard operations"). Control transfers are the only transfers that you can
perform synchronously as well as asynchronously. The functions you can use
are \c usb_module_info::send_request() for synchronous requests and
\c usb_module_info::queue_request() for asynchronous requests.
Many of the constants that you should use when performing can be found in
the USB_spec.h file which is automatically included if you include the main
USB header. Have a look of how to use these constants in the following
example:
\code
// Send a request that is defined by the standard of this class. We retrieve
// a report from the device on one of its interfaces.
// This request is specified by the HID specification.
status = usb->send_request(dev,
USB_REQTYPE_INTERFACE_IN | USB_REQTYPE_CLASS,
USB_REQUEST_HID_GET_REPORT, 0x0100 | report_id,
interfaceNumber, device->total_report_size,
device->buffer, &actual);
\endcode
\warning Both the \link usb_module_info::send_request() \a send_request()
\endlink and \link usb_module_info::queue_request() \a queue_request()
\endlink functions can be used to perform standard usb requests. Avoid
low-level operations, because the stack needs to keep its internal
data structures consistent. If you need to perform one of the
\ref usb_modules_standard "standard operations", use the provided
convenience functions.
\subsection usb_modules_transfers_interrupt Interrupt
Interrupt transfers apply to endpoints that receive data, or that can be
polled in several instances of time. The intervals are determined by the
endpoint descriptor.
To schedule a transfer, use usb_module_info::queue_interrupt(). You only have
to supply a buffer, the stack schedule the transfer in such a way that it
will be performed within a certain timeframe. To create a continuous
interrupt system, you should queue the next transfer in the callback function
of the previous. The stack will make sure that the new transfer will be
performed exactly after the required interval.
\subsection usb_modules_transfers_bulk Bulk
Bulk transfers are very similar to control transfers. They will be performed
as soon as possible without stalling other transfers, and they transfer data.
Bulk transfers are designed to transfer up to large amounts of data as
efficiently as possible. Performing bulk transfers isn't difficult, you
merely supply a buffer and the endpoint that should execute the request, and
you're set.
Bulk transfers come in two flavours. The first is
usb_module_info::queue_bulk(), which takes a standard data buffer. The second
flavour is the usb_module_info::queue_bulk_v() function, which is designed to
operate on (an array of) POSIX vectors. These functions only differ in the
buffer they accept, they function in exactly the same way.
\subsection usb_modules_transfers_isochronous Isochronous
Isochronous transfers are not implemented on Haiku yet. As soon as they are,
this section should contain information on how to queue them.
\section usb_modules_cleanup Cleaning Up
This section describes how to gracefully leave the stack after your driver is
requested to shut down.
There are truely only two simple actions to perform. The first is to
uninstall your notification hooks, using
\c usb_module_info::uninstall_notify(). The second action is to 'put' the
module.
\code
void
uninit_driver(void)
{
usb->uninstall_notify(kDriverName);
put_module(B_USB_MODULE_NAME);
}
\endcode
\section usb_modules_resources More Resources
This section should list more resources on the web.
*/
docs/user/game/DirectWindow.dox
+34 -3
View File
@@ -13,30 +13,38 @@
/*!
\file DirectWindow.h
\ingroup game
\ingroup libbe
\brief Provides the DirectWindow class.
*/
/*!
\enum direct_buffer_state
Direct buffer state constants
*/
/*!
\enum direct_driver_state
Direct driver state constants
*/
/*!
\struct direct_buffer_info
\ingroup game
\ingroup libbe
Direct butter info struct
*/
/*!
\var direct_buffer_info::buffer_state
State of the direct buffer access privileges.
It can have one of the following values:
- \c B_DIRECT_MODE_MASK
@@ -52,81 +60,103 @@
/*!
\var direct_buffer_info::driver_state
State of the graphics card on which your direct window is displayed.
There are two possible values:
- \c B_MODE_CHANGED The resolution or color depth has changed.
- \c B_DRIVER_CHANGED The window was moved onto another monitor.
- \c B_MODE_CHANGED The resolution or color depth has changed.
- \c B_DRIVER_CHANGED The window was moved onto another monitor.
*/
/*!
\var direct_buffer_info::bits
Pointer to the frame buffer in your team's memory space.
*/
/*!
\var direct_buffer_info::pci_bits
Pointer to the frame buffer in the PCI memory space. This value is
typically needed to control DMA.
*/
/*!
\var direct_buffer_info::bytes_per_row
Number of bytes used to represent a single row of pixels in the frame buffer.
*/
/*!
\var direct_buffer_info::bits_per_pixel
number of bits actually used to store a single pixel, including reserved,
Number of bits actually used to store a single pixel, including reserved,
unused, or alpha channel bits. This value is usually a multiple of eight.
*/
/*!
\var direct_buffer_info::pixel_format
The format used to encode a pixel as defined by the \c color_space type.
*/
/*!
\var direct_buffer_info::layout
Reserved for future use.
*/
/*!
\var direct_buffer_info::orientation
Reserved for future use.
*/
/*!
\var direct_buffer_info::_reserved[9]
Reserved for future use.
*/
/*!
\var direct_buffer_info::_dd_type_
Reserved for future use.
*/
/*!
\var direct_buffer_info::_dd_token_
Reserved for future use.
*/
/*!
\var direct_buffer_info::clip_list_count
Number of rectangles in \c clip_list.
*/
/*!
\var direct_buffer_info::window_bounds
Rectangle that defines the full content area of the window in screen
coordinates.
*/
/*!
\var direct_buffer_info::clip_bounds
Bounding rectangle of the visible part of the content area of the window
in screen coordinates.
*/
@@ -134,6 +164,7 @@
/*!
\var direct_buffer_info::clip_list
List of rectangles that together define the visible region of the content
area of the window in screen coordinates.
*/
docs/user/game/FileGameSound.dox
+2
View File
@@ -13,6 +13,8 @@
/*!
\file FileGameSound.h
\ingroup game
\ingroup libbe
\brief Provides the BFileGameSound class.
*/
docs/user/game/GameProducer.dox
+4
View File
@@ -5,8 +5,10 @@
* Authors:
* Christopher ML Zumwalt May, [email protected]
* Omri Barak
*
* Proofreaders:
* John Scipione, [email protected]
*
* Corresponds to:
* src/kits/game/GameProducer.h rev 43514
* src/kits/game/GameProducer.cpp rev 43514
@@ -15,6 +17,8 @@
/*!
\file GameProducer.h
\ingroup game
\ingroup libbe
\brief Provides the GameProducer class.
*/
docs/user/interface/AbstractLayout.dox
+14 -1
View File
@@ -1,3 +1,16 @@
/*
* Copyright 2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Alex Wilson, [email protected]
*
* Corresponds to:
* headers/os/interface/AbstractLayout.h rev 39055
* src/kits/inteface/AbstractLayout.cpp rev 39055
*/
/*!
\class BAbstractLayout
\ingroup interface
@@ -6,7 +19,7 @@
\brief BLayout subclass providing convenience methods for derived
implementations.
This class is designed to reduce the amount of boilerplate code required to
write a BLayout subclass. In most cases, you classes should derive from
BAbstractLayout rather than BLayout.
docs/user/interface/Alert.dox
+27 -7
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2011, Haiku inc.
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* John Scipione <[email protected]>
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/Alert.h rev 42274
* /trunk/src/kits/interface/Alert.cpp rev 42274
@@ -12,12 +13,17 @@
/*!
\file Alert.h
\ingroup interface
\ingroup libbe
\brief BAlert class definition and support enums.
*/
/*!
\enum alert_type
\ingroup interface
\ingroup libbe
Determines which icon (if any) is displayed in the alert dialog.
Choose one option. If the constructor doesn't include an
alert_type argument than \c B_EMPTY_ALERT is used.
@@ -25,35 +31,47 @@
/*!
\var alert_type B_EMPTY_ALERT
No icon
*/
/*!
\var alert_type B_INFO_ALERT
\image html http://api.haiku-os.org/images/alert_info_32.png
Info icon
*/
/*!
\var alert_type B_IDEA_ALERT
\image html http://api.haiku-os.org/images/alert_idea_32.png
Idea icon
*/
/*!
\var alert_type B_WARNING_ALERT
\image html http://api.haiku-os.org/images/alert_warning_32.png
Warning icon
*/
/*!
\var alert_type B_STOP_ALERT
\image html http://api.haiku-os.org/images/alert_stop_32.png
Stop icon
*/
/*!
\enum button_spacing
\ingroup interface
\ingroup libbe
Determines how the buttons on the alert dialog are spaced relative
to each other. Choose one option. If the constructor doesn't include a
button_spacing argument than \c B_EVEN_SPACING is used.
@@ -61,12 +79,14 @@
/*!
\var button_spacing B_EVEN_SPACING
If the alert dialog has more than one button than the buttons are
spaced evenly across the bottom of the alert dialog.
*/
/*!
\var button_spacing B_OFFSET_SPACING
If the alert dialog has more than one button than the leftmost button
is offset to the left-hand side of the dialog while the rest of the
buttons are grouped on the right. This is useful to separate off a
@@ -104,13 +124,13 @@
The code used to create and display an alert dialog like the one shown
above is shown below:
\code
\code
BAlert* alert = new BAlert("Close and save dialog", "Save changes to...",
"Cancel", "Don't save", "Save", B_WIDTH_AS_USUAL, B_OFFSET_SPACING,
B_WARNING_ALERT);
"Cancel", "Don't save", "Save", B_WIDTH_AS_USUAL, B_OFFSET_SPACING,
B_WARNING_ALERT);
alert->SetShortcut(0, B_ESCAPE);
int32 button_index = alert->Go();
\endcode
\endcode
The messaged displayed in the dialog window along with the button labels
are set by the strings in the contructor. The Cancel button is offset to
docs/user/interface/Bitmap.dox
+12 -7
View File
@@ -1,17 +1,21 @@
/*
* Copyright 2011, Haiku inc.
* Distributed under the terms of the MIT Licence.
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Axel Dörfler, [email protected]
* John Scipione, [email protected]
*
* Documentation by:
* Axel Dörfler <[email protected]>
* John Scipione <[email protected]>
* Corresponds to:
* /trunk/headers/os/interface/Bitmap.h rev 42274
* /trunk/src/kits/interface/Bitmap.cpp rev 42274
*/
/*!
\file Bitmap.h
\ingroup interface
\ingroup libbe
\brief Defines the BBitmap class and global operators and functions for
handling bitmaps.
*/
@@ -34,10 +38,11 @@
An example of creating a new 32x32 pixel BBitmap object and assigning the
icon of the current application looks like this:
\code
\code
BBitmap iconBitmap = new BBitmap(BRect(0, 0, 31, 31), B_RGBA32));
appFileInfo.GetIcon(iconBitmap, B_LARGE_ICON);
\endcode
\endcode
You can access the properties of a bitmap by calling the Bounds(),
Flags(), ColorSpace(), Area(), Bits(), BitsLength(), BytesPerRow(),
docs/user/interface/Box.dox
+7 -3
View File
@@ -1,11 +1,12 @@
/*
* Copyright 2010, Haiku inc.
* Distributed under the terms of the MIT Licence.
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Authors:
* Clark Gaeble
* Adrien Destugues <[email protected]>
* John Scipione <[email protected]>
*
* Corresponds to:
* /trunk/headers/os/interface/Box.h rev 42274
* /trunk/src/kits/interface/Box.cpp rev 42274
@@ -13,6 +14,8 @@
/*!
\file Box.h
\ingroup interface
\ingroup libbe
\brief Defines the BBox class
*/
@@ -20,6 +23,7 @@
/*!
\class BBox
\ingroup interface
\ingroup libbe
\brief A rectangular view with a border and an optional label to group
related subviews visually.
docs/user/interface/Button.dox
+8 -4
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2011, Haiku inc.
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/Button.h rev 42794
* /trunk/src/kits/interface/Button.cpp rev 42794
@@ -11,6 +12,8 @@
/*!
\file Button.h
\ingroup interface
\ingroup libbe
\brief Describes the BButton class.
*/
@@ -18,6 +21,7 @@
/*!
\class BButton Button.h
\ingroup interface
\ingroup libbe
\brief A BButton is a labeled on-screen button.
A BButton control is used to initiate an action. An action is activated
@@ -29,8 +33,8 @@
A BButton, unlike other user interface elements such as check boxes and
radio buttons has only a single state. During a click event the
BButton's value is set to \c 1, (\c B_CONTROL_ON) otherwise this value
is \c 0 (\c B_CONTROL_OFF).
BButton's value is set to 1, (\c B_CONTROL_ON) otherwise this value
is 0 (\c B_CONTROL_OFF).
BButton inherits from the BControl class.
*/
docs/user/interface/CheckBox.dox
+7 -3
View File
@@ -1,18 +1,22 @@
/*
* Copyright 2011, Haiku inc.
* Distributed under the terms of the MIT Licence.
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Authors:
* Stephan Aßmus, [email protected]
* Marc Flerackers, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/CheckBox.h rev 42794
* /trunk/src/kits/interface/CheckBox.cpp rev 42794
*/
/*!
\file CheckBox.h
\ingroup interface
\ingroup libbe
\brief Defines the BCheckBox class
*/
docs/user/interface/ColorControl.dox
+21 -9
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2011, Haiku inc.
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/ColorControl.h rev 42794
* /trunk/src/kits/interface/ColorControl.cpp rev 42794
@@ -12,37 +13,48 @@
/*!
\file ColorControl.h
\ingroup interface
\ingroup libbe
\brief BColorControl class definition and support enums.
*/
/*! \enum color_control_layout
/*!
\enum color_control_layout
\ingroup interface
\ingroup libbe
Enumeration of the color control layout options.
*/
/*!
\var color_control_layout B_CELLS_4x64
cells are arranged in 4 columns, 64 rows.
Cells are arranged in 4 columns, 64 rows.
*/
/*!
\var color_control_layout B_CELLS_8x32
cells are arranged in 8 columns, 32 rows.
Cells are arranged in 8 columns, 32 rows.
*/
/*!
\var color_control_layout B_CELLS_16x16
cells are arranged in 16 columns, 16 rows.
Cells are arranged in 16 columns, 16 rows.
*/
/*!
\var color_control_layout B_CELLS_32x8
cells are arranged in 32 columns, 8 rows.
Cells are arranged in 32 columns, 8 rows.
*/
/*!
\var color_control_layout B_CELLS_64x4
cells are arranged in 64 columns, 4 rows.
Cells are arranged in 64 columns, 4 rows.
*/
@@ -64,7 +76,7 @@
An example of creating a color control looks like this:
\code
colorControl = new BColorControl(BPoint(0, 0), B_CELLS_32x8, 7.0,
"ColorControl", new BMessage(kValueChanged));
"ColorControl", new BMessage(kValueChanged));
colorControl->SetValue(0x336698);
\endcode
docs/user/interface/Control.dox
+10 -4
View File
@@ -1,29 +1,35 @@
/*
* Copyright 2011, Haiku inc.
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/Control.h rev 42794
* /trunk/src/kits/interface/Control.cpp rev 42794
*/
/*!
\file Control.h
\ingroup interface
\ingroup libbe
\brief BControl class definition and support enums.
*/
/*!
\var B_CONTROL_ON
Control on
Control on. Value equal to 1.
*/
/*!
\var B_CONTROL_OFF
Control off
Control off. Value equal to 0.
*/
docs/user/interface/Dragger.dox
+4 -2
View File
@@ -1,8 +1,8 @@
/*
* Copyright 2012 Haiku inc.
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
@@ -12,6 +12,8 @@
/*!
\file Dragger.h
\ingroup interface
\ingroup libbe
\brief Provides the BDragger class.
*/
docs/user/interface/Font.dox
+105 -25
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2013 Haiku inc.
* Copyright 2013 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* John Scipione <[email protected]>
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/Font.h hrev45178
* /trunk/src/kits/interface/Font.cpp hrev45178
@@ -12,6 +13,8 @@
/*!
\file Font.h
\ingroup interface
\ingroup libbe
\brief BFont class definition, unicode_block class definition, and
font-related struct and enum definitions.
*/
@@ -19,12 +22,14 @@
/*!
\var B_CHAR_SPACING
Position each character without adjustment. Best mode for printing.
*/
/*!
\var B_STRING_SPACING
Optimizes the position of each character within it's space. Collisions
are unlikely but characters may touch each other. Best mode to use when
the screen needs to match what appears on the printed page.
@@ -33,6 +38,7 @@
/*!
\var B_BITMAP_SPACING
The widths of the characters are chosen so that they never collide and
rarely touch. Best mode for drawing small amounts of text.
*/
@@ -40,225 +46,267 @@
/*!
\var B_FIXED_SPACING
Positions characters at a constant width. Best mode for fixed-width fonts.
*/
/*!
\enum font_direction
\ingroup interface
\ingroup libbe
Determines the direction of the text rendered by the font,
left-to-right or right-to-left.
*/
/*!
\var font_direction B_FONT_LEFT_TO_RIGHT
Left to right.
*/
/*!
\var font_direction B_FONT_RIGHT_TO_LEFT
Right to left.
*/
/*!
\var B_DISABLE_ANTIALIASING
Disable antialiasing. Used by BFont::Flags() and BFont::SetFlags().
*/
/*!
\var B_FORCE_ANTIALIASING
Force antialiasing. Used by BFont::Flags() and BFont::SetFlags().
*/
/*!
\var B_TRUNCATE_END
Truncate from the end of the string.
*/
/*!
\var B_TRUNCATE_BEGINNING
Truncate from the beginning of the string.
*/
/*!
\var B_TRUNCATE_MIDDLE
Truncate from the middle of the string.
*/
/*!
\var B_TRUNCATE_SMART
Truncate while keeping each string unique.
*/
/*!
\var B_UNICODE_UTF8
UTF-8 font encoding.
*/
/*!
\var B_ISO_8859_1
ISO 8859-1 aka Latin 1 "Western European" font encoding.
*/
/*!
\var B_ISO_8859_2
ISO 8859-2 aka Latin 2 "Eastern European" font encoding.
*/
/*!
\var B_ISO_8859_3
ISO 8859-3 aka Latin 3 "South European" font encoding.
*/
/*!
\var B_ISO_8859_4
ISO 8859-4 aka Latin 4 "Northern European" font encoding.
*/
/*!
\var B_ISO_8859_5
ISO 8859-5 "Latin/Cyrillic" font encoding.
*/
/*!
\var B_ISO_8859_6
ISO 8859-6 "Latin/Arabic" font encoding.
*/
/*!
\var B_ISO_8859_7
ISO 8859-7 "Latin/Greek" font encoding.
*/
/*!
\var B_ISO_8859_8
ISO 8859-8 "Latin/Hebrew" font encoding.
*/
/*!
\var B_ISO_8859_9
ISO 8859-9 aka Latin 5 "Latin/Turkish" font encoding.
*/
/*!
\var B_ISO_8859_10
ISO 8859-10 aka Latin 6 "Nordic" font encoding.
*/
/*!
\var B_MACINTOSH_ROMAN
Macintosh Roman font encoding.
*/
/*!
\var B_HAS_TUNED_FONT
flags for get_font_family() and get_font_style()
Flags for get_font_family() and get_font_style()
*/
/*!
\var B_IS_FIXED
flags for get_font_family() and get_font_style()
*/
/*!
\var B_ITALIC_FACE
Italic font face flag.
*/
/*!
\var B_UNDERSCORE_FACE
Underscore font face flag.
*/
/*!
\var B_NEGATIVE_FACE
Negative font face flag.
*/
/*!
\var B_OUTLINED_FACE
Outline font face flag.
*/
/*!
\var B_STRIKEOUT_FACE
Strikeout font face flag.
*/
/*!
\var B_BOLD_FACE
Bold font face flag.
*/
/*!
\var B_REGULAR_FACE
Regular font face flag.
*/
/*!
\var B_CONDENSED_FACE
Condensed font face flag. Not in BeOS 5.
*/
/*!
\var B_LIGHT_FACE
Light font face flag. Not in BeOS 5.
*/
/*!
\var B_HEAVY_FACE
Heavy font face flag. Not in BeOS 5.
*/
/*!
\enum font_metric_mode
Font metric mode, screen or printing.
*/
/*!
\var font_metric_mode B_SCREEN_METRIC
Screen font metric mode.
*/
/*!
\var font_metric_mode B_PRINTING_METRIC
Printing font metric mode.
*/
/*!
\enum font_file_format
\ingroup interface
\ingroup libbe
Font file format, TrueType™ or PostScript™ Type1.
\see BFont::FileFormat()
@@ -266,17 +314,21 @@
/*!
\var font_file_format B_TRUETYPE_WINDOWS
TrueType™ font file format.
*/
/*!
\var font_file_format B_POSTSCRIPT_TYPE1_WINDOWS
PostScript™ Type1 font file format.
*/
/*!
\class unicode_block
\ingroup interface
\ingroup libbe
\brief Describes the blocks of Unicode characters supported by a font.
\see BFont::Blocks()
@@ -392,6 +444,8 @@
/*!
\struct edge_info
\ingroup interface
\ingroup libbe
\brief The distance that a character outline is inset from its escapement
boundaries.
@@ -404,20 +458,24 @@
/*!
\var edge_info::left
\brief The distance that the character outline is inset from the left
escapement boundary.
The distance that the character outline is inset from the left
escapement boundary.
*/
/*!
\var edge_info::right
\brief The distance that the character outline is inset from the right
escapement boundary.
The distance that the character outline is inset from the right
escapement boundary.
*/
/*!
\struct font_height
\ingroup interface
\ingroup libbe
\brief The amount of vertical space surrounding a character.
\see BFont::GetHeight()
@@ -426,24 +484,29 @@
/*!
\var font_height::ascent
\brief The distance characters can ascend above the baseline.
The distance characters can ascend above the baseline.
*/
/*!
\var font_height::descent
\brief The distance characters can descend below the baseline.
The distance characters can descend below the baseline.
*/
/*!
\var font_height::leading
\brief The distance between lines, descent above to ascent below.
The distance between lines, descent above to ascent below.
*/
/*!
\struct escapement_delta
\ingroup interface
\ingroup libbe
\brief The amount of horizontal space surrounding a character.
Escapements need to be multiplied by the font size to get the correct
@@ -455,60 +518,72 @@
/*!
\var escapement_delta::nonspace
\brief The amount of space surrounding a character with a visible glyph.
The amount of space surrounding a character with a visible glyph.
*/
/*!
\var escapement_delta::space
\brief The amount of space surrounding a whitespace character, for example
\c B_TAB and \c B_SPACE.
The amount of space surrounding a whitespace character, for example
\c B_TAB and \c B_SPACE.
*/
/*!
\struct font_cache_info
\ingroup interface
\ingroup libbe
\brief Font cache parameters.
*/
/*!
\var font_cache_info::sheared_font_penalty
\brief Sheared font penalty.
Sheared font penalty.
*/
/*!
\var font_cache_info::rotated_font_penalty
\brief Rotated font penalty.
Rotated font penalty.
*/
/*!
\var font_cache_info::oversize_threshold
\brief Oversize threshold.
Oversize threshold.
*/
/*!
\var font_cache_info::oversize_penalty
\brief Oversize penalty.
Oversize penalty.
*/
/*!
\var font_cache_info::cache_size
\brief Cache size.
Cache size.
*/
/*!
\var font_cache_info::spacing_size_threshold
\brief Spacing size threshold.
Spacing size threshold.
*/
/*!
\struct tuned_font_info
\ingroup interface
\ingroup libbe
\brief Tuning information of fonts used to make it look better when
displayed on-screen.
@@ -519,30 +594,35 @@
/*!
\var tuned_font_info::size
\brief Font size.
Font size.
*/
/*!
\var tuned_font_info::shear
\brief Font shear.
Font shear.
*/
/*!
\var tuned_font_info::rotation
\brief Font rotation.
Font rotation.
*/
/*!
\var tuned_font_info::flags
\brief Font flags.
Font flags.
*/
/*!
\var tuned_font_info::face
\brief Font face.
Font face.
*/
docs/user/interface/GridLayout.dox
+10 -7
View File
@@ -1,17 +1,21 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Alex Wilson <[email protected]>
* Authors:
* Alex Wilson, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/GridLayout.h rev 38207
* /trunk/src/kits/interface/GridLayout.cpp rev 38207
* headers/os/interface/GridLayout.h rev 38207
* src/kits/interface/GridLayout.cpp rev 38207
*/
/*!
\file GridLayout.h
\ingroup interface
\ingroup layout
\ingroup libbe
\brief Provides the BGridLayout class.
*/
@@ -21,9 +25,8 @@
\ingroup interface
\ingroup layout
\ingroup libbe
\brief The BGridLayout class a BLayout subclass that arranges the items it
holds in a grid.
holds in a grid.
Each item in a BGridLayout receives a rectangular area which can span more
than a single row or column. The indexing of columns and rows is zero based,
docs/user/interface/GroupLayout.dox
+44 -23
View File
@@ -1,17 +1,21 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Alex Wilson <[email protected]>
* Authors:
* Alex Wilson, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/GroupLayout.h rev 38207
* /trunk/src/kits/interface/GroupLayout.cpp rev 38207
* headers/os/interface/GroupLayout.h rev 38207
* src/kits/interface/GroupLayout.cpp rev 38207
*/
/*!
\file GroupLayout.h
\ingroup interface
\ingroup layout
\ingroup libbe
\brief Describes the BGroupLayout class.
*/
@@ -21,7 +25,7 @@
\ingroup layout
\ingroup libbe
\brief The BGroupLayout class is a simple BLayout subclass that
arranges the items it holds within a vertical or horizontal box.
arranges the items it holds within a vertical or horizontal box.
In a horizontal BGroupLayout, each BLayoutItem is given the same vertical
area, but different horizontal areas. In a vertical BGroupLayout, each
@@ -47,7 +51,8 @@
*/
/*! \fn BGroupLayout::BGroupLayout(enum orientation orientation, float spacing)
/*!
\fn BGroupLayout::BGroupLayout(enum orientation orientation, float spacing)
\brief Creates a new BGroupLayout.
\param orientation The #orientation of this BGroupLayout.
@@ -55,52 +60,61 @@
*/
/*! \fn BGroupLayout::~BGroupLayout()
/*!
\fn BGroupLayout::~BGroupLayout()
\brief Destructor method.
Standard Destructor.
*/
/*! \fn BGroupLayout::BGroupLayout(BMessage* from)
/*!
\fn BGroupLayout::BGroupLayout(BMessage* from)
\brief Archive constructor.
\param from The message to construct the BGroupLayout from.
*/
/*! \fn float BGroupLayout::Spacing() const
/*!
\fn float BGroupLayout::Spacing() const
\brief Get the amount of spacing (in pixels) between each item.
*/
/*! \fn void BGroupLayout::SetSpacing(float spacing)
/*!
\fn void BGroupLayout::SetSpacing(float spacing)
\brief Set the amount of spacing (in pixels) between each item.
*/
/*! \fn orientation BGroupLayout::Orientation() const
/*!
\fn orientation BGroupLayout::Orientation() const
\brief Get the #orientation of this BGroupLayout.
*/
/*! \fn void BGroupLayout::SetOrientation(enum orientation orientation)
/*!
\fn void BGroupLayout::SetOrientation(enum orientation orientation)
\brief Set the #orientation of this BGroupLayout.
\param orientation The new #orientation of this BGroupLayout.
*/
/*! \fn float BGroupLayout::ItemWeight(int32 index) const
/*!
\fn float BGroupLayout::ItemWeight(int32 index) const
\brief Get the weight of the item at \a index.
*/
/*! \fn void BGroupLayout::SetItemWeight(int32 index, float weight)
/*!
\fn void BGroupLayout::SetItemWeight(int32 index, float weight)
\brief Set the weight of the item at \a index.
*/
/*! \fn BLayoutItem* BGroupLayout::AddView(BView* child)
/*!
\fn BLayoutItem* BGroupLayout::AddView(BView* child)
\brief Adds \a child to this layout as the last item. In a vertical
BGroupLayout, \a child will be on the right, in a horizontal
BGroupLayout, \a child will be at the bottom.
@@ -109,27 +123,31 @@
*/
/*! \fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child)
/*!
\fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child)
\brief Adds \a child to this layout at \a index.
\a child will have a weight of \c 1.0f.
*/
/*! \fn BLayoutItem* BGroupLayout::AddView(BView* child, float weight)
/*!
\fn BLayoutItem* BGroupLayout::AddView(BView* child, float weight)
\brief Adds \a child to the end of this layout with a weight of
\a weight.
*/
/*! \fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child,
/*!
\fn BLayoutItem* BGroupLayout::AddView(int32 index, BView* child,
float weight)
\brief Adds \a child this layout at \a index with a weight of
\a weight.
*/
/*! \fn bool BGroupLayout::AddItem(BLayoutItem* item)
/*!
\fn bool BGroupLayout::AddItem(BLayoutItem* item)
\brief Adds \a item to this layout as the last item. In a vertical
BGroupLayout, \a item will be on the right, in a horizontal
BGroupLayout, \a item will be at the bottom.
@@ -138,20 +156,23 @@
*/
/*! \fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item)
/*!
\fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item)
\brief Adds \a item to this layout at \a index.
\a item will have a weight of \c 1.0f.
*/
/*! \fn bool BGroupLayout::AddItem(BLayoutItem* item, float weight)
/*!
\fn bool BGroupLayout::AddItem(BLayoutItem* item, float weight)
\brief Adds \a item to the end of this layout with a weight of
\a weight.
*/
/*! \fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item, float weight)
/*!
\fn bool BGroupLayout::AddItem(int32 index, BLayoutItem* item, float weight)
\brief Adds \a item this layout at \a index with a weight of
\a weight.
*/
docs/user/interface/IconUtils.dox
+8 -5
View File
@@ -1,17 +1,20 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Adrien Destugues <[email protected]>
* Authors:
* Adrien Destugues, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/IconUtils.h rev 42600
* /trunk/src/kits/interface/IconUtils.cpp rev 42600
* headers/os/interface/IconUtils.h rev 42600
* src/kits/interface/IconUtils.cpp rev 42600
*/
/*!
\file IconUtils.h
\ingroup interface
\ingroup libbe
\brief Vector icon handling utility class
*/
docs/user/interface/InterfaceDefs.dox
+39 -6
View File
@@ -1,20 +1,35 @@
/*
* Copyright 2001-2011, Haiku, Inc. All rights reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/interface/InterfaceDefs.h rev 43230
* src/kits/interface/InterfaceDefs.cpp rev 43230
*/
/*!
\file InterfaceDefs.h
\ingroup interface
\ingroup libbe
\brief Defines standard interface definitions for controls.
*/
/*!
\enum border_style
\ingroup interface
\ingroup libbe
Collection of flags that determine the border style drawn around a BBox.
*/
/*! \var border_style B_PLAIN_BORDER
/*!
\var border_style B_PLAIN_BORDER
\image html B_PLAIN_BORDER.png
@@ -23,7 +38,9 @@
is raised slightly above the surrounding surface.
*/
/*! \var border_style B_FANCY_BORDER
/*!
\var border_style B_FANCY_BORDER
\image html B_FANCY_BORDER.png
@@ -31,45 +48,61 @@
in appearance on all four sides. This is the default appearance.
*/
/*! \var border_style B_NO_BORDER
/*!
\var border_style B_NO_BORDER
No border.
*/
/*!
\enum orientation
Orientation flag sets the layout to either horizontal or vertical
Orientation flag sets the layout to either horizontal or vertical
alignment.
*/
/*!
\var orientation B_HORIZONTAL
Horizontal alignment
*/
/*! \var orientation B_VERTICAL
/*!
\var orientation B_VERTICAL
Vertical alignment
*/
/*!
\enum button_width
Collection of flags that determine how wide to draw the buttons in a
BAlert dialog.
*/
/*!
\var button_width B_WIDTH_AS_USUAL
Set the width of each button based on the standard width.
*/
/*!
\var button_width B_WIDTH_FROM_WIDEST
Set the width of each button based on the width of the widest button.
*/
/*!
\var button_width B_WIDTH_FROM_LABEL
Set the width of each button to accomidate the width of the button's
label.
*/
docs/user/interface/Layout.dox
+14 -10
View File
@@ -1,17 +1,21 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Alex Wilson <[email protected]>
* Authors:
* Alex Wilson, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/Layout.h rev 38207
* /trunk/src/kits/interface/Layout.cpp rev 38207
* headers/os/interface/Layout.h rev 38207
* src/kits/interface/Layout.cpp rev 38207
*/
/*!
\file Layout.h
\ingroup interface
\ingroup layout
\ingroup libbe
\brief Defines the BLayout class.
*/
@@ -72,7 +76,7 @@ topLayout->AddItem(nestedLayoutWithView);
After this constructor has finished, this BLayout holds no
BLayoutItem&apos;s and does not have a target BView.
\warning Because a new BLayout does not have a target BView, calls to the
AddItem() and AddView() will fail methods will fail.
*/
@@ -147,7 +151,7 @@ topLayout->AddItem(nestedLayoutWithView);
this layout.
\a child is added to this BLayout&apos;s target view.
\returns The BLayoutItem created to represent \a child is, or \c NULL if
there was an error.
@@ -208,7 +212,7 @@ topLayout->AddItem(nestedLayoutWithView);
it represents from this BLayout&apos;s target view.
\param item The BLayoutItem to be removed
\warning \a item is not deleted, you must delete it manually, or add it to
another BLayout.
\warning \a item->View(), even when it is removed from the target view,
@@ -255,7 +259,7 @@ topLayout->AddItem(nestedLayoutWithView);
/*!
\fn int32 BLayout::IndexOfView(BView* child) const
\brief Get the index of \a child in this layout.
\note This finds the index of views added through BLayout::AddView(), not
the index of an item which represents \a child that was added through
BLayout::AddItem().
@@ -339,7 +343,7 @@ topLayout->AddItem(nestedLayoutWithView);
\brief If there is no layout currently ongoing, and \a force is \c false,
creates a new BLayoutContext and calls the DoLayout() method
of this BLayout and any BLayout s nested in this BLayout.
This method also guarantees that the owner view of this layout (as returned
by BLayout::Owner()) performs a layout as well (if it is suitable to do so).
docs/user/interface/LayoutBuilder.Group.dox
+7 -3
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -14,6 +14,9 @@
/*!
\file GroupLayoutBuilder.h
\ingroup interface
\ingroup layout
\ingroup libbe
\brief Provides the BLayoutBuilder::Group<> class.
*/
@@ -22,6 +25,7 @@
\class BLayoutBuilder::Group<>
\ingroup interface
\ingroup layout
\ingroup libbe
\brief BLayoutBuilder::Base subclass for building BGroupLayouts.
*/
@@ -347,7 +351,7 @@
/*!
\fn BView* BLayoutBuilder::Group<ParentBuilder>::View() const
\fn BView* BLayoutBuilder::Group<ParentBuilder>::View() const
\brief Get the BView this builder's BGroupLayout is attached to.
*/
@@ -361,7 +365,7 @@
/*!
\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::GetView(
\fn ThisBuilder& BLayoutBuilder::Group<ParentBuilder>::GetView(
BView** _view)
\brief Get the BView this builder's BGroupLayout is attached to.
\param[out] _view The BView this builder's BGroupLayout is attached to.
docs/user/interface/LayoutBuilder.dox
+18 -4
View File
@@ -1,13 +1,27 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Alex Wilson <[email protected]>
* Authors:
* Alex Wilson, [email protected]
*
* Corresponds to:
* headers/os/interface/LayoutBuilder.h rev 38207
* src/kits/interface/LayoutBuilder.cpp rev 38207
*/
/*! \class BLayoutBuilder::Base<>
/*!
\file LayoutBuilder.h
\ingroup interface
\ingroup layout
\ingroup libbe
\brief Defines the BLayoutBuilder templates.
*/
/*!
\class BLayoutBuilder::Base<>
\ingroup interface
\ingroup layout
\brief Base for all other layout builders in the BLayoutBuilder namespace.
docs/user/interface/LayoutItem.dox
+11 -8
View File
@@ -1,18 +1,22 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Alex Wilson <[email protected]>
* Authors:
* Alex Wilson, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/LayoutItem.h rev 38207
* /trunk/src/kits/interface/LayoutItem.cpp rev 38207
* headers/os/interface/LayoutItem.h rev 38207
* src/kits/interface/LayoutItem.cpp rev 38207
*/
/*!
\file LayoutItem.h
\brief Describes the BLayoutItem class
\ingroup interface
\ingroup layout
\ingroup libbe
\brief Describes the BLayoutItem class.
*/
@@ -21,7 +25,6 @@
\ingroup interface
\ingroup layout
\ingroup libbe
\brief Abstract class representing things that are positionable and
resizable by objects of the BLayout class.
@@ -98,7 +101,7 @@
\fn bool BLayoutItem::HasHeightForWidth()
\brief Returns whether or not this BLayoutItem&apos;s height constraints are
dependent on its width.
\note By default, this method returns \c false.
*/
docs/user/interface/Screen.dox
+11 -6
View File
@@ -1,19 +1,22 @@
/*
* Copyright 2011, Haiku inc.
* Distributed under the terms of the MIT Licence.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Authors:
* Stefano Ceccherini, [email protected]
* Axel Dörfler, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/Screen.h rev 42759
* /trunk/src/kits/interface/Screen.cpp rev 42759
* /trunk/headers/os/interface/Screen.h rev 42759
* /trunk/src/kits/interface/Screen.cpp rev 42759
*/
/*!
\file Screen.h
\ingroup interface
\ingroup libbe
\brief Defines the BScreen class and support structures.
*/
@@ -21,6 +24,7 @@
/*!
\class BScreen
\ingroup interface
\ingroup libbe
\brief The BScreen class provides methods to retrieve and change display
settings.
@@ -126,7 +130,8 @@
*/
/*! \fn color_space BScreen::ColorSpace()
/*!
\fn color_space BScreen::ColorSpace()
\brief Gets the color_space of the display.
\return \c B_CMAP8, \c B_RGB15, \c B_RGB32, or \c B_NO_COLOR_SPACE
docs/user/interface/TwoDimensionalLayout.dox
+9 -6
View File
@@ -1,17 +1,21 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Alex Wilson <[email protected]>
* Authors:
* Alex Wilson, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/TwoDimensionalLayout.h rev 38207
* /trunk/src/kits/interface/TwoDimensionalLayout.cpp rev 38207
* headers/os/interface/TwoDimensionalLayout.h rev 38207
* src/kits/interface/TwoDimensionalLayout.cpp rev 38207
*/
/*!
\file TwoDimensionalLayout.h
\ingroup interface
\ingroup layout
\ingroup libbe
\brief Defines the BTwoDimensionalLayout class.
*/
@@ -21,7 +25,6 @@
\ingroup interface
\ingroup layout
\ingroup libbe
\brief Abstract BLayout subclass arranging items within rows and columns.
This class manages all the tricky work of actually positioning/resizing
docs/user/interface/View.dox
+8 -6
View File
@@ -1,18 +1,21 @@
/*
* Copyright 2011, Haiku inc.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/interface/View.h rev 42794
* /trunk/src/kits/interface/View.cpp rev 42794
* headers/os/interface/View.h rev 42794
* src/kits/interface/View.cpp rev 42794
*/
/*!
\file View.h
\brief BView class definition and support enums.
\ingroup interface
\ingroup libbe
\brief BView class definition and support data structures.
*/
@@ -20,7 +23,6 @@
\class BView
\ingroup interface
\ingroup libbe
\brief View base class.
*/
docs/user/interface/_interface_intro.dox
+8 -8
View File
@@ -1,26 +1,26 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Alex Wilson <[email protected]>
* Authors:
* Alex Wilson, [email protected]
*/
/*!
\page interface_intro Introduction to the Interface Kit.
The Interface Kit holds all the classes you'll need to develop a GUI.
Building on the messaging facilities provided by the Application Kit,
the Inteface Kit can be used to create a responsive and attractive graphical
user interface.
the Interface Kit can be used to create a responsive and attractive
graphical user interface.
The most important class in the Interface Kit is the BView class, which
The most important class in the Interface Kit is the BView class, which
handles drawing and user interaction. Pointer and keyboard events are
processed in this class.
Another important class is the BWindow class, which holds BViews and makes
them visibile to the user. The BWindow class also handles BView focusing
them visible to the user. The BWindow class also handles BView focusing
and BMessage dispatching, among other things.
A new addition Haiku has added over the BeOS API is the Layout API, which
docs/user/interface/_layout_intro.dox
+15 -17
View File
@@ -1,9 +1,9 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Alex Wilson <[email protected]>
* Authors:
* Alex Wilson, [email protected]
*/
@@ -13,7 +13,8 @@
Haiku's Layout API is centered around the BLayoutItem and BLayout classes.
The BLayoutItem class represents thing that can be managed by a BLayout,
which is itself a BLayoutItem. Before we go any further, it is a good idea
to familiarize yourself with the different BLayouts available in Haiku:
to familiarize yourself with the different BLayout classes available in
Haiku:
\li BGroupLayout
\li BGridLayout
\li BCardLayout
@@ -21,14 +22,14 @@
You'll notice that BSplitView is not actually a BLayout, but a BView. The
BSplitView class uses a custom BLayout behind the scenes, but because it
must also be able to draw, a BView is required. Other BLayouts have
BViews that can be used for convenience.
must also be able to draw, a BView is required. Other BLayout objects have
BView objects that can be used for convenience.
\li BGroupLayout : BGroupView
\li BGridLayout : BGridView
\li BCardLayout : BTabView (also provides on-screen tabs)
Although it is not necessary to use these classes to make use of the
coresponding layouts, it does make things easier.
corresponding layouts, it does make things easier.
Once you have an understanding of what each BLayout does, you can start
designing an interface with them. Let's consider a very simple window,
@@ -39,8 +40,7 @@
So, let's review the BGroupLayout constructor:
\code
BGroupLayout(enum orientation orientation, float spacing
= B_USE_DEFAULT_SPACING)
BGroupLayout(enum orientation orientation, float spacing = B_USE_DEFAULT_SPACING)
\endcode
Because we only have one item in this layout, \c orientation and \c spacing
@@ -67,17 +67,17 @@ group->AddView(MakeStringView("Haiku rocks!"));
That does it! Now we've got a BWindow with a horizontal BGroupLayout holding
a single BView. However, if we want to ensure that our BStringView is always
centered in the window, we should give it an explict BAlignment. So that
centered in the window, we should give it an explicit BAlignment. So the
last line becomes:
\code
BLayoutItem* stringView = group->AddView(MakeStringView("Haiku rocks!"));
stringView->SetExplicitAlignment(BAlignment(B_ALIGN_HORIZONTAL_CENTER,
B_ALIGN_VERTICAL_CENTER);
B_ALIGN_VERTICAL_CENTER);
\endcode
Now our BStringView will always be right in the middle of the space
alloted to it, which at the moment is the whole of \c window.
allotted to it, which at the moment is the whole of \c window.
Now let's take things one step further, and add a BMenuBar into the mix.
@@ -118,8 +118,8 @@ group->AddItem(grid);
\endcode
You'll notice that we've added \c grid directly to \c group. This means that
any BViews we add to \c grid will become children of \c window, but will be
positioned by \c grid.
any BView objects we add to \c grid will become children of \c window, but
will be positioned by \c grid.
\code
grid->AddView(MakeSmallButton(), 0, 0);
@@ -128,7 +128,7 @@ grid->AddView(MakeBigButton(), 0, 1, 2, 1);
grid->AddView(MakeSmallButton(), 1, 2);
\endcode
Now we've got a nice grid of BButtons, let's go over it quickly:
Now we've got a nice grid of BButton objects, let's go over it quickly:
\li \c grid has two columns and three rows.
\li The cells (0, 0), (1, 0), and (1, 2) hold small buttons
\li The cells (0, 1) and (1, 1) hold a single button that spans both
@@ -156,6 +156,4 @@ BLayoutBuilder::Group<>(window, B_VERTICAL)
This is only one way that you could build this layout, but it is probably
the most succinct. Functionally, this is equivalent to all the previous
code in this introduction.
*/
docs/user/interface/BAlert_example.png → docs/user/interface/images/BAlert_example.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.8 KiB

After

Width:  |  Height:  |  Size: 8.8 KiB

docs/user/interface/BBox_example.png → docs/user/interface/images/BBox_example.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.7 KiB

After

Width:  |  Height:  |  Size: 3.7 KiB

docs/user/interface/BBox_with_checkbox.png → docs/user/interface/images/BBox_with_checkbox.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.4 KiB

After

Width:  |  Height:  |  Size: 9.4 KiB

docs/user/interface/BButton_example.png → docs/user/interface/images/BButton_example.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.7 KiB

After

Width:  |  Height:  |  Size: 4.7 KiB

docs/user/interface/BCheckBox_example.png → docs/user/interface/images/BCheckBox_example.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.0 KiB

After

Width:  |  Height:  |  Size: 6.0 KiB

docs/user/interface/BColorControl_example.png → docs/user/interface/images/BColorControl_example.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.0 KiB

After

Width:  |  Height:  |  Size: 6.0 KiB

docs/user/interface/BColorControl_example_256_colors.png → docs/user/interface/images/BColorControl_example_256_colors.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.4 KiB

After

Width:  |  Height:  |  Size: 6.4 KiB

docs/user/interface/BDragger_example.png → docs/user/interface/images/BDragger_example.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.3 KiB

After

Width:  |  Height:  |  Size: 5.3 KiB

docs/user/interface/B_FANCY_BORDER.png → docs/user/interface/images/B_FANCY_BORDER.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.4 KiB

After

Width:  |  Height:  |  Size: 3.4 KiB

docs/user/interface/B_PLAIN_BORDER.png → docs/user/interface/images/B_PLAIN_BORDER.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.3 KiB

After

Width:  |  Height:  |  Size: 3.3 KiB

docs/user/interface/layout_tips.dox
-1
View File
@@ -26,7 +26,6 @@
consider using one of the layout-related convenience classes (eg.
BGroupView for BGroupLayout).
\section layout_layout_tips BLayout Tips
\li It is generally better to add BViews and BLayoutItems directly to the
docs/user/locale/Catalog.dox
+6 -4
View File
@@ -1,20 +1,22 @@
/*
* Copyright 2011-2012 Haiku, Inc. All Rights Reserved.
* Copyright 2011-2012 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Axel Dörfler, [email protected]
* John Scipione, [email protected]
* Oliver Tappe, [email protected]
*
*
* Corresponds to:
* /trunk/headers/os/locale/Catalog.h hrev45083
* /trunk/src/kits/locale/Catalog.cpp hrev45083
* headers/os/locale/Catalog.h hrev45083
* src/kits/locale/Catalog.cpp hrev45083
*/
/*!
\file Catalog.h
\ingroup locale
\ingroup libbe
\brief Provides the BCatalog class.
*/
docs/user/locale/Collator.dox
+6 -3
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -8,13 +8,15 @@
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/locale/Collator.h rev 42274
* /trunk/src/kits/locale/Collator.cpp rev 42274
* headers/os/locale/Collator.h rev 42274
* src/kits/locale/Collator.cpp rev 42274
*/
/*!
\file Collator.h
\ingroup locale
\ingroup libbe
\brief Provides the BCollator class.
*/
@@ -22,6 +24,7 @@
/*!
\class BCollator
\ingroup locale
\ingroup libbe
\brief Class for handling locale-aware collation (sorting) of strings.
BCollator is designed to handle collation (sorting) of strings. Unlike
docs/user/locale/Country.dox
+17 -12
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -8,26 +8,31 @@
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/locale/Country.h rev 42274
* /trunk/src/kits/locale/Country.cpp rev 42274
* headers/os/locale/Country.h rev 42274
* src/kits/locale/Country.cpp rev 42274
*/
/*! \file Country.h
/*!
\file Country.h
\ingroup locale
\ingroup libbe
\brief BCountry class definition.
*/
/*! \class BCountry
/*!
\class BCountry
\ingroup locale
\brief Class representing a country
\ingroup libbe
\brief Class representing a country.
BCountry provides all the information about a particular country.
This includes the country flag (as an HVIF icon), the localized name
of the country, and the ISO country code.
BCountry provides information about a particular country including the
countries flag (as an HVIF icon), the localized name of the country,
and the ISO country code.
Date, time, and numer formatting also depends to some extent on the
language used, so they are found in the BLocale class instead.
Date, time, and number formatting also depends to some extent on the
language used so they are found in the BLocale class instead.
*/
@@ -85,7 +90,7 @@
The flag is stored in HVIF format so it can be rendered at any size and
color depth.
\param result The BBitmap to drag the flag into.
\param result The BBitmap object to draw the flag into.
\returns \c B_OK if the drawing was successful.
*/
docs/user/locale/DurationFormat.dox
+11 -3
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011, Haiku. All rights reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -7,11 +7,19 @@
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/locale/DurationFormat.h hrev45084
* /trunk/src/kits/locale/DurationFormat.cpp hrev45084
* headers/os/locale/DurationFormat.h hrev45084
* src/kits/locale/DurationFormat.cpp hrev45084
*/
/*!
\file DurationFormat.h
\ingroup locale
\ingroup libbe
\brief Contains BDurationFormat class, a time interval formatter.
*/
/*!
\class BDurationFormat
\ingroup locale
docs/user/locale/Locale.dox
+8 -4
View File
@@ -1,12 +1,12 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Axel Dörfler, [email protected].
* John Scipione, [email protected]
* Oliver Tappe, [email protected].
*
*
* Corresponds to:
* /trunk/headers/os/locale/Locale.h rev 43095
* /trunk/src/kits/locale/Locale.cpp rev 43095
@@ -15,12 +15,16 @@
/*!
\file Locale.h
\brief Provides the BLocale class.
\ingroup locale
\ingroup libbe
\brief Provides the BLocale class, the base class of the Locale Kit.
*/
/*! \class BLocale
/*!
\class BLocale
\ingroup locale
\ingroup libbe
\brief Class for representing a locale and its settings.
A locale is defined by the combination of a country and a language.
docs/user/locale/LocaleRoster.dox
+13 -4
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2003-2010, Haiku. All rights reserved.
* Copyright 2003-2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -8,15 +8,24 @@
* Oliver Tappe, [email protected]
*
* Corresponds to:
* /trunk/headers/os/locale/LocaleRoster.h rev 42274
* /trunk/src/kits/locale/LocaleRoster.cpp rev 42274
* headers/os/locale/LocaleRoster.h rev 42274
* src/kits/locale/LocaleRoster.cpp rev 42274
*/
/*!
\file LocaleRoster.h
\ingroup locale
\ingroup libbe
\brief Provides the BLocaleRoster class to access locale data.
*/
/*!
\class BLocaleRoster
\ingroup locale
\brief Main class for accessing the locale kit data
\ingroup libbe
\brief Main class for accessing the Locale Kit data.
The Locale Roster is the central part of the locale kit. It is a global
object (\c be_locale_roster) storing all the useful locale data. Other
docs/user/locale/TimeZone.dox
+13 -9
View File
@@ -1,26 +1,30 @@
/*
* Copyright 2011, Haiku inc.
* Distributed under the terms of the MIT Licence.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Adrien Destugues, [email protected]
* John Scipione, [email protected]
* Oliver Tappe, [email protected]
*
* Documentation by:
* Adrien Destugues <[email protected]>
* John Scipione <[email protected]>
* Oliver Tappe <[email protected]>
* Corresponds to:
* /trunk/headers/os/locale/TimeZone.h rev 42274
* /trunk/src/kits/locale/TimeZone.cpp rev 42274
* headers/os/locale/TimeZone.h rev 42274
* src/kits/locale/TimeZone.cpp rev 42274
*/
/*!
\file TimeZone.h
\brief Provides for the BTimeZone class.
\ingroup locale
\ingroup libbe
\brief Provides the BTimeZone class.
*/
/*!
\class BTimeZone
\ingroup locale
\ingroup libbe
\brief Provides information about time zones.
*/
docs/user/locale/UnicodeChar.dox
+47 -15
View File
@@ -1,20 +1,29 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the OpenBeOS License.
*
* Authors:
* Axel Dörfler <[email protected]>
* John Scipione <[email protected]>
*
* Axel Dörfler, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/locale/UnicodeChar.h rev 42274
* /trunk/src/kits/locale/UnicodeChar.cpp rev 42274
* headers/os/locale/UnicodeChar.h rev 42274
* src/kits/locale/UnicodeChar.cpp rev 42274
*/
/*!
\file UnicodeChar.h
\ingroup locale
\ingroup libbe
\brief Provides the BUnicodeChar class.
*/
/*!
\class BUnicodeChar
\ingroup locale
\ingroup libbe
\brief Management of all information about characters.
This class provide a set of tools for managing the whole set of characters
@@ -27,11 +36,12 @@
instantiate it. You can call one of the methods passing in the character
that you want to be examined.
Note all the function work with chars encoded in utf-32. This is not the
Note all the function work with chars encoded in UTF-32. This is not the
most usual way to handle characters, but it is the fastest. To convert an
utf-8 string to an utf-32 character use the FromUTF8() method.
UTF-8 string to an UTF-32 character use the FromUTF8() method.
*/
/*!
\fn static bool BUnicodeChar::IsAlpha(uint32 c)
\brief Determine if \a c is alphabetic.
@@ -40,6 +50,7 @@
alphabetic character.
*/
/*!
\fn static bool BUnicodeChar::IsAlNum(uint32 c)
\brief Determine if \a c is alphanumeric.
@@ -48,6 +59,7 @@
alphabetic or numeric character.
*/
/*!
\fn static bool BUnicodeChar::IsDigit(uint32 c)
\brief Determine if \a c is numeric.
@@ -56,6 +68,7 @@
number character.
*/
/*!
\fn static bool BUnicodeChar::IsHexDigit(uint32 c)
\brief Determine if \a c is a hexadecimal digit.
@@ -64,6 +77,7 @@
hexadecimal number character.
*/
/*!
\fn static bool BUnicodeChar::IsUpper(uint32 c)
\brief Determine if \a c is uppercase.
@@ -72,6 +86,7 @@
uppercase character.
*/
/*!
\fn static bool BUnicodeChar::IsLower(uint32 c)
\brief Determine if \a c is lowercase.
@@ -80,6 +95,7 @@
lowercase character.
*/
/*!
\fn static bool BUnicodeChar::IsSpace(uint32 c)
\brief Determine if \a c is a space.
@@ -94,6 +110,7 @@
\sa IsWhitespace()
*/
/*!
\fn static bool BUnicodeChar::IsWhitespace(uint32 c)
\brief Determine if \a c is whitespace.
@@ -107,6 +124,7 @@
\sa IsSpace()
*/
/*!
\fn static bool BUnicodeChar::IsControl(uint32 c)
\brief Determine if \a c is a control character.
@@ -120,6 +138,7 @@
\sa IsPrintable()
*/
/*!
\fn static bool BUnicodeChar::IsPunctuation(uint32 c)
\brief Determine if \a c is punctuation character.
@@ -128,6 +147,7 @@
punctuation character.
*/
/*!
\fn static bool BUnicodeChar::IsPrintable(uint32 c)
\brief Determine if \a c is printable.
@@ -140,6 +160,7 @@
\sa IsControl()
*/
/*!
\fn static bool BUnicodeChar::IsTitle(uint32 c)
\brief Determine if \a c is title case.
@@ -150,6 +171,7 @@
character.
*/
/*!
\fn static bool BUnicodeChar::IsDefined(uint32 c)
\brief Determine if \a c is defined.
@@ -160,6 +182,7 @@
\returns \c true if the specified unicode character is defined.
*/
/*!
\fn static bool BUnicodeChar::IsBase(uint32 c)
\brief Determine if \a c can be used with a diacritic.
@@ -170,6 +193,7 @@
form character that can be used with a diacritic.
*/
/*!
\fn static int8 BUnicodeChar::Type(uint32 c)
\brief Gets the type of a character.
@@ -177,6 +201,7 @@
\returns A member of the \c unicode_char_category enum.
*/
/*!
\fn uint32 BUnicodeChar::ToLower(uint32 c)
\brief Transforms \a c to lowercase.
@@ -184,6 +209,7 @@
\returns The lowercase version of the specified unicode character.
*/
/*!
\fn uint32 BUnicodeChar::ToUpper(uint32 c)
\brief Transforms \a c to uppercase.
@@ -191,6 +217,7 @@
\returns The uppercase version of the specified unicode character.
*/
/*!
\fn uint32 BUnicodeChar::ToTitle(uint32 c)
\brief Transforms \a c to title case.
@@ -198,6 +225,7 @@
\returns The title case version of the specified unicode character.
*/
/*!
\fn int32 BUnicodeChar::DigitValue(uint32 c)
\brief Gets the numeric value \a c.
@@ -205,33 +233,37 @@
\returns The numeric version of the specified unicode character.
*/
/*!
\fn void BUnicodeChar::ToUTF8(uint32 c, char **out)
\brief Transform a character to utf-8 encoding.
\brief Transform a character to UTF-8 encoding.
\returns The utf-8 encoding of the specified unicode character.
\returns The UTF-8 encoding of the specified unicode character.
*/
/*!
\fn uint32 BUnicodeChar::FromUTF8(const char **in)
\brief Transform a utf-8 string to an utf-32 character.
\brief Transform a UTF-8 string to an UTF-32 character.
If the string contains multiple characters, only the fist one is used.
This function updates the in pointer so that it points on the next
character for the following call.
\returns The utf-32 encoded version of \a in.
\returns The UTF-32 encoded version of \a in.
*/
/*!
\fn size_t BUnicodeChar::UTF8StringLength(const char *str)
\brief Counts the characters in the given \c NUL terminated string.
\returns the number of utf-8 characters in the \c NUL terminated string.
\returns the number of UTF-8 characters in the \c NUL terminated string.
\sa BString::CountChars()
*/
/*!
\fn size_t BUnicodeChar::UTF8StringLength(const char *str, size_t maxLength)
\brief Counts the characters in the given string up to \a maxLength
@@ -240,6 +272,6 @@
The string does not need to be \c NUL terminated if you specify a
\a maxLength that is shorter than the maximum length of the string.
\returns the number of utf-8 characters in the \c NUL terminated string
\returns the number of UTF-8 characters in the \c NUL terminated string
up to \a maxLength characters.
*/
docs/user/media/Buffer.dox
+9 -4
View File
@@ -1,24 +1,28 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/media/Buffer.h rev 42274
* /trunk/src/kits/media/Buffer.cpp rev 42274
* headers/os/media/Buffer.h rev 42274
* src/kits/media/Buffer.cpp rev 42274
*/
/*!
\file Buffer.h
\ingroup media
\ingroup libbe
\brief Defines the buffer_clone_info struct and BBuffer class.
*/
/*!
\struct buffer_clone_info
\ingroup media
\ingroup libbe
\brief A struct that stores where in memory a BBuffer object is in memory
as well as the buffer flags.
*/
@@ -27,8 +31,9 @@
/*!
\class BBuffer
\ingroup media
\ingroup libbe
\brief A reference to a chunk of memory useful for sharing media data
between applications and nodes.
between applications and nodes.
*/
docs/user/media/FileInterface.dox
+5 -3
View File
@@ -1,18 +1,20 @@
/*
* Copyright 2012 Haiku, Inc. All Rights Reserved.
* Copyright 2012 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/media/FileInterface.h hrev45081
* /trunk/src/kits/media/FileInterface.cpp hrev45081
* headers/os/media/FileInterface.h hrev45081
* src/kits/media/FileInterface.cpp hrev45081
*/
/*!
\file FileInterface.h
\ingroup media
\ingroup libbe
\brief Provides BFileInterface abstract class.
*/
docs/user/midi2/Midi2Defs.dox
+309 -245
View File
@@ -1,280 +1,344 @@
/*!
\file Midi2Defs.h
\brief Some definitions to define raw MIDI events.
\ingroup midi2
\file Midi2Defs.h
\ingroup midi2
\ingroup libbe
\brief Some definitions to define raw MIDI events.
*/
/*!
\name Channel Message Masks
\brief Some definitions to define the raw MIDI events.
\name Channel Message Masks
\brief Some definitions to define the raw MIDI events.
The default implementation of BMidiLocalConsumer::Data() uses these constants
to determine which event has been passed on. If you override that method, you
may use the constants yourself.
The default implementation of BMidiLocalConsumer::Data() uses these
constants to determine which event has been passed on. If you override
that method, you may use the constants yourself.
*/
//! @{
/*!
\var B_NOTE_OFF
*/
/*!
\var B_NOTE_ON
*/
/*!
\var B_KEY_PRESSURE
*/
/*!
\var B_CONTROL_CHANGE
*/
/*!
\var B_PROGRAM_CHANGE
*/
/*!
\var B_CHANNEL_PRESSURE
*/
/*!
\var B_PITCH_BEND
*/
//! @}
/*!
\name System Messages
\brief Some definitions to define the raw MIDI system messages.
The default implementation of BMidiLocalConsumer::Data() uses these constants
to determine which event system message has been passed on. See
BMidiLocalProducer::SpraySystemCommon() and BMidiLocalProducer::SpraySystemRealTime()
for more details on how and when to use these messages.
*/
//! @{
/*!
\var B_SYS_EX_START
*/
/*!
\var B_MIDI_TIME_CODE
*/
/*!
\var B_SONG_POSITION
*/
/*!
\var B_SONG_SELECT
*/
/*!
\var B_CABLE_MESSAGE
*/
/*!
\var B_TUNE_REQUEST
*/
/*!
\var B_SYS_EX_END
*/
/*!
\var B_TIMING_CLOCK
*/
/*!
\var B_START
*/
/*!
\var B_CONTINUE
*/
/*!
\var B_STOP
*/
/*!
\var B_ACTIVE_SENSING
*/
/*!
\var B_SYSTEM_RESET
*/
//! @}
/*!
\name Controller Numbers
\brief Constants that represent specific controller messages.
These constants can be used in BMidiLocalProducer::SprayControlChange()
and BMidiLocalConsumer::ControlChange(). These constants represent the
MIDI specification.
*/
//! @{
/*!
\var B_NOTE_OFF
*/
/*!
\var B_MODULATION
\var B_NOTE_ON
*/
/*!
\var B_BREATH_CONTROLLER
\var B_KEY_PRESSURE
*/
/*!
\var B_FOOT_CONTROLLER
\var B_CONTROL_CHANGE
*/
/*!
\var B_PORTAMENTO_TIME
\var B_PROGRAM_CHANGE
*/
/*!
\var B_DATA_ENTRY
\var B_CHANNEL_PRESSURE
*/
/*!
\var B_MAIN_VOLUME
*/
/*!
\var B_MIDI_BALANCE
*/
/*!
\var B_PAN
*/
/*!
\var B_EXPRESSION_CTRL
*/
/*!
\var B_GENERAL_CTRL_1
*/
/*!
\var B_GENERAL_CTRL_2
*/
/*!
\var B_GENERAL_CTRL_3
*/
/*!
\var B_GENERAL_CTRL_4
*/
/*!
\var B_SUSTAIN_PEDAL
*/
/*!
\var B_PORTAMENTO
*/
/*!
\var B_SOSTENUTO
*/
/*!
\var B_SOFT_PEDAL
*/
/*!
\var B_HOLD_2
*/
/*!
\var B_GENERAL_CTRL_5
*/
/*!
\var B_GENERAL_CTRL_6
*/
/*!
\var B_TEMPO_CHANGE
*/
/*!
\var B_GENERAL_CTRL_7
*/
/*!
\var B_GENERAL_CTRL_8
*/
/*!
\var B_EFFECTS_DEPTH
*/
/*!
\var B_TREMOLO_DEPTH
*/
/*!
\var B_CHORUS_DEPTH
*/
/*!
\var B_CELESTE_DEPTH
*/
/*!
\var B_PHASER_DEPTH
*/
/*!
\var B_DATA_INCREMENT
*/
/*!
\var B_DATA_DECREMENT
*/
/*!
\var B_RESET_ALL_CONTROLLERS
*/
/*!
\var B_LOCAL_CONTROL
*/
/*!
\var B_ALL_NOTES_OFF
*/
/*!
\var B_OMNI_MODE_OFF
*/
/*!
\var B_OMNI_MODE_ON
*/
/*!
\var B_MONO_MODE_ON
*/
/*!
\var B_POLY_MODE_ON
\var B_PITCH_BEND
*/
//! @}
/*!
\name System Messages
\brief Some definitions to define the raw MIDI system messages.
The default implementation of BMidiLocalConsumer::Data() uses these
constants to determine which event system message has been passed on.
See BMidiLocalProducer::SpraySystemCommon() and
BMidiLocalProducer::SpraySystemRealTime() for more details on how and
when to use these messages.
*/
//! @{
/*!
\var B_SYS_EX_START
*/
/*!
\var B_MIDI_TIME_CODE
*/
/*!
\var B_SONG_POSITION
*/
/*!
\var B_SONG_SELECT
*/
/*!
\var B_CABLE_MESSAGE
*/
/*!
\var B_TUNE_REQUEST
*/
/*!
\var B_SYS_EX_END
*/
/*!
\var B_TIMING_CLOCK
*/
/*!
\var B_START
*/
/*!
\var B_CONTINUE
*/
/*!
\var B_STOP
*/
/*!
\var B_ACTIVE_SENSING
*/
/*!
\var B_SYSTEM_RESET
*/
//! @}
/*!
\name Controller Numbers
\brief Constants that represent specific controller messages.
These constants can be used in BMidiLocalProducer::SprayControlChange()
and BMidiLocalConsumer::ControlChange(). These constants represent the
MIDI specification.
*/
//! @{
*/
/*!
\var B_MODULATION
*/
/*!
\var B_BREATH_CONTROLLER
*/
/*!
\var B_FOOT_CONTROLLER
*/
/*!
\var B_PORTAMENTO_TIME
*/
/*!
\var B_DATA_ENTRY
*/
/*!
\var B_MAIN_VOLUME
*/
/*!
\var B_MIDI_BALANCE
*/
/*!
\var B_PAN
*/
/*!
\var B_EXPRESSION_CTRL
*/
/*!
\var B_GENERAL_CTRL_1
*/
/*!
\var B_GENERAL_CTRL_2
*/
/*!
\var B_GENERAL_CTRL_3
*/
/*!
\var B_GENERAL_CTRL_4
*/
/*!
\var B_SUSTAIN_PEDAL
*/
/*!
\var B_PORTAMENTO
*/
/*!
\var B_SOSTENUTO
*/
/*!
\var B_SOFT_PEDAL
*/
/*!
\var B_HOLD_2
*/
/*!
\var B_GENERAL_CTRL_5
*/
/*!
\var B_GENERAL_CTRL_6
*/
/*!
\var B_TEMPO_CHANGE
*/
/*!
\var B_GENERAL_CTRL_7
*/
/*!
\var B_GENERAL_CTRL_8
*/
/*!
\var B_EFFECTS_DEPTH
*/
/*!
\var B_TREMOLO_DEPTH
*/
/*!
\var B_CHORUS_DEPTH
*/
/*!
\var B_CELESTE_DEPTH
*/
/*!
\var B_PHASER_DEPTH
*/
/*!
\var B_DATA_INCREMENT
*/
/*!
\var B_DATA_DECREMENT
*/
/*!
\var B_RESET_ALL_CONTROLLERS
*/
/*!
\var B_LOCAL_CONTROL
*/
/*!
\var B_ALL_NOTES_OFF
*/
/*!
\var B_OMNI_MODE_OFF
*/
/*!
\var B_OMNI_MODE_ON
*/
/*!
\var B_MONO_MODE_ON
*/
/*!
\var B_POLY_MODE_ON
*/
//! @}
docs/user/midi2/MidiConsumer.dox
+323
View File
@@ -0,0 +1,323 @@
/*!
\file MidiConsumer.h
\ingroup midi2
\ingroup libbe
\brief Defines consumer classes for the MIDI Kit.
*/
/*!
\class BMidiConsumer MidiConsumer.h
\ingroup midi2
\ingroup libmidi2
\ingroup libbe
\brief Receives MIDI events from a producer
A consumer is an object that knows how to deal with incoming MIDI events. A
consumer can be connected to multiple producers at the same time. There is no
way to find out which producers are connected to this consumer just by looking
at the BMidiConsumer object; you will have to consult BMidiRoster for that.
A BMidiConsumer either represents a local consumer, i.e. a class extending from
BMidiLocalConsumer, or is a proxy for a remote object published by another app.
*/
/*!
\fn bigtime_t BMidiConsumer::Latency() const
\brief Returns the latency of this consumer
The latency is measured in microseconds. Producers should attempt to get MIDI
events to this consumer by <I>(when - latency)</I>. You do this by subtracting
the latency from the performance time when you spray the events (provided that
you spray these events ahead of time, of course).
You cannot <I>set</I> the latency on a BMidiConsumer, only on a
BMidiLocalConsumer.
The latency issue gets slightly more complicated when multiple endpoints are
chained together, as in the following picture:
\verbatim
+-------+ +-------------+ +-------+
| | | | | |
| prodA |---->| consB prodB |---->| consC |
| | | | | |
+-------+ +-------------+ +-------+
appA appB (filter) appC
\endverbatim
Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply
reports 100ms, then prodA will schedule its events for (t - 100), which is
really 200ms too late. (Of course, producers send out their events as soon as
possible, so depending on the load of the system, everything may work out just
fine.)
ConsB should report the latency of the consumer that is hooked up to its
output, consC, in addition to its own latency. In other words, the full
downstream latency. So, the reported latency in this case would be 300ms. This
also means that appB should change the latency of consB when prodB makes or
breaks a connection, and when consC reports a latency change. (If multiple
consumers are connected to prodB, you should take the slowest one.)
Unfortunately, the Midi Kit provides no easy mechanism for doing any of this,
so you are on your own here.
*/
/*!
\class BMidiLocalConsumer MidiConsumer.h
\ingroup midi2
\ingroup libmidi2
\ingroup libbe
\brief A consumer endpoint that is created by your own application.
If you want to create a consumer that reacts to MIDI events, you should
subclass BMidiLocalConsumer.
Each local consumer has its own thread that receives and dispatches the MIDI
events. Whenever MIDI data arrives, the Data() hook passes the MIDI event on to
a more specific hook function: NoteOn(), NoteOff(), SystemExclusive(), and so
on. Calls to these hook functions are serialized -- they will never have to be
re-entrant. They also should not be called from outside the thread that is
invoking them.
Your subclass can override any of the MIDI event hooks. BMidiLocalConsumer
doesn't provide default implementations for them, so you don't have to call a
hook's default implementation if you override it. For complete control, you can
also override Data().
Most hook functions take a channel argument. Even though MIDI channels are
really numbered 1 through 16, the hook functions work with channels 0 through
15. The performance time for the event is specified in microseconds relative to
the system time base. A performance time that is 0 (or really any time in the
past) means "play as soon as possible". See the \ref midi2time "introduction"
for more information about timing and consumers.
The thread driving the consumer's events is a very high priority real time
thread. Events should be handled as quickly as possible (not counting
snoozing). If non-time-critical computation is needed it may be wise to queue
events up for a lower priority thread to handle them external to the main event
thread.
*/
/*!
\fn BMidiLocalConsumer::BMidiLocalConsumer(const char *name = NULL)
\brief Creates a new local consumer endpoint
The new endpoint is not visible to other applications until you Register() it.
You can tell the constructor what the name of the new consumer will be. If you
pass NULL (or use the default argument), then the consumer's name will be an
empty string. It won't be NULL, since endpoint names cannot be NULL.
There is no guarantee that the endpoint will be successfully created. For
example, the Midi Server may not be running. Therefore, you should always call
IsValid() after creating a new endpoint to make sure that everything went okay.
If not, Release() the object to reclaim memory and abort gracefully.
\code
MyConsumer* cons = new MyConsumer(...);
if (!cons->IsValid())
{
cons->Release();
...exit gracefully...
}
\endcode
*/
/*!
\fn void BMidiLocalConsumer::SetLatency(bigtime_t latency)
\brief Changes the published latency of the consumer.
\sa Latency()
*/
/*!
\fn int32 BMidiLocalConsumer::GetProducerID()
\brief Returns the ID of the producer that most recently sent a MIDI event to
this consumer.
You can call this from one of the hooks to determine which producer the event
came from.
*/
/*!
\fn void BMidiLocalConsumer::SetTimeout(bigtime_t when, void* data)
\brief Requests that the Timeout() hook will be called at some point.
This method asks the consumer thread to call the Timeout() hook as soon as
possible after the timeout expires. For every call to SetTimeout(), the
Timeout() hook is only called once. Note: the term "timeout" may be a little
misleading; the hook will <I>always</I> be called, even if events are received
in the mean time. Apparently, this facility is handy for dealing with early
events.
Note that the event thread blocks on the consumer's port as long as no events
arrive. By default no timeout is set, and as a result the thread blocks
forever. Your call to SetTimeout() doesn't change this. The new timeout value
will go into effect the next time the thread tries to read from the port, i.e.
after the first event has been received. If no event ever comes in, the
Timeout() hook will never be called. This also means that you cannot cancel a
timeout once you have set it. To repeat, calling SetTimeout() only takes effect
after at least one new event has been received.
\param when An absolute time that's measured against the system clock.
\param data A pointer to a "cookie" that you can pass along to Timeout(). The
data is not copied, so you must ensure that the pointer remains valid until
Timeout() is called. You typically delete the data inside Timeout().
*/
/*!
\fn void BMidiLocalConsumer::Timeout(void* data)
\brief Hook function that is called per your own request.
\sa SetTimeout()
*/
/*!
\fn void BMidiLocalConsumer::Data(uchar* data, size_t length, bool atomic,
bigtime_t time)
\brief Invoked when raw MIDI is received.
What the default implementation of Data() does depends on the value of atomic.
If atomic is true, the data received comprises a single MIDI event; i.e. one
status byte followed by the appropriate number of data bytes and nothing else.
In this case, Data() calls the event-specific hook function that corresponds to
that status byte. This optimization is used by the Midi Kit to allow faster
dispatch of events generated by the specific Spray functions from
BMidiLocalProducer.
If atomic is false, Data() ignores the MIDI event. If you want a consumer to
handle non-atomic events, you have to override Data() and program this
yourself. In that case, you probably also want to call the default
implementation to handle the "normal" MIDI events.
Data() is rarely overridden, but you can override it if you want to. If you do,
remember that the data buffer is owned by the Midi Kit. Do not attempt to
modify or free it, lest you wish to be laughed at by other developers.
\param data the MIDI event data
\param length byte size of the data buffer
\param atomic whether the data buffer contains a single complete MIDI event
\param time the requested performance time of the event
\sa BMidiLocalProducer::SprayData()
*/
/*!
\fn void BMidiLocalConsumer::NoteOff(uchar channel, uchar note,
uchar velocity, bigtime_t time)
\brief Invoked when a Note Off event is received.
\sa BMidiLocalProducer::SprayNoteOff()
*/
/*!
\fn void BMidiLocalConsumer::NoteOn(uchar channel, uchar note,
uchar velocity, bigtime_t time)
\brief Invoked when a Note On event is received.
\sa BMidiLocalProducer::SprayNoteOn()
*/
/*!
\fn void BMidiLocalConsumer::KeyPressure(uchar channel, uchar note,
uchar pressure, bigtime_t time)
\brief Invoked when a Polyphonic Pressure (Aftertouch) event is received.
\sa BMidiLocalProducer::SprayKeyPressure()
*/
/*!
\fn void BMidiLocalConsumer::ControlChange(uchar channel,
uchar controlNumber, uchar controlValue, bigtime_t time)
\brief Invoked when a Controller Change event is received.
\sa BMidiLocalProducer::SprayControlChange()
*/
/*!
\fn void BMidiLocalConsumer::ProgramChange(uchar channel,
uchar programNumber, bigtime_t time)
\brief Invoked when a Program Change event is received.
\sa BMidiLocalProducer::SprayProgramChange()
*/
/*!
\fn void BMidiLocalConsumer::ChannelPressure(uchar channel,
uchar pressure, bigtime_t time)
\brief Invoked when a Channel Pressure event is received.
\sa BMidiLocalProducer::SprayChannelPressure()
*/
/*!
\fn void BMidiLocalConsumer::PitchBend(uchar channel, uchar lsb,
uchar msb, bigtime_t time)
\brief Invoked when a Pitch Bend event is received.
\sa BMidiLocalProducer::SprayPitchBend()
*/
/*!
\fn void BMidiLocalConsumer::SystemExclusive(void* data, size_t length,
bigtime_t time)
\brief Invoked when a System Exclusive event is received.
The data does not include the sysex start and end control bytes
(0xF0 and 0xF7), only the payload of the sysex message.
The data belongs to the Midi Kit and is only valid for the duration of
this event. You may not modify or free it.
\sa BMidiLocalProducer::SpraySystemExclusive()
*/
/*!
\fn void BMidiLocalConsumer::SystemCommon(uchar status, uchar data1,
uchar data2, bigtime_t time)
\brief Invoked when a System Common event is received.
Not all data bytes are used for all common events. Unused bytes are
set to 0.
\sa BMidiLocalProducer::SpraySystemCommon()
*/
/*!
\fn void BMidiLocalConsumer::SystemRealTime(uchar status, bigtime_t time)
\brief Invoked when a Real Time event is received.
\sa BMidiLocalProducer::SpraySystemRealTime()
*/
/*!
\fn void BMidiLocalConsumer::TempoChange(int32 beatsPerMinute, bigtime_t time)
\brief Invoked when a Tempo Change event is received
\sa BMidiLocalProducer::SprayTempoChange()
*/
/*!
\fn void BMidiLocalConsumer::AllNotesOff(bool justChannel, bigtime_t time)
\brief Not used.
*/
docs/user/midi2/MidiEndpoint.dox
+322
View File
@@ -0,0 +1,322 @@
/*!
\file MidiEndpoint.h
\ingroup midi2
\ingroup libbe
\brief Defines the Baseclass of all MIDI consumers and producers.
*/
/*!
\class BMidiEndpoint
\ingroup midi2
\ingroup libmidi2
\ingroup libbe
\brief 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 \link BMidiProducer::Disconnect() Disconnect() \endlink
and Unregister() the object yourself and not rely on the destructor to
do this.
*/
/*!
\fn const char* BMidiEndpoint::Name() const
\brief Returns the name of the endpoint.
The function never returns NULL. If you created a local endpoint by
passing a \c NULL name into its constructor (or passing no name,
which is the same thing), then Name() will return an empty string,
not \c NULL.
\sa SetName()
*/
/*!
\fn void BMidiEndpoint::SetName(const char* name)
\brief 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.
\param name The new name. If you pass \c NULL the name won't be changed.
\sa Name()
*/
/*!
\fn int32 BMidiEndpoint::ID() const
\brief 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 <b>not</b> valid IDs.
*/
/*!
\fn bool BMidiEndpoint::IsProducer() const
\brief Determines whether this endpoint is a BMidiProducer
If it is, you can use a dynamic_cast to convert this object into a
producer:
\code
if (endp->IsProducer())
{
BMidiProducer* prod = dynamic_cast<BMidiProducer*>(endp);
....
}
\endcode
*/
/*!
\fn bool BMidiEndpoint::IsConsumer() const
\brief Determines whether this endpoint is a BMidiConsumer
If it is, you can use a dynamic_cast to convert this object into a consumer:
\code
if (endp->IsConsumer())
{
BMidiConsumer* cons = dynamic_cast<BMidiConsumer*>(endp);
....
}
\endcode
*/
/*!
\fn bool BMidiEndpoint::IsRemote() const
\brief 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.
*/
/*!
\fn bool BMidiEndpoint::IsLocal() const
\brief 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.
*/
/*!
\fn bool BMidiEndpoint::IsPersistent() const
\brief Not used.
The purpose of this function is unclear, and as a result it doesn't do
anything in the Haiku Midi Kit implementation.
\return \c false always.
*/
/*!
\fn bool BMidiEndpoint::IsValid() const
\brief 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 \c false.
*/
/*!
\fn status_t BMidiEndpoint::Acquire()
\brief 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.
\return Always returns B_OK
\sa Release()
*/
/*!
\fn status_t BMidiEndpoint::Release()
\brief Decrements the endpoint's reference count.
\return Always returns B_OK
\sa Acquire()
*/
/*!
\fn status_t BMidiEndpoint::Register()
\brief 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 \link BMidiRoster::StartWatching() watching \endlink, you will
<b>not</b> receive notifications for any local endpoints you register or
unregister. Of course, other applications <I>will</I> 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 \c B_ERROR) if
something went wrong.
\sa Unregister()
*/
/*!
\fn status_t BMidiEndpoint::Unregister()
\brief Hides the endpoint from the roster/
\sa Register()
*/
/*!
\fn status_t BMidiEndpoint::SetProperties(const BMessage* props)
\brief 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:
\code
BMessage props;
if (endpoint->GetProperties(&props) == B_OK)
{
...add data to the message...
endpoint->SetProperties(&props);
}
\endcode
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.
<TABLE BORDER="1">
<TR><TD>property</TD><TD>Vector icon (raw data)</TD></TR>
<TR><TD>field name</TD><TD>"icon"</TD></TR>
<TR><TD>field type</TD><TD>'VICN'</TD></TR>
</TABLE>
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.
<TABLE BORDER="1">
<TR><TD>property</TD><TD>Large (32x32) icon</TD></TR>
<TR><TD>field name</TD><TD>"be:large_icon"</TD></TR>
<TR><TD>field type</TD><TD>'ICON'</TD></TR>
</TABLE>
<TABLE BORDER="1">
<TR><TD>property</TD><TD>Small (16x16) icon</TD></TR>
<TR><TD>field name</TD><TD>"be:mini_icon"</TD></TR>
<TR><TD>field type</TD><TD>'MICN'</TD></TR>
</TABLE>
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.
\sa GetProperties()
*/
/*!
\fn status_t BMidiEndpoint::GetProperties(BMessage* props) const
\brief Reads the properties of the endpoint
Usage example:
\code
BMessage props;
if (endpoint->GetProperties(&props) == B_OK)
{
...examine the contents of the message...
}
\endcode
Note that GetProperties() overwrites the contents of your BMessage.
\sa SetProperties()
*/
docs/user/midi2/MidiProducer.dox
+359
View File
@@ -0,0 +1,359 @@
/*!
\file MidiProducer.h
\ingroup midi2
\ingroup libbe
\brief Defines producer classes for the MIDI Kit.
*/
/*!
\class BMidiProducer MidiProducer.h
\ingroup midi2
\ingroup libmidi2
\ingroup libbe
\brief Streams MIDI events to connected consumers.
A producer is an object that generate a stream of MIDI events. Each
producer has a list of BMidiConsumer objects to which it is connected,
and may be asked to connect to or disconnect from a BMidiConsumer. A
producer can spray its events to multiple consumers at the same time.
A BMidiProducer either represents a local producer, i.e. a class extending
from BMidiLocalProducer, or is a proxy for a remote object published by
another app.
*/
/*!
\fn status_t BMidiProducer::Connect(BMidiConsumer* cons)
\brief Connects a consumer to this producer.
Establishes a connection between this producer and the specified consumer
endpoint. From now on, any events that this producer sprays will be sent
to that consumer. You may connect multiple consumers to a producer.
\return B_OK on success, or an error code when the connection could not be
established. If the consumer is a proxy for a remote object and that
object no longer exists, Connect() returns B_ERROR. It also returns
\c B_ERROR if you try to connect the same producer and consumer more
than once.
\sa Disconnect()
*/
/*!
\fn status_t BMidiProducer::Disconnect(BMidiConsumer* cons)
\brief Disconnects a consumer from this producer.
Terminates the connection between this producer and the specified consumer
endpoint. From now on, any events that this producer sprays no longer go
to that consumer.
\return B_OK on success, or an error code if there was no connection to break
\sa Connect()
*/
/*!
\fn bool BMidiProducer::IsConnected(BMidiConsumer* cons) const
\brief Determines whether a consumer is connected to this producer.
\sa Connect()
\sa Disconnect()
*/
/*!
\fn BList* BMidiProducer::Connections() const
\brief Returns a list with all connected consumers.
Returns a BList with pointers to BMidiEndpoint objects for all consumers
that are connected to this producer. You can examine the contents of the
list as follows:
\code
BList* list = prod->Connections();
for (int32 t = 0; t < list->CountItems(); ++t)
{
BMidiEndpoint* endp = (BMidiEndpoint*) list->ItemAt(t);
...do stuff...
endp->Release(); // yes, here too!
}
delete list;
\endcode
Every time you call this function, a new BList is allocated. The caller
(that is you) is responsible for freeing this list. The BMidiEndpoint
objects in the list have their reference counts bumped, so you need to
Release() them before you delete the list or they will go all leaky on
you.
*/
/*!
\class BMidiLocalProducer MidiProducer.h
\ingroup midi2
\ingroup libmidi2
\ingroup libbe
\brief A producer endpoint that is created by your own application.
You create a BMidiLocalProducer if you want your application to send MIDI
events. You use the various spray functions to send events to all connected
consumers. If no consumers are connected to the producer, any calls to the
spray functions are ignored.
Most spray functions accept a channel argument. Even though MIDI channels are
really numbered 1 through 16, the spray functions work with channels 0 through
15. You can also specify the performance time for the event using the time
argument. Specify 0 (or any time in the past) to perform the event "now", i.e.
as soon as possible. You can also schedule events to be performed in the
future, by passing a time such as system_time() + 5000000, which means 5
seconds from now.
Unlike BMidiLocalConsumer, which should be subclassed almost always, you hardly
ever need to derive a class from BMidiLocalProducer. The only reason for
subclassing is when you need to know when the producer gets connected or
disconnected.
Also unlike consumers, local producers have no thread of control directly
associated with them. If you want to send out the MIDI events from a different
thread, you will have to create one yourself.
*/
/*!
\fn BMidiLocalProducer::BMidiLocalProducer(const char *name = NULL)
\brief Creates a new local producer endpoint.
The new endpoint is not visible to other applications until you Register() it.
You can tell the constructor what the name of the new producer will be. If you
pass NULL (or use the default argument), then the producer's name will be an
empty string. It won't be NULL, since endpoint names cannot be NULL.
There is no guarantee that the endpoint will be successfully created. For
example, the Midi Server may not be running. Therefore, you should always call
IsValid() after creating a new endpoint to make sure that everything went okay.
If not, Release() the object to reclaim memory and abort gracefully.
\code
BMidiLocalProducer* prod = new BMidiLocalProducer(...);
if (!prod->IsValid())
{
prod->Release();
...exit gracefully...
}
\endcode
*/
/*!
\fn void BMidiLocalProducer::Connected(BMidiConsumer* cons)
\brief Invoked when a new consumer is connected to this producer
Although typical notifications (i.e. from BMidiRoster's "watching" facility)
are only sent if it is some other app that is performing the operation,
Connected() is also called if you are making the connection yourself.
If you override this hook, you don't have to call the default implementation,
because that does nothing.
\param cons The newly connected consumer. The reference count of the
consumer object is not increased, so you should not Release() it.
However, if you want to keep track of the consumer beyond this
function, you should first Acquire() it, and Release() it when you
are done.
\sa Disconnected()
*/
/*!
\fn void BMidiLocalProducer::Disconnected(BMidiConsumer* cons)
\brief Invoked when a consumer is disconnected from this producer.
\sa Connected()
*/
/*!
\fn void BMidiLocalProducer::SprayData(void* data, size_t length,
bool atomic = false, bigtime_t time = 0) const
\brief Sends raw MIDI data downstream to all connected consumers.
Typically you won't have to call SprayData(); the other spray functions
will do just fine. If you do call it, remember that you retain ownership
of the data and that you are responsible for freeing it at some point.
(Even though data is not declared const, the function does not change it.)
With atomic set to false, you can send a MIDI message in segments (perhaps
for a large sysex dump). However, when you do this, you are on your own.
The Midi Kit only tags the data as being non-atomic, but offers no]
additional support.
The default implementation of BMidiLocalConsumer completely ignores such
events. To handle non-atomic MIDI data, you should override the
BMidiLocalConsumer::Data() hook and process the MIDI event yourself. All of
BMidiLocalProducer's other spray functions always send atomic data.
\param data the MIDI event data.
\param length byte size of the data buffer.
\param atomic whether the data buffer contains a single complete
MIDI event.
\param time the required performance time of the event.
\sa BMidiLocalConsumer::Data()
*/
/*!
\fn void BMidiLocalProducer::SprayNoteOff(uchar channel, uchar note,
uchar velocity, bigtime_t time = 0) const
\brief Sends a Note Off event to all connected consumers.
\sa BMidiLocalConsumer::NoteOff()
*/
/*!
\fn void BMidiLocalProducer::SprayNoteOn(uchar channel, uchar note,
uchar velocity, bigtime_t time = 0) const
\brief Sends a Note On event to all connected consumers.
\sa BMidiLocalConsumer::NoteOn()
*/
/*!
\fn void BMidiLocalProducer::SprayKeyPressure(uchar channel, uchar note,
uchar pressure, bigtime_t time = 0) const
\brief Sends a Polyphonic Pressure (Aftertouch) event to all connected
consumers.
\sa BMidiLocalConsumer::KeyPressure()
*/
/*!
\fn void BMidiLocalProducer::SprayControlChange(uchar channel,
uchar controlNumber, uchar controlValue, bigtime_t time = 0) const
\brief Sends a Controller Change event to all connected consumers.
\sa Midi2Defs.h
\sa BMidiLocalConsumer::ControlChange()
*/
/*!
\fn void BMidiLocalProducer::SprayProgramChange(uchar channel,
uchar programNumber, bigtime_t time = 0) const
\brief Sends a Program Change event to all connected consumers.
\sa BMidiLocalConsumer::ProgramChange()
*/
/*!
\fn void BMidiLocalProducer::SprayChannelPressure(uchar channel,
uchar pressure, bigtime_t time = 0) const
\brief Sends a Channel Pressure event to all connected consumers.
\sa BMidiLocalConsumer::ChannelPressure()
*/
/*!
\fn void BMidiLocalProducer::SprayPitchBend(uchar channel, uchar lsb,
uchar msb, bigtime_t time = 0) const
\brief Sends a Pitch Bend event to all connected consumers.
\sa BMidiLocalConsumer::PitchBend()
*/
/*!
\fn void BMidiLocalProducer::SpraySystemExclusive(void* data,
size_t length, bigtime_t time = 0) const
\brief Sends a System Exclusive event to all connected consumers.
You retain ownership of the data and are responsible for freeing it. Even
though data is not declared const, the function does not change it. Even
though the amount of data may be quite large, this function always sends
sysex messages as an atomic block of data.
\sa BMidiLocalConsumer::SystemExclusive()
*/
/*!
\fn void BMidiLocalProducer::SpraySystemCommon(uchar status,\
uchar data1, uchar data2, bigtime_t time = 0) const
\brief Sends a System Common event to the connected consumers.
The status byte must be one of the following:
<table border="1">
<tr>
<td>0xF1</td>
<td>\c B_MIDI_TIME_CODE</td>
<td>data1 only</td>
</tr>
<tr>
<td>0xF2</td>
<td>\c B_SONG_POSITION</td>
<td>data1 and data2</td>
</tr>
<tr>
<td>0xF3</td>
<td>\c B_SONG_SELECT</td>
<td>data1 only</td>
</tr>
<tr>
<td>0xF5</td>
<td>\c B_CABLE_MESSAGE</td>
<td>data1 only</td>
</tr>
<tr>
<td>0xF6</td>
<td>\c B_TUNE_REQUEST</td>
<td>no data</td>
</tr>
<tr>
<td>0xF7</td>
<td>\c B_SYS_EX_END</td>
<td>no data</td>
</tr>
</table>
\sa BMidiLocalConsumer::SystemCommon()
*/
/*!
\fn void BMidiLocalProducer::SpraySystemRealTime(uchar status,
bigtime_t time = 0) const
\brief Sends a Real Time event to the connected consumers.
The status byte must be one of the following:
<table border="1">
<tr><td>0xf8</td><td>\c B_TIMING_CLOCK</td></tr>
<tr><td>0xfa</td><td>\c B_START</td></tr>
<tr><td>0xfb</td><td>\c B_CONTINUE</td></tr>
<tr><td>0xfc</td><td>\c B_STOP</td></tr>
<tr><td>0xfe</td><td>\c B_ACTIVE_SENSING</td></tr>
<tr><td>0xff</td><td>\c B_SYSTEM_RESET</td></tr>
</table>
Because of their high priority, the MIDI specification allows real time
messages to "interleave" with other MIDI messages. A large sysex dump, for
example, may be interrupted by a real time event. The Midi Kit, however,
doesn't care. If you (or another producer) have just sent a big system
exclusive to a consumer, any following real time message will simply have
to wait until the consumer has dealt with the sysex.
\sa BMidiLocalConsumer::SystemRealTime()
*/
/*!
\fn void BMidiLocalProducer::SprayTempoChange(int32 bpm,
bigtime_t time = 0) const
\brief Sends a Tempo Change event to the connected consumers.
This kind of Tempo Change event is not really part of the MIDI spec,
rather it is an extension from the SMF (Standard MIDI File) format.
\sa BMidiLocalConsumer::TempoChange()
*/
docs/user/midi2/MidiRoster.dox
+418
View File
@@ -0,0 +1,418 @@
/*!
\file MidiRoster.h
\ingroup midi2
\ingroup libbe
\brief Defines the heart of the MIDI Kit: the MIDI Roster.
*/
/*!
\enum BMidiOp
\ingroup midi2
\ingroup libbe
\brief Defines the status codes for MIDI Server notification messages.
These codes are used when you request notification as in
BMidiRoster::StartWatching(). Check against these codes to determine what
is happening. See the StartWatching() method for a more complete
description of the codes and their meaning.
*/
/*!
\var B_MIDI_EVENT
\brief BMessage identifier of MIDI messages.
*/
/*!
\class BMidiRoster MidiRoster.h
\ingroup midi2
\ingroup libmidi2
\ingroup libbe
\brief Interface to the system-wide Midi Roster.
BMidiRoster allows you to find available MIDI consumer and producer
objects. You can locate these objects using the iterative NextEndpoint(),
NextProducer(), and NextConsumer() methods or by requesting notification
messages to be sent with StartWatching(). Notification messages may
contain object IDs which can be resolved using the FindEndpoint(),
FindProducer(), and FindConsumer() methods.
The constructor and destructor of BMidiRoster are private, which means
that you cannot create or delete your own BMidiRoster objects. Every
application can have only one instance of BMidiRoster, which is
automatically created the very first time you use a Midi Kit function.
You can call BMidiRoster's functions like this:
\code
producer = BMidiRoster::FindProducer(someID);
\endcode
Or using the slightly more annoying:
\code
BMidiRoster* roster = BMidiRoster::MidiRoster();
if (roster != NULL)
{
producer = roster->FindProducer(someID);
}
\endcode
*/
/*!
\fn BMidiEndpoint* BMidiRoster::NextEndpoint(int32* id)
\brief Returns the next endpoint from the roster
The "next endpoint" means: the endpoint with the ID that follows \a id.
So if you set id to 3, the first possible endpoint it returns is
endpoint 4. No endpoint can have ID 0, so passing 0 gives you the first
endpoint. If you pass \c NULL instead of an ID, NextEndpoint() always
returns \c NULL. When the function returns, it sets \a id to the ID of the
endpoint that was found. If no more endpoints exist, NextEndpoint()
returns \c NULL and id is not changed. NextEndpoint() does <b>not</b>
return locally created endpoints, even if they are Register()'ed.
Usage example:
\code
int32 id = 0;
BMidiEndpoint* endp;
while ((endp = BMidiRoster::NextEndpoint(&id)) != NULL)
{
... do something with endpoint ...
endp->Release(); // don't forget!
}
\endcode
Remember that NextEndpoint() bumps the endpoint's reference count, so you
should always \link BMidiEndpoint::Release() Release() \endlink it when
you are done.
*/
/*!
\fn BMidiProducer* BMidiRoster::NextProducer(int32* id)
\brief Returns the next producer from the roster.
Like NextEndpoint(), but only returns producer endpoints.
\sa NextConsumer
\sa NextEndpoint
*/
/*!
\fn BMidiConsumer* BMidiRoster::NextConsumer(int32* id)
\brief Returns the next consumer from the roster.
Like NextEndpoint(), but only returns consumer endpoints.
\sa NextProducer
\sa NextEndpoint
*/
/*!
\fn BMidiEndpoint* BMidiRoster::FindEndpoint(int32 id,
bool localOnly = false)
\brief Returns the endpoint with the specified \a id.
FindEndpoint() will always find <b>any</b> local endpoints created by this
application; they do not have to be published with Register() first. If
localOnly is false, FindEndpoint() also looks at remote endpoints,
otherwise only local endpoints will be resolved. Returns NULL if no such
endpoint could be found.
You should use a dynamic_cast to convert the BMidiEndpoint into a producer
or consumer:
\code
BMidiEndpoint* endp = ...;
BMidiProducer* prod = NULL;
BMidiConsumer* cons = NULL;
if (endp->IsProducer())
{
prod = dynamic_cast<BMidiProducer*>(endp);
}
else if (endp->IsConsumer())
{
cons = dynamic_cast<BMidiConsumer*>(endp);
}
\endcode
Remember that FindEndpoint() increments the endpoint's reference count,
so you should always \link BMidiEndpoint::Release() Release() \endlink
an endpoint when you are done with it:
\code
BMidiEndpoint* endp = BMidiRoster::FindEndpoint(someID);
if (endp != NULL)
{
...do stuff with the endpoint...
endp->Release();
}
\endcode
*/
/*!
\fn BMidiProducer* BMidiRoster::FindProducer(int32 id,
bool localOnly = false)
\brief Finds the producer with the specified \a id.
Like FindEndpoint(), but only looks for producer endpoints. Returns
\c NULL if no endpoint with that ID exists, or if that endpoint is not
a producer.
\sa FindConsumer
\sa FindEndpoint
*/
/*!
\fn BMidiConsumer* BMidiRoster::FindConsumer(int32 id,
bool localOnly = false)
\brief Finds the consumer with the specified \a id.
Like FindEndpoint(), but only looks for consumer endpoints. Returns
\c NULL if no endpoint with that ID exists, or if that endpoint is not
a consumer.
\sa FindProducer
\sa FindEndpoint
*/
/*!
\fn void BMidiRoster::StartWatching(const BMessenger* msngr)
\brief Start receiving notifications from the Midi Roster
When you start watching, BMidiRoster sends you notifications for all
currently \b published \c remote endpoints, and all the current
connections between them. (At this point, BMidiRoster does not let you
know about connections between unpublished endpoints, nor does it tell
you anything about your local endpoints, even though they may be
published.)
Thereafter, you'll receive notifications any time something important
happens to an object. The application that performs these operations is
itself not notified. The assumption here is that you already know about
these changes, because you are the one that is performing them.
The notifications are BMessages with code B_MIDI_EVENT. You specify the
BMessenger that will be used to send these messages. Each message contains
a field called be:op that describes the type of notification.
The "registered" and "unregistered" notifications are sent when a remote
endpoint Register()'s or Unregister()'s, respectively. You don't receive
these notifications when you register or unregister your local endpoints,
but the other apps will.
<table border="1">
<tr>
<td>be:op</td>
<td>int32</td>
<td>\c B_MIDI_REGISTERED</td>
</tr>
<tr>
<td>be:id</td>
<td>int32</td>
<td>id of the endpoint</td>
</tr>
<tr>
<td>be:type</td>
<td>string</td>
<td>"producer" or "consumer"</td>
</tr>
</table>
<table border="1">
<tr>
<td>be:op</td>
<td>int32</td>
<td>\c B_MIDI_UNREGISTERED</td>
</tr>
<tr>
<td>be:id</td>
<td>int32</td>
<td>id of the endpoint</td>
</tr>
<tr>
<td>be:type</td>
<td>string</td>
<td>"producer" or "consumer"</td>
</tr>
</table>
The "connected" and "disconnected" notifications are sent when a consumer
\link BMidiProducer::Connect() Connect()\endlink's to a producer, or when
they \link BMidiProducer::Disconnect() Disconnect() \endlink. You will
receive these notifications when \b any two endpoints connect or
disconnect, even if they are not published. (The purpose of which is
debatable.) You won't receive the notifications if you are the one making
the connection, even if both endpoints are remote. You \b will be notified
when another app connects one of your published endpoints.
<table border="1">
<tr>
<td>be:op</td>
<td>\c int32</td>
<td>\c B_MIDI_CONNECTED</td>
</tr>
<tr>
<td>be:producer</td>
<td>\c int32</td>
<td>id of the connector</td>
</tr>
<tr>
<td>be:consumer</td>
<td>\c int32</td>
<td>id of the connectee</td>
</tr>
</table>
<table border="1">
<tr>
<td>be:op</td>
<td>\c int32</td>
<td>\c B_MIDI_DISCONNECTED</td>
</tr>
<tr>
<td>be:producer</td>
<td>\c int32</td>
<td>id of the connector</td>
</tr>
<tr>
<td>be:consumer</td>
<td>int32</td>
<td>id of the connectee</td>
</tr>
</table>
the following notifications are sent when an endpoint's attributes are
changed. you receive these notifications only if another application is
changing one of its published endpoints.
<table border="1">
<tr>
<td>be:op</td>
<td>\c int32</td>
<td>\c B_MIDI_CHANGED_NAME</td>
</tr>
<tr>
<td>be:id</td>
<td>\c int32</td>
<td>id of the endpoint</td>
</tr>
<tr>
<td>be:type</td>
<td>string</td>
<td>"producer" or "consumer"</td>
</tr>
<tr>
<td>be:name</td>
<td>string</td>
<td>the endpoint's new name</td>
</tr>
</table>
<table border="1">
<tr>
<td>be:op</td>
<td>\c int32</td>
<td>\c B_MIDI_CHANGED_LATENCY</td>
</tr>
<tr>
<td>be:id</td>
<td>\c int32</td>
<td>id of the endpoint</td>
</tr>
<tr>
<td>be:type</td>
<td>string</td>
<td>"producer" or "consumer"</td>
</tr>
<tr>
<td>be:latency</td>
<td>int64</td>
<td>the new latency (microseconds)</td>
</tr>
</table>
<table border="1">
<tr>
<td>be:op</td>
<td>int32</td>
<td>\c B_MIDI_CHANGED_PROPERTIES</td>
</tr>
<tr>
<td>be:id</td>
<td>\c int32</td>
<td>id of the endpoint</td>
</tr>
<tr>
<td>be:type</td>
<td>string</td>
<td>"producer" or "consumer"</td>
</tr>
<tr>
<td>be:properties</td>
<td>bmessage</td>
<td>the new properties</td>
</tr>
</table>
Typical usage example:
\code
void MyView::AttachedToWindow()
{
BMessenger msgr(this);
BMidiRoster::StartWatching(&msgr);
}
void MyView::MessageReceived(BMessage* msg)
{
switch (msg->what)
{
case B_MIDI_EVENT:
HandleMidiEvent(msg);
break;
default:
super::MessageReceived(msg);
break;
}
}
\endcode
For the possible midi options, see #BMidiOp
*/
/*!
\fn void BMidiRoster::StopWatching()
\brief Stop receiving notifications from the Midi Roster.
\sa StartWatching()
*/
/*!
\fn status_t BMidiRoster::Register(BMidiEndpoint* object)
\brief Publishes an endpoint to other applications.
Calls BMidiEndpoint's \link BMidiEndpoint::Register() Register() \endlink
method to publish an endpoint, which makes it visible to other
applications.
*/
/*!
\fn status_t BMidiRoster::Unregister(BMidiEndpoint* object)
\brief Hides an endpoint from other applications.
Calls BMidiEndpoint's
\link BMidiEndpoint::Unregister() Unregister() \endlink method to hide
a previously published endpoint from other applications.
*/
/*!
\fn BMidiRoster* BMidiRoster::MidiRoster()
\brief Returns a pointer to the only instance of BMidiRoster.
There is no real reason use this function, since all BMidiRoster's public
function are static.
*/
docs/user/midi2/midi2concepts.png → docs/user/midi2/images/midi2concepts.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 28 KiB

docs/user/midi2/midiconsumer.dox
-291
View File
@@ -1,291 +0,0 @@
/*!
\class BMidiConsumer MidiConsumer.h
\ingroup midi2
\ingroup libmidi2
\brief Receives MIDI events from a producer
A consumer is an object that knows how to deal with incoming MIDI events. A
consumer can be connected to multiple producers at the same time. There is no
way to find out which producers are connected to this consumer just by looking
at the BMidiConsumer object; you will have to consult BMidiRoster for that.
A BMidiConsumer either represents a local consumer, i.e. a class extending from
BMidiLocalConsumer, or is a proxy for a remote object published by another app.
*/
/*!
\fn bigtime_t BMidiConsumer::Latency() const
\brief Returns the latency of this consumer
The latency is measured in microseconds. Producers should attempt to get MIDI
events to this consumer by <I>(when - latency)</I>. You do this by subtracting
the latency from the performance time when you spray the events (provided that
you spray these events ahead of time, of course).
You cannot <I>set</I> the latency on a BMidiConsumer, only on a
BMidiLocalConsumer.
The latency issue gets slightly more complicated when multiple endpoints are
chained together, as in the following picture:
\verbatim
+-------+ +-------------+ +-------+
| | | | | |
| prodA |---->| consB prodB |---->| consC |
| | | | | |
+-------+ +-------------+ +-------+
appA appB (filter) appC
\endverbatim
Suppose consC has 200ms latency, and consB has 100ms latency. If consB simply
reports 100ms, then prodA will schedule its events for (t - 100), which is
really 200ms too late. (Of course, producers send out their events as soon as
possible, so depending on the load of the system, everything may work out just
fine.)
ConsB should report the latency of the consumer that is hooked up to its
output, consC, in addition to its own latency. In other words, the full
downstream latency. So, the reported latency in this case would be 300ms. This
also means that appB should change the latency of consB when prodB makes or
breaks a connection, and when consC reports a latency change. (If multiple
consumers are connected to prodB, you should take the slowest one.)
Unfortunately, the Midi Kit provides no easy mechanism for doing any of this,
so you are on your own here.
*/
/*!
\class BMidiLocalConsumer MidiConsumer.h
\ingroup midi2
\ingroup libmidi2
\brief A consumer endpoint that is created by your own application
If you want to create a consumer that reacts to MIDI events, you should
subclass BMidiLocalConsumer.
Each local consumer has its own thread that receives and dispatches the MIDI
events. Whenever MIDI data arrives, the Data() hook passes the MIDI event on to
a more specific hook function: NoteOn(), NoteOff(), SystemExclusive(), and so
on. Calls to these hook functions are serialized -- they will never have to be
re-entrant. They also should not be called from outside the thread that is
invoking them.
Your subclass can override any of the MIDI event hooks. BMidiLocalConsumer
doesn't provide default implementations for them, so you don't have to call a
hook's default implementation if you override it. For complete control, you can
also override Data().
Most hook functions take a channel argument. Even though MIDI channels are
really numbered 1 through 16, the hook functions work with channels 0 through
15. The performance time for the event is specified in microseconds relative to
the system time base. A performance time that is 0 (or really any time in the
past) means "play as soon as possible". See the \ref midi2time "introduction"
for more information about timing and consumers.
The thread driving the consumer's events is a very high priority real time
thread. Events should be handled as quickly as possible (not counting
snoozing). If non-time-critical computation is needed it may be wise to queue
events up for a lower priority thread to handle them external to the main event
thread.
*/
/*!
\fn BMidiLocalConsumer::BMidiLocalConsumer(const char *name = NULL)
\brief Creates a new local consumer endpoint
The new endpoint is not visible to other applications until you Register() it.
You can tell the constructor what the name of the new consumer will be. If you
pass NULL (or use the default argument), then the consumer's name will be an
empty string. It won't be NULL, since endpoint names cannot be NULL.
There is no guarantee that the endpoint will be successfully created. For
example, the Midi Server may not be running. Therefore, you should always call
IsValid() after creating a new endpoint to make sure that everything went okay.
If not, Release() the object to reclaim memory and abort gracefully.
\code
MyConsumer* cons = new MyConsumer(...);
if (!cons->IsValid())
{
cons->Release();
...exit gracefully...
}
\endcode
*/
/*!
\fn void BMidiLocalConsumer::SetLatency(bigtime_t latency)
\brief Changes the published latency of the consumer
\sa Latency()
*/
/*!
\fn int32 BMidiLocalConsumer::GetProducerID()
\brief Returns the ID of the producer that most recently sent a MIDI event to
this consumer
You can call this from one of the hooks to determine which producer the event
came from.
*/
/*!
\fn void BMidiLocalConsumer::SetTimeout(bigtime_t when, void* data)
\brief Requests that the Timeout() hook will be called at some point
This method asks the consumer thread to call the Timeout() hook as soon as
possible after the timeout expires. For every call to SetTimeout(), the
Timeout() hook is only called once. Note: the term "timeout" may be a little
misleading; the hook will <I>always</I> be called, even if events are received
in the mean time. Apparently, this facility is handy for dealing with early
events.
Note that the event thread blocks on the consumer's port as long as no events
arrive. By default no timeout is set, and as a result the thread blocks
forever. Your call to SetTimeout() doesn't change this. The new timeout value
will go into effect the next time the thread tries to read from the port, i.e.
after the first event has been received. If no event ever comes in, the
Timeout() hook will never be called. This also means that you cannot cancel a
timeout once you have set it. To repeat, calling SetTimeout() only takes effect
after at least one new event has been received.
\param when An absolute time that's measured against the system clock.
\param data A pointer to a "cookie" that you can pass along to Timeout(). The
data is not copied, so you must ensure that the pointer remains valid until
Timeout() is called. You typically delete the data inside Timeout().
*/
/*!
\fn void BMidiLocalConsumer::Timeout(void* data)
\brief Hook function that is called per your own request
\sa SetTimeout()
*/
/*!
\fn void BMidiLocalConsumer::Data(
uchar* data, size_t length, bool atomic, bigtime_t time)
\brief Invoked when raw MIDI is received
What the default implementation of Data() does depends on the value of atomic.
If atomic is true, the data received comprises a single MIDI event; i.e. one
status byte followed by the appropriate number of data bytes and nothing else.
In this case, Data() calls the event-specific hook function that corresponds to
that status byte. This optimization is used by the Midi Kit to allow faster
dispatch of events generated by the specific Spray functions from
BMidiLocalProducer.
If atomic is false, Data() ignores the MIDI event. If you want a consumer to
handle non-atomic events, you have to override Data() and program this
yourself. In that case, you probably also want to call the default
implementation to handle the "normal" MIDI events.
Data() is rarely overridden, but you can override it if you want to. If you do,
remember that the data buffer is owned by the Midi Kit. Do not attempt to
modify or free it, lest you wish to be laughed at by other developers.
\param data the MIDI event data
\param length byte size of the data buffer
\param atomic whether the data buffer contains a single complete MIDI event
\param time the requested performance time of the event
\sa BMidiLocalProducer::SprayData()
*/
/*!
\fn void BMidiLocalConsumer::NoteOff(
uchar channel, uchar note, uchar velocity, bigtime_t time)
\brief Invoked when a Note Off event is received
\sa BMidiLocalProducer::SprayNoteOff()
*/
/*!
\fn void BMidiLocalConsumer::NoteOn(
uchar channel, uchar note, uchar velocity, bigtime_t time)
\brief Invoked when a Note On event is received
\sa BMidiLocalProducer::SprayNoteOn()
*/
/*!
\fn void BMidiLocalConsumer::KeyPressure(
uchar channel, uchar note, uchar pressure, bigtime_t time)
\brief Invoked when a Polyphonic Pressure (Aftertouch) event is received
\sa BMidiLocalProducer::SprayKeyPressure()
*/
/*!
\fn void BMidiLocalConsumer::ControlChange(
uchar channel, uchar controlNumber, uchar controlValue, bigtime_t time)
\brief Invoked when a Controller Change event is received
\sa BMidiLocalProducer::SprayControlChange()
*/
/*!
\fn void BMidiLocalConsumer::ProgramChange(
uchar channel, uchar programNumber, bigtime_t time)
\brief Invoked when a Program Change event is received
\sa BMidiLocalProducer::SprayProgramChange()
*/
/*!
\fn void BMidiLocalConsumer::ChannelPressure(
uchar channel, uchar pressure, bigtime_t time)
\brief Invoked when a Channel Pressure event is received
\sa BMidiLocalProducer::SprayChannelPressure()
*/
/*!
\fn void BMidiLocalConsumer::PitchBend(
uchar channel, uchar lsb, uchar msb, bigtime_t time)
\brief Invoked when a Pitch Bend event is received
\sa BMidiLocalProducer::SprayPitchBend()
*/
/*!
\fn void BMidiLocalConsumer::SystemExclusive(
void* data, size_t length, bigtime_t time)
\brief Invoked when a System Exclusive event is received
The data does not include the sysex start and end control bytes (0xF0 and 0xF7),
only the payload of the sysex message.
The data belongs to the Midi Kit and is only valid for the duration of this
event. You may not modify or free it.
\sa BMidiLocalProducer::SpraySystemExclusive()
*/
/*!
\fn void BMidiLocalConsumer::SystemCommon(
uchar status, uchar data1, uchar data2, bigtime_t time)
\brief Invoked when a System Common event is received
Not all data bytes are used for all common events. Unused bytes are set to 0.
\sa BMidiLocalProducer::SpraySystemCommon()
*/
/*!
\fn void BMidiLocalConsumer::SystemRealTime(
uchar status, bigtime_t time)
\brief Invoked when a Real Time event is received
\sa BMidiLocalProducer::SpraySystemRealTime()
*/
/*!
\fn void BMidiLocalConsumer::TempoChange(int32 beatsPerMinute, bigtime_t time)
\brief Invoked when a Tempo Change event is received
\sa BMidiLocalProducer::SprayTempoChange()
*/
/*!
\fn void BMidiLocalConsumer::AllNotesOff(bool justChannel, bigtime_t time)
\brief Not used
*/
docs/user/midi2/midiendpoint.dox
-296
View File
@@ -1,296 +0,0 @@
/*!
\class BMidiEndpoint
\ingroup midi2
\ingroup libmidi2
\brief 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 \link
BMidiProducer::Disconnect() Disconnect() \endlink and Unregister() the object
yourself and not rely on the destructor to do this.
*/
/*!
\fn const char* BMidiEndpoint::Name() const
\brief 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.
\sa SetName()
*/
/*!
\fn void BMidiEndpoint::SetName(const char* name)
\brief 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.
\param name The new name. If you pass NULL, the name simply won't be changed.
\sa Name()
*/
/*!
\fn int32 BMidiEndpoint::ID() const
\brief 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 <I>not</I> valid IDs.
*/
/*!
\fn bool BMidiEndpoint::IsProducer() const
\brief Determines whether this endpoint is a BMidiProducer
If it is, you can use a dynamic_cast to convert this object into a producer:
\code
if (endp->IsProducer())
{
BMidiProducer* prod = dynamic_cast<BMidiProducer*>(endp);
....
}
\endcode
*/
/*!
\fn bool BMidiEndpoint::IsConsumer() const
\brief Determines whether this endpoint is a BMidiConsumer
If it is, you can use a dynamic_cast to convert this object into a consumer:
\code
if (endp->IsConsumer())
{
BMidiConsumer* cons = dynamic_cast<BMidiConsumer*>(endp);
....
}
\endcode
*/
/*!
\fn bool BMidiEndpoint::IsRemote() const
\brief 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.
*/
/*!
\fn bool BMidiEndpoint::IsLocal() const
\brief 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.
*/
/*!
\fn bool BMidiEndpoint::IsPersistent() const
\brief Not used
The purpose of this function is unclear, and as a result it doesn't do anything
in the OpenBeOS implementation of the Midi Kit.
\return Always returns false.
*/
/*!
\fn bool BMidiEndpoint::IsValid() const
\brief 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.
*/
/*!
\fn status_t BMidiEndpoint::Acquire()
\brief 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
<I>always</I> 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.
\return Always returns B_OK
\sa Release()
*/
/*!
\fn status_t BMidiEndpoint::Release()
\brief Decrements the endpoint's reference count
\return Always returns B_OK
\sa Acquire()
*/
/*!
\fn status_t BMidiEndpoint::Register()
\brief 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 \link BMidiRoster::StartWatching() watching \endlink, you will
<I>not</I> receive notifications for any local endpoints you register or
unregister. Of course, other applications <I>will</I> 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.
\return B_OK on success, or a negative error code (typically B_ERROR) if
something went wrong.
\sa Unregister()
*/
/*!
\fn status_t BMidiEndpoint::Unregister()
\brief Hides the endpoint from the roster
\sa Register()
*/
/*!
\fn status_t BMidiEndpoint::SetProperties(const BMessage* props)
\brief 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:
\code
BMessage props;
if (endpoint->GetProperties(&props) == B_OK)
{
...add data to the message...
endpoint->SetProperties(&props);
}
\endcode
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.
<TABLE BORDER="1">
<TR><TD>property</TD><TD>Vector icon (raw data)</TD></TR>
<TR><TD>field name</TD><TD>"icon"</TD></TR>
<TR><TD>field type</TD><TD>'VICN'</TD></TR>
</TABLE>
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.
<TABLE BORDER="1">
<TR><TD>property</TD><TD>Large (32x32) icon</TD></TR>
<TR><TD>field name</TD><TD>"be:large_icon"</TD></TR>
<TR><TD>field type</TD><TD>'ICON'</TD></TR>
</TABLE>
<TABLE BORDER="1">
<TR><TD>property</TD><TD>Small (16x16) icon</TD></TR>
<TR><TD>field name</TD><TD>"be:mini_icon"</TD></TR>
<TR><TD>field type</TD><TD>'MICN'</TD></TR>
</TABLE>
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.
\sa GetProperties()
*/
/*!
\fn status_t BMidiEndpoint::GetProperties(BMessage* props) const
\brief Reads the properties of the endpoint
Usage example:
\code
BMessage props;
if (endpoint->GetProperties(&props) == B_OK)
{
...examine the contents of the message...
}
\endcode
Note that GetProperties() overwrites the contents of your BMessage.
\sa SetProperties()
*/
docs/user/midi2/midifiles.dox
-31
View File
@@ -1,31 +0,0 @@
*!
\file Midi2Defs.h
\ingroup midi2
\brief General Defines for the MIDI2 kit
Please see \ref midi2defs for more information.
*/
/*!
\file MidiConsumer.h
\ingroup midi2
\brief Defines consumer classes for the MIDI Kit
*/
/*!
\file MidiProducer.h
\ingroup midi2
\brief Defines producer classes for the MIDI Kit
*/
/*!
\file MidiEndpoint.h
\ingroup midi2
\brief Defines the Baseclass of all MIDI consumers and producers
*/
/*!
\file MidiRoster.h
\ingroup midi2
\brief Defines the heart of the MIDI Kit: the MIDI Roster
*/
docs/user/midi2/midiproducer.dox
-308
View File
@@ -1,308 +0,0 @@
/*!
\class BMidiProducer MidiProducer.h
\ingroup midi2
\ingroup libmidi2
\brief Streams MIDI events to connected consumers
A producer is an object that generate a stream of MIDI events. Each producer
has a list of BMidiConsumer objects to which it is connected, and may be asked
to connect to or disconnect from a BMidiConsumer. A producer can spray its
events to multiple consumers at the same time.
A BMidiProducer either represents a local producer, i.e. a class extending from
BMidiLocalProducer, or is a proxy for a remote object published by another app.
*/
/*!
\fn status_t BMidiProducer::Connect(BMidiConsumer* cons)
\brief Connects a consumer to this producer
Establishes a connection between this producer and the specified consumer
endpoint. From now on, any events that this producer sprays will be sent to
that consumer. You may connect multiple consumers to a producer.
\return B_OK on success, or an error code when the connection could not be
established. If the consumer is a proxy for a remote object and that object no
longer exists, Connect() returns B_ERROR. It also returns B_ERROR if you try to
connect the same producer and consumer more than once.
\sa Disconnect()
*/
/*!
\fn status_t BMidiProducer::Disconnect(BMidiConsumer* cons)
\brief Disconnects a consumer from this producer
Terminates the connection between this producer and the specified consumer
endpoint. From now on, any events that this producer sprays no longer go to
that consumer.
\return B_OK on success, or an error code if there was no connection to break
\sa Connect()
*/
/*!
\fn bool BMidiProducer::IsConnected(BMidiConsumer* cons) const
\brief Determines whether a consumer is connected to this producer
\sa Connect()
\sa Disconnect()
*/
/*!
\fn BList* BMidiProducer::Connections() const
\brief Returns a list with all connected consumers
Returns a BList with pointers to BMidiEndpoint objects for all consumers that
are connected to this producer. You can examine the contents of the list as
follows:
\code
BList* list = prod->Connections();
for (int32 t = 0; t < list->CountItems(); ++t)
{
BMidiEndpoint* endp = (BMidiEndpoint*) list->ItemAt(t);
...do stuff...
endp->Release(); // yes, here too!
}
delete list;
\endcode
Every time you call this function, a new BList is allocated. The caller (that
is you) is responsible for freeing this list. The BMidiEndpoint objects in the
list have their reference counts bumped, so you need to Release() them before
you delete the list or they will go all leaky on you.
*/
/*!
\class BMidiLocalProducer MidiProducer.h
\ingroup midi2
\ingroup libmidi2
\brief A producer endpoint that is created by your own application
You create a BMidiLocalProducer if you want your application to send MIDI
events. You use the various spray functions to send events to all connected
consumers. If no consumers are connected to the producer, any calls to the
spray functions are ignored.
Most spray functions accept a channel argument. Even though MIDI channels are
really numbered 1 through 16, the spray functions work with channels 0 through
15. You can also specify the performance time for the event using the time
argument. Specify 0 (or any time in the past) to perform the event "now", i.e.
as soon as possible. You can also schedule events to be performed in the
future, by passing a time such as system_time() + 5000000, which means 5
seconds from now.
Unlike BMidiLocalConsumer, which should be subclassed almost always, you hardly
ever need to derive a class from BMidiLocalProducer. The only reason for
subclassing is when you need to know when the producer gets connected or
disconnected.
Also unlike consumers, local producers have no thread of control directly
associated with them. If you want to send out the MIDI events from a different
thread, you will have to create one yourself.
*/
/*!
\fn BMidiLocalProducer::BMidiLocalProducer(const char *name = NULL)
\brief Creates a new local producer endpoint
The new endpoint is not visible to other applications until you Register() it.
You can tell the constructor what the name of the new producer will be. If you
pass NULL (or use the default argument), then the producer's name will be an
empty string. It won't be NULL, since endpoint names cannot be NULL.
There is no guarantee that the endpoint will be successfully created. For
example, the Midi Server may not be running. Therefore, you should always call
IsValid() after creating a new endpoint to make sure that everything went okay.
If not, Release() the object to reclaim memory and abort gracefully.
\code
BMidiLocalProducer* prod = new BMidiLocalProducer(...);
if (!prod->IsValid())
{
prod->Release();
...exit gracefully...
}
\endcode
*/
/*!
\fn void BMidiLocalProducer::Connected(BMidiConsumer* cons)
\brief Invoked when a new consumer is connected to this producer
Although typical notifications (i.e. from BMidiRoster's "watching" facility)
are only sent if it is some other app that is performing the operation,
Connected() is also called if you are making the connection yourself.
If you override this hook, you don't have to call the default implementation,
because that does nothing.
\param cons The newly connected consumer. The reference count of the consumer
object is not increased, so you should not Release() it. However, if you want
to keep track of the consumer beyond this function, you should first Acquire()
it, and Release() it when you are done.
\sa Disconnected()
*/
/*!
\fn void BMidiLocalProducer::Disconnected(BMidiConsumer* cons)
\brief Invoked when a consumer is disconnected from this producer
\sa Connected()
*/
/*!
\fn void BMidiLocalProducer::SprayData(
void* data, size_t length, bool atomic = false, bigtime_t time = 0) const
\brief Sends raw MIDI data downstream to all connected consumers
Typically you won't have to call SprayData(); the other spray functions will do
just fine. If you do call it, remember that you retain ownership of the data
and that you are responsible for freeing it at some point. (Even though data is
not declared const, the function does not change it.)
With atomic set to false, you can send a MIDI message in segments (perhaps for
a large sysex dump). However, when you do this, you are on your own. The Midi
Kit only tags the data as being non-atomic, but offers no additional support.
The default implementation of BMidiLocalConsumer completely ignores such
events. To handle non-atomic MIDI data, you should override the
BMidiLocalConsumer::Data() hook and process the MIDI event yourself. All of
BMidiLocalProducer's other spray functions always send atomic data.
\param data the MIDI event data
\param length byte size of the data buffer
\param atomic whether the data buffer contains a single complete MIDI event
\param time the required performance time of the event
\sa BMidiLocalConsumer::Data()
*/
/*!
\fn void BMidiLocalProducer::SprayNoteOff(
uchar channel, uchar note, uchar velocity, bigtime_t time = 0) const
\brief Sends a Note Off event to all connected consumers
\sa BMidiLocalConsumer::NoteOff()
*/
/*!
\fn void BMidiLocalProducer::SprayNoteOn(
uchar channel, uchar note, uchar velocity, bigtime_t time = 0) const
\brief Sends a Note On event to all connected consumers
\sa BMidiLocalConsumer::NoteOn()
*/
/*!
\fn void BMidiLocalProducer::SprayKeyPressure(
uchar channel, uchar note, uchar pressure, bigtime_t time = 0) const
\brief Sends a Polyphonic Pressure (Aftertouch) event to all connected
consumers
\sa BMidiLocalConsumer::KeyPressure()
*/
/*!
\fn void BMidiLocalProducer::SprayControlChange(
uchar channel, uchar controlNumber, uchar controlValue,
bigtime_t time = 0) const
\brief Sends a Controller Change event to all connected consumers
\sa Midi2Defs.h
\sa BMidiLocalConsumer::ControlChange()
*/
/*!
\fn void BMidiLocalProducer::SprayProgramChange(
uchar channel, uchar programNumber, bigtime_t time = 0) const
\brief Sends a Program Change event to all connected consumers
\sa BMidiLocalConsumer::ProgramChange()
*/
/*!
\fn void BMidiLocalProducer::SprayChannelPressure(
uchar channel, uchar pressure, bigtime_t time = 0) const
\brief Sends a Channel Pressure event to all connected consumers
\sa BMidiLocalConsumer::ChannelPressure()
*/
/*!
\fn void BMidiLocalProducer::SprayPitchBend(
uchar channel, uchar lsb, uchar msb, bigtime_t time = 0) const
\brief Sends a Pitch Bend event to all connected consumers
\sa BMidiLocalConsumer::PitchBend()
*/
/*!
\fn void BMidiLocalProducer::SpraySystemExclusive(
void* data, size_t length, bigtime_t time = 0) const
\brief Sends a System Exclusive event to all connected consumers
You retain ownership of the data and are responsible for freeing it. Even
though data is not declared const, the function does not change it. Even though
the amount of data may be quite large, this function always sends sysex
messages as an atomic block of data.
\sa BMidiLocalConsumer::SystemExclusive()
*/
/*!
\fn void BMidiLocalProducer::SpraySystemCommon(
uchar status, uchar data1, uchar data2, bigtime_t time = 0) const
\brief Sends a System Common event to the connected consumers
The status byte must be one of the following:
<TABLE BORDER="1">
<TR><TD>0xF1</TD><TD>B_MIDI_TIME_CODE</TD><TD>data1 only</TD></TR>
<TR><TD>0xF2</TD><TD>B_SONG_POSITION</TD><TD>data1 and data2</TD></TR>
<TR><TD>0xF3</TD><TD>B_SONG_SELECT</TD><TD>data1 only</TD></TR>
<TR><TD>0xF5</TD><TD>B_CABLE_MESSAGE</TD><TD>data1 only</TD></TR>
<TR><TD>0xF6</TD><TD>B_TUNE_REQUEST</TD><TD>no data</TD></TR>
<TR><TD>0xF7</TD><TD>B_SYS_EX_END</TD><TD>no data</TD></TR>
</TABLE>
\sa BMidiLocalConsumer::SystemCommon()
*/
/*!
\fn void BMidiLocalProducer::SpraySystemRealTime(
uchar status, bigtime_t time = 0) const
\brief Sends a Real Time event to the connected consumers
The status byte must be one of the following:
<TABLE BORDER="1">
<TR><TD>0xF8</TD><TD>B_TIMING_CLOCK</TD></TR>
<TR><TD>0xFA</TD><TD>B_START</TD></TR>
<TR><TD>0xFB</TD><TD>B_CONTINUE</TD></TR>
<TR><TD>0xFC</TD><TD>B_STOP</TD></TR>
<TR><TD>0xFE</TD><TD>B_ACTIVE_SENSING</TD></TR>
<TR><TD>0xFF</TD><TD>B_SYSTEM_RESET</TD></TR>
</TABLE>
Because of their high priority, the MIDI specification allows real time
messages to "interleave" with other MIDI messages. A large sysex dump, for
example, may be interrupted by a real time event. The Midi Kit, however,
doesn't care. If you (or another producer) have just sent a big system
exclusive to a consumer, any following real time message will simply have to
wait until the consumer has dealt with the sysex.
\sa BMidiLocalConsumer::SystemRealTime()
*/
/*!
\fn void BMidiLocalProducer::SprayTempoChange(
int32 bpm, bigtime_t time = 0) const
\brief Sends a Tempo Change event to the connected consumers.
This kind of Tempo Change event is not really part of the MIDI spec, rather
it is an extension from the SMF (Standard MIDI File) format.
\sa BMidiLocalConsumer::TempoChange()
*/
docs/user/midi2/midiroster.dox
-309
View File
@@ -1,309 +0,0 @@
/*!
\var B_MIDI_EVENT
\ingroup midi2
\brief BMessage identifier of MIDI messages.
*/
/*!
\class BMidiRoster MidiRoster.h
\ingroup midi2
\ingroup libmidi2
\brief Interface to the system-wide Midi Roster
BMidiRoster allows you to find available MIDI consumer and producer objects.
You can locate these objects using the iterative NextEndpoint(),
NextProducer(), and NextConsumer() methods or by requesting notification
messages to be sent with StartWatching(). Notification messages may contain
object IDs which can be resolved using the FindEndpoint(), FindProducer(), and
FindConsumer() methods.
The constructor and destructor of BMidiRoster are private, which means that you
cannot create or delete your own BMidiRoster objects. Every application can
have only one instance of BMidiRoster, which is automatically created the very
first time you use a Midi Kit function.
You can call BMidiRoster's functions like this:
\code
producer = BMidiRoster::FindProducer(someID);
\endcode
Or using the slightly more annoying:
\code
BMidiRoster* roster = BMidiRoster::MidiRoster();
if (roster != NULL)
{
producer = roster->FindProducer(someID);
}
\endcode
*/
/*!
\fn BMidiEndpoint* BMidiRoster::NextEndpoint(int32* id)
\brief Returns the next endpoint from the roster
The "next endpoint" means: the endpoint with the ID that follows id. So if you
set id to 3, the first possible endpoint it returns is endpoint 4. No endpoint
can have ID 0, so passing 0 gives you the first endpoint. If you pass NULL
instead of an ID, NextEndpoint() always returns NULL. When the function
returns, it sets id to the ID of the endpoint that was found. If no more
endpoints exist, NextEndpoint() returns NULL and id is not changed.
NextEndpoint() does <I>not</I> return locally created endpoints, even if they
are Register()'ed.
Usage example:
\code
int32 id = 0;
BMidiEndpoint* endp;
while ((endp = BMidiRoster::NextEndpoint(&id)) != NULL)
{
...do something with endpoint ...
endp->Release(); // don't forget!
}
\endcode
Remember that NextEndpoint() bumps the endpoint's reference count, so you
should always \link BMidiEndpoint::Release() Release() \endlink it when you are
done.
*/
/*!
\fn BMidiProducer* BMidiRoster::NextProducer(int32* id)
\brief Returns the next producer from the roster
Like NextEndpoint(), but only returns producer endpoints.
\sa NextConsumer
\sa NextEndpoint
*/
/*!
\fn BMidiConsumer* BMidiRoster::NextConsumer(int32* id)
\brief Returns the next consumer from the roster
Like NextEndpoint(), but only returns consumer endpoints.
\sa NextProducer
\sa NextEndpoint
*/
/*!
\fn BMidiEndpoint* BMidiRoster::FindEndpoint(
int32 id, bool localOnly = false)
\brief Returns the endpoint with the specified ID
FindEndpoint() will always find <I>any</I> local endpoints created by this
application; they do not have to be published with Register() first. If
localOnly is false, FindEndpoint() also looks at remote endpoints, otherwise
only local endpoints will be resolved. Returns NULL if no such endpoint could
be found.
You should use a dynamic_cast to convert the BMidiEndpoint into a producer or
consumer:
\code
BMidiEndpoint* endp = ...;
BMidiProducer* prod = NULL;
BMidiConsumer* cons = NULL;
if (endp->IsProducer())
{
prod = dynamic_cast<BMidiProducer*>(endp);
}
else if (endp->IsConsumer())
{
cons = dynamic_cast<BMidiConsumer*>(endp);
}
\endcode
Remember that FindEndpoint() increments the endpoint's reference count, so you
should always \link BMidiEndpoint::Release() Release() \endlink an endpoint
when you are done with it:
\code
BMidiEndpoint* endp = BMidiRoster::FindEndpoint(someID);
if (endp != NULL)
{
...do stuff with the endpoint...
endp->Release();
}
\endcode
*/
/*!
\fn BMidiProducer* BMidiRoster::FindProducer(
int32 id, bool localOnly = false)
\brief Finds the producer with the specified ID
Like FindEndpoint(), but only looks for producer endpoints. Returns NULL if no
endpoint with that ID exists, or if that endpoint is not a producer.
\sa FindConsumer
\sa FindEndpoint
*/
/*!
\fn BMidiConsumer* BMidiRoster::FindConsumer(
int32 id, bool localOnly = false)
\brief Finds the consumer with the specified ID
Like FindEndpoint(), but only looks for consumer endpoints. Returns NULL if no
endpoint with that ID exists, or if that endpoint is not a consumer.
\sa FindProducer
\sa FindEndpoint
*/
/*!
\fn void BMidiRoster::StartWatching(const BMessenger* msngr)
\brief Start receiving notifications from the Midi Roster
When you start watching, BMidiRoster sends you notifications for all currently
<I>published</I> <I>remote</I> endpoints, and all the current connections
between them. (At this point, BMidiRoster does not let you know about
connections between unpublished endpoints, nor does it tell you anything about
your local endpoints, even though they may be published.)
Thereafter, you'll receive notifications any time something important happens
to an object. The application that performs these operations is itself not
notified. The assumption here is that you already know about these changes,
because you are the one that is performing them.
The notifications are BMessages with code B_MIDI_EVENT. You specify the
BMessenger that will be used to send these messages. Each message contains a
field called be:op that describes the type of notification.
The "registered" and "unregistered" notifications are sent when a remote
endpoint Register()'s or Unregister()'s, respectively. You don't receive these
notifications when you register or unregister your local endpoints, but the
other apps will.
<TABLE BORDER="1">
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_REGISTERED</TD></TR>
<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
</TABLE>
<TABLE BORDER="1">
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_UNREGISTERED</TD></TR>
<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
</TABLE>
The "connected" and "disconnected" notifications are sent when a consumer \link
BMidiProducer::Connect() Connect()\endlink's to a producer, or when they \link
BMidiProducer::Disconnect() Disconnect() \endlink. You will receive these
notifications when <I>any</I> two endpoints connect or disconnect, even if they
are not published. (The purpose of which is debatable.) You won't receive the
notifications if you are the one making the connection, even if both endpoints
are remote. You <I>will</I> be notified when another app connects one of your
published endpoints.
<TABLE BORDER="1">
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CONNECTED</TD></TR>
<TR><TD>be:producer</TD><TD>int32</TD><TD>ID of the connector</TD></TR>
<TR><TD>be:consumer</TD><TD>int32</TD><TD>ID of the connectee</TD></TR>
</TABLE>
<TABLE BORDER="1">
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_DISCONNECTED</TD></TR>
<TR><TD>be:producer</TD><TD>int32</TD><TD>ID of the connector</TD></TR>
<TR><TD>be:consumer</TD><TD>int32</TD><TD>ID of the connectee</TD></TR>
</TABLE>
The following notifications are sent when an endpoint's attributes are changed.
You receive these notifications only if another application is changing one of
its published endpoints.
<TABLE BORDER="1">
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CHANGED_NAME</TD></TR>
<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
<TR><TD>be:name</TD><TD>string</TD><TD>the endpoint's new name</TD></TR>
</TABLE>
<TABLE BORDER="1">
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CHANGED_LATENCY</TD></TR>
<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
<TR><TD>be:latency</TD><TD>int64</TD><TD>the new latency (microseconds)</TD></TR>
</TABLE>
<TABLE BORDER="1">
<TR><TD>be:op</TD><TD>int32</TD><TD>B_MIDI_CHANGED_PROPERTIES</TD></TR>
<TR><TD>be:id</TD><TD>int32</TD><TD>ID of the endpoint</TD></TR>
<TR><TD>be:type</TD><TD>string</TD><TD>"producer" or "consumer"</TD></TR>
<TR><TD>be:properties</TD><TD>BMessage</TD><TD>the new properties</TD></TR>
</TABLE>
Typical usage example:
\code
void MyView::AttachedToWindow()
{
BMessenger msgr(this);
BMidiRoster::StartWatching(&msgr);
}
void MyView::MessageReceived(BMessage* msg)
{
switch (msg->what)
{
case B_MIDI_EVENT:
HandleMidiEvent(msg);
break;
default:
super::MessageReceived(msg);
break;
}
}
\endcode
For the possible midi options, see #BMidiOp
*/
/*!
\fn void BMidiRoster::StopWatching()
\brief Stop receiving notifications from the Midi Roster
\sa StartWatching()
*/
/*!
\fn status_t BMidiRoster::Register(BMidiEndpoint* object)
\brief Publishes an endpoint to other applications
Calls BMidiEndpoint's \link BMidiEndpoint::Register() Register() \endlink
method to publish an endpoint, which makes it visible to other applications.
*/
/*!
\fn status_t BMidiRoster::Unregister(BMidiEndpoint* object)
\brief Hides an endpoint from other applications
Calls BMidiEndpoint's \link BMidiEndpoint::Unregister() Unregister() \endlink
method to hide a previously published endpoint from other applications.
*/
/*!
\fn BMidiRoster* BMidiRoster::MidiRoster()
\brief Returns a pointer to the only instance of BMidiRoster
There is no real reason use this function, since all BMidiRoster's public
function are static.
*/
/*!
\enum BMidiOp
\brief Defines the status codes for MIDI Server notification messages.
These codes are used when you request notification as in BMidiRoster::StartWatching().
Check against these codes to determine what is happening. See the StartWatching() method
for a more complete description of the codes and their meaning.
*/
docs/user/storage/AppFileInfo.dox
+11 -7
View File
@@ -1,18 +1,21 @@
/*
* Copyright 2011, Haiku inc.
* Distributed under the terms of the MIT Licence.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, [email protected]
* Ingo Weinhold, [email protected]
*
* Documentation by:
* John Scipione <[email protected]>
* Ingo Weinhold <[email protected]>
* Corresponds to:
* /trunk/headers/os/storage/AppFileInfo.h rev 42274
* /trunk/src/kits/storage/AppFileInfo.cpp rev 42274
* headers/os/storage/AppFileInfo.h rev 42274
* src/kits/storage/AppFileInfo.cpp rev 42274
*/
/*!
\file AppFileInfo.h
\ingroup storage
\ingroup libbe
\brief Provides the BAppFileInfo class.
*/
@@ -20,6 +23,7 @@
/*!
\class BAppFileInfo
\ingroup storage
\ingroup libbe
\brief Provides access to the metadata associated with executables,
libraries and add-ons.
docs/user/storage/Directory.dox
+3
View File
@@ -7,6 +7,7 @@
* Ingo Weinhold, [email protected]
* Axel Dörfler, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/storage/Directory.h hrev43528
* src/kits/storage/Directory.cpp hrev43528
@@ -15,6 +16,8 @@
/*!
\file Directory.h
\ingroup storage
\ingroup libbe
\brief Provides the BDirectory class.
*/
docs/user/storage/Entry.dox
+16 -8
View File
@@ -6,6 +6,7 @@
* Tyler Dauwalder
* Simon Cusack, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/storage/Entry.h hrev43528
* src/kits/storage/Entry.cpp hrev43528
@@ -14,12 +15,16 @@
/*!
\file Entry.h
\ingroup storage
\ingroup libbe
\brief Provides the BEntry class and entry_ref implementations.
*/
/*!
\struct entry_ref
\ingroup storage
\ingroup libbe
\brief A filesystem entry represented as a name in a concrete directory.
entry_refs may refer to pre-existing (concrete) files, as well as
@@ -120,20 +125,23 @@
/*!
\var dev_t entry_ref::device
\brief The device id of the storage device on which the entry resides
The device id of the storage device on which the entry resides.
*/
/*!
\var ino_t entry_ref::directory
\brief The inode number of the directory in which the entry resides
The inode number of the directory in which the entry resides.
*/
/*!
\var char *entry_ref::name
\brief The leaf name of the entry
The leaf name of the entry
*/
@@ -162,10 +170,10 @@ BEntry entry("/boot/home/fido");
Should be followed by a call to one of the SetTo() methods, or an
assignment.
- SetTo(const BDirectory*, const char*, bool)
- SetTo(const entry_ref*, bool)
- SetTo(const char*, bool)
- operator=(const BEntry&)
- SetTo(const BDirectory*, const char*, bool)
- SetTo(const entry_ref*, bool)
- SetTo(const char*, bool)
- operator=(const BEntry&)
*/
@@ -250,7 +258,7 @@ BEntry entry("/boot/home/fido");
\fn bool BEntry::Exists() const
\brief Returns whether or not the entry exists in the filesystem.
\returns \c true if the entry exists, \c false if the entry does not exist.
\returns \c true if the entry exists, \c false if not.
*/
docs/user/storage/EntryList.dox
+5 -3
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2011, Haiku, Inc. All Rights Reserved.
* Copyright 2011 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -7,13 +7,15 @@
* John Scipione, [email protected]
*
* Corresponds to:
* /trunk/headers/os/storage/EntryList.h rev 42794
* /trunk/src/kits/storage/EntryList.cpp rev 42794
* headers/os/storage/EntryList.h rev 42794
* src/kits/storage/EntryList.cpp rev 42794
*/
/*!
\file EntryList.h
\ingroup storage
\ingroup libbe
\brief Defines the BEntryList class.
*/
docs/user/storage/File.dox
+2
View File
@@ -15,6 +15,8 @@
/*!
\file File.h
\ingroup storage
\ingroup libbe
\brief Provides the BFile class.
*/
docs/user/storage/FilePanel.dox
+12 -2
View File
@@ -13,42 +13,52 @@
/*!
\file FilePanel.h
\ingroup storage
\ingroup libbe
\brief Provides the BFilePanel and BRefFilter classes and support enums.
*/
/*!
\enum file_panel_mode
Whether the file panel is a save or open panel.
\ingroup storage
\ingroup libbe
\brief Whether the file panel is a save or open panel.
*/
/*!
\var file_panel_mode B_OPEN_PANEL
Open panel
*/
/*!
\var file_panel_mode B_SAVE_PANEL
Save panel
*/
/*!
\enum file_panel_button
List of buttons used by the file panel
\ingroup storage
\ingroup libbe
\brief List of buttons used by the file panel
*/
/*!
\var file_panel_button B_CANCEL_BUTTON
Cancel button
*/
/*!
\var file_panel_button B_DEFAULT_BUTTON
Default button
*/
docs/user/storage/FindDirectory.dox
+5 -3
View File
@@ -1,9 +1,10 @@
/*
* Copyright 2011, Haiku inc.
* Distributed under the terms of the MIT Licence.
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Adrien Destugues <[email protected]>
* Adrien Destugues, [email protected]
*
* Corresponds to:
* /trunk/headers/os/storage/FindDirectory.h rev 42600
* /trunk/src/kits/storage/FindDirectory.cpp rev 42600
@@ -13,6 +14,7 @@
/*!
\file FindDirectory.h
\ingroup storage
\ingroup libbe
\brief Provides the find_directory function.
Haiku provides a set of directories for applications to use. These can be
docs/user/storage/Mime.dox
+5 -22
View File
@@ -1,8 +1,8 @@
/*
* Copyright 2013 Haiku Inc.
* Copyright 2013 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Authors:
* Ingo Weinhold, [email protected]
* John Scipione, [email protected]
*
@@ -15,12 +15,15 @@
/*!
\file Mime.h
\ingroup storage
\ingroup libbe
\brief Provides C and Haiku-only C++ MIME-type handling functions.
*/
/*!
\enum icon_size
\ingroup storage
\ingroup libbe
\brief Legacy BeOS icon size constants.
*/
@@ -62,26 +65,6 @@
*/
/*!
\fn status_t do_mime_update(int32 what, const char *path, int recursive,
int synchronous, int force)
\brief Helper function that contacts the registrar for mime update calls.
\param what The message identifier.
\param path The path to a file or directory, or \c NULL.
\param recursive Triggers recursive behavior if not \c NULL.
\param synchronous If not \c NULL update_mime_info() waits until the
operation is finished, otherwise it returns immediately and the
update is done asynchronously.
\param force Specifies how to handle files that already have MIME
information.
\returns A status code.
\see update_mime_info
*/
/*!
\fn int update_mime_info(const char *path, int recursive, int synchronous,
int force)
docs/user/storage/MimeType.dox
+3
View File
@@ -7,6 +7,7 @@
* Ingo Weinhold, [email protected]
* Axel Dörfler, [email protected]
* John Scipione, [email protected]
*
* Corresponds to:
* headers/os/storage/MimeType.h hrev43528
* src/kits/storage/MimeType.cpp hrev43528
@@ -15,6 +16,8 @@
/*!
\file MimeType.h
\ingroup storage
\ingroup libbe
\brief Provides the BMimeType class.
*/
docs/user/storage/Node.dox
+14 -4
View File
@@ -1,25 +1,30 @@
/*
* Copyright 2002-2011, Haiku Inc.
* Copyright 2002-2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Tyler Dauwalder, [email protected]
* John Scipione, [email protected]
* Ingo Weinhold, [email protected]
*
* Corresponds to:
* /trunk/headers/os/app/Node.h rev 42803
* /trunk/src/kits/app/Node.cpp rev 42803
* /trunk/headers/os/app/Node.h rev 42803
* /trunk/src/kits/app/Node.cpp rev 42803
*/
/*!
\file Node.h
\ingroup storage
\ingroup libbe
\brief Provides the BNode class and node_ref structure.
*/
/*!
\struct node_ref
\ingroup storage
\ingroup libbe
\brief Reference structure to a particular vnode on a device.
*/
@@ -71,6 +76,7 @@
/*!
\class BNode
\ingroup storage
\ingroup libbe
\brief A BNode represents a chunk of data in the filesystem.
The BNode class provides an interface for manipulating the data and
@@ -82,18 +88,22 @@
/*!
\var BNode::fFd
File descriptor for the given node.
*/
/*!
\var BNode::fAttrFd
File descriptor for the attribute directory of the node. Initialized lazily.
File descriptor for the attribute directory of the node.
Initialized lazily.
*/
/*!
\var BNode::fCStatus
The object's initialization status.
*/
docs/user/storage/BFilePanel_example.png → docs/user/storage/images/BFilePanel_example.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 23 KiB

docs/user/support/Archivable.dox
+24 -15
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -11,18 +11,22 @@
* Thom Holwerda, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Archivable.h rev 37751
* /trunk/src/kits/support/Archivable.cpp rev 37751
* headers/os/support/Archivable.h rev 37751
* src/kits/support/Archivable.cpp rev 37751
*/
/*! \file Archivable.h
/*!
\file Archivable.h
\ingroup support
\ingroup libbe
\brief Provides the BArchivable interface and declares the BArchiver and
BUnarchiver classes.
*/
/*! \class BArchivable
/*!
\class BArchivable
\ingroup support
\ingroup libbe
\brief Interface for objects that can be archived into a BMessage.
@@ -37,8 +41,8 @@
disk. The objective of this interface, however, is to store objects that
will later be restored as new (but identical) objects. To illustrate this
point, BArchivable objects can be restored automatically to the correct
class, whereas BFlattenables have a data type which you need to map to
classes manually.
class, whereas BFlattenable objects have a data type which you need to map
to classes manually.
Archiving is done with the Archive() method. If your class supports it, the
caller can request it to store into a deep archive, meaning that all child
@@ -65,12 +69,12 @@
/*!
\fn BArchivable::BArchivable(BMessage* from)
\brief Constructor. Does important behind-the-scenes work in the unarchiving
process.
\brief Constructor. Does important behind-the-scenes work in the
unarchiving process.
If you inherit this interface you should provide at least one constructor
that takes one BMessage argument. In that constructor, you should call your
parent class' archive constructor (even if your parent class is
that takes one BMessage argument. In that constructor, you should call
your parent class' archive constructor (even if your parent class is
BArchivable).
*/
@@ -130,7 +134,7 @@
/*!
\fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
\brief Perform some action (Internal method defined for binary
compatibility purposes).
compatibility purposes).
\internal This method is defined for binary compatibility purposes, it is
used to ensure that the correct AllUnarchived() and AllArchived()
@@ -184,13 +188,18 @@
///// Global methods /////
/*!
\addtogroup support_globals
@{
*/
/*! \typedef typedef BArchivable* (*instantiation_func)(BMessage*)
//! @{
/*!
\typedef typedef BArchivable* (*instantiation_func)(BMessage*)
\brief Internal definition of a function that can instantiate objects that
have been created with the BArchivable API.
*/
docs/user/support/Archiver.dox
+11 -3
View File
@@ -1,16 +1,24 @@
/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Copyright 2010 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Author:
* Alex Wilson, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Archivable.h rev 37751
* /trunk/src/kits/support/Archivable.cpp rev 37751
* headers/os/support/Archivable.h rev 37751
* src/kits/support/Archivable.cpp rev 37751
*/
/*!
\file Archivable.h
\ingroup support
\ingroup libbe
\brief Contains BArchiver class.
*/
/*!
\class BArchiver
\ingroup support
docs/user/support/Autolock.dox
+76 -69
View File
@@ -1,114 +1,121 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Autolock.h rev 19972
* headers/os/support/Autolock.h rev 19972
*/
/*!
\file Autolock.h
\brief Implements a handy locking utility.
\file Autolock.h
\ingroup support
\ingroup libbe
\brief Implements a handy locking utility.
*/
/*!
\class BAutolock
\ingroup support
\ingroup libbe
\brief Convenient utility to make parts of your code thread-safe easily.
\class BAutolock
\ingroup support
\ingroup libbe
\brief Convenient utility to make parts of your code thread-safe easily.
The autolocker uses a BLooper or a BLocker in order to protect a part
of your code. This class is usually used in combination with a BLocker
that protects a certain part of your code and data that are being
accessed by multiple threads. While BAutolock does not add any features
to locking, it provides a mechanism to easily lock and protect a part of your
code.
The autolocker uses a BLooper or a BLocker in order to protect a part
of your code. This class is usually used in combination with a BLocker
that protects a certain part of your code and data that are being
accessed by multiple threads. While BAutolock does not add any features
to locking, it provides a mechanism to easily lock and protect a part of your
code.
Normally, when you need to protect data, you would have to make sure that
all your locks are paired with unlocks. Below is a simple example, but you
can imagine that there are more complex situations where you might spend a
lot of time debugging a hang because you didn't pair all the Lock()s with an
Unlock(). See the example:
Normally, when you need to protect data, you would have to make sure that
all your locks are paired with unlocks. Below is a simple example, but you
can imagine that there are more complex situations where you might spend a
lot of time debugging a hang because you didn't pair all the Lock()s with an
Unlock(). See the example:
\code
status_t
Receiver::HandleCall(Call *call)
{
... work on call data ...
fDataLocker->Lock()
... perform changes ...
if (!success)
{
fDataLocker->Unlock();
return B_ERROR;
}
fDataLocker->Unlock()
return B_OK;
... work on call data ...
fDataLocker->Lock()
... perform changes ...
if (!success)
{
fDataLocker->Unlock();
return B_ERROR;
}
fDataLocker->Unlock()
return B_OK;
}
\endcode
With the BAutolock this example can be rewritten as follows:
With the BAutolock this example can be rewritten as follows:
\code
status_t
Receiver::HandleCall(Call *call)
{
... work on call data ...
BAutolock autolock(fDataLocker);
... perform changes ...
if (!success)
return B_ERROR;
return B_OK;
... work on call data ...
BAutolock autolock(fDataLocker);
... perform changes ...
if (!success)
return B_ERROR;
return B_OK;
}
\endcode
Since the object is created on stack, it is destroyed as soon as we leave
the function. Because the destruction of the object causes it to unlock
the BLocker or BLooper, you don't have to manually make sure that every
exit from the function is properly unlocked.
Since the object is created on stack, it is destroyed as soon as we leave
the function. Because the destruction of the object causes it to unlock
the BLocker or BLooper, you don't have to manually make sure that every
exit from the function is properly unlocked.
*/
/*!
\fn BAutolock::BAutolock(BLooper *looper)
\brief Create an object and lock the BLooper
\fn BAutolock::BAutolock(BLooper *looper)
\brief Create an object and lock the BLooper
*/
/*!
\fn BAutolock::BAutolock(BLocker *locker)
\brief Create an object and lock the BLocker
\fn BAutolock::BAutolock(BLocker *locker)
\brief Create an object and lock the BLocker
*/
/*!
\fn BAutolock::BAutolock(BLocker &locker)
\brief Create an object and lock the BLocker
\fn BAutolock::BAutolock(BLocker &locker)
\brief Create an object and lock the BLocker
*/
/*!
\fn BAutolock::~BAutolock()
\brief Destroy the object and unlock the associated BLocker or BLooper
\fn BAutolock::~BAutolock()
\brief Destroy the object and unlock the associated BLocker or BLooper
*/
/*!
\fn bool BAutolock::IsLocked(void)
\brief Verify whether the associated BLocker or BLooper are actually locked.
\fn bool BAutolock::IsLocked(void)
\brief Verify whether the associated BLocker or BLooper are actually
locked.
Basically you may assume that when the object is created, you are
almost always sure the actual locking succeeds. It might fail if the
BLocker or BLooper are destroyed though. The semaphore will be
released and the Lock() call will fail.
Basically you may assume that when the object is created, you are
almost always sure the actual locking succeeds. It might fail if the
BLocker or BLooper are destroyed though. The semaphore will be
released and the Lock() call will fail.
If you expect this to happen, you can use this method to help you
protect yourself from any harm.
\retval true The lock was acquired.
\retval false Failed to acquire the lock.
If you expect this to happen, you can use this method to help you
protect yourself from any harm.
\retval true The lock was acquired.
\retval false Failed to acquire the lock.
*/
docs/user/support/Beep.dox
+32 -25
View File
@@ -1,54 +1,61 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Beep.h rev 19972
* /trunk/src/kits/support/Beep.cpp rev 20711
* headers/os/support/Beep.h rev 19972
* src/kits/support/Beep.cpp rev 20711
*/
/////!!!!!! Note that the workings of the beep still aren't completely clear
///// and not completely implemented, so this needs revision if everything
///// is finished.
/*!
\file Beep.h
\brief Functions to generate sounds from the computer.
*/
/////!!!!!! Note that the workings of the beep still aren't completely clear
///// and not completely implemented, so this needs revision if everything
///// is finished.
/*!
\addtogroup support_globals
\file Beep.h
\ingroup support
\ingroup libbe
\brief Functions to generate sounds from the computer.
*/
/*!
\addtogroup support_globals
*/
//! @{
/*! \fn status_t beep()
/*!
\fn status_t beep()
\brief Invoke the standard system beep to alert users.
From Beep.h and in libbe.so.
\see system_beep() and add_system_beep_event()
*/
/*! \fn status_t system_beep(const char* eventName)
/*!
\fn status_t system_beep(const char* eventName)
\brief Invokes the sound for event \a eventName.
You can add the events using add_system_beep_event().
From Beep.h and in libbe.so.
*/
/*! \fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0)
/*!
\fn status_t add_system_beep_event(const char* eventName, uint32 flags = 0)
\brief Adds an event to the media server.
Call this method to add a specific event to the media server.
From Beep.h and in libbe.so.
\param eventName The name of the event.
\param flags Currently unused. Pass \c 0.
*/
//! @}
docs/user/support/BlockCache.dox
+8 -6
View File
@@ -1,22 +1,24 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Niels Sascha Reedijk, [email protected]
* Niels Sascha Reedijk, [email protected]
*
* Proofreading:
* David Weizades, [email protected]
* David Weizades, [email protected]
* Thom Holwerda, [email protected]
*
*
* Corresponds to:
* /trunk/headers/os/support/BlockCache.h rev 19972
* /trunk/src/kits/support/BlockCache.cpp rev 4568
* headers/os/support/BlockCache.h rev 19972
* src/kits/support/BlockCache.cpp rev 4568
*/
/*!
\file BlockCache.h
\ingroup support
\ingroup libbe
\brief Implements a mechanism to store and retrieve memory blocks.
*/
docs/user/support/BufferIO.dox
+162 -138
View File
@@ -1,184 +1,208 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007,Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Stefano Ceccherini ([email protected])
* Authors:
* Stefano Ceccherini, [email protected]
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/BufferIO.h rev 19972
* /trunk/src/kits/support/BufferIO.cpp rev 20510
* headers/os/support/BufferIO.h rev 19972
* src/kits/support/BufferIO.cpp rev 20510
*/
/*!
\file BufferIO.h
\brief Provides the BBufferIO class.
\file BufferIO.h
\ingroup support
\ingroup libbe
\brief Provides the BBufferIO class.
*/
/*!
\class BBufferIO
\ingroup support
\ingroup libbe
\brief A buffered adapter for BPositionIO objects.
\author Stefano Ceccherini \<[email protected]\>
This class differs from other classes derived from BPositionIO in a sense
that it does not actually provide an actual entity to be read or written
to, but rather acts like a "frontend" to a stream. This class especially
comes in handy when working with files that are constantly written and
rewritten and where you want do this writing buffered so that the hard
disk or the network will not have to be accessed so frequently.
This class works as follows. After constructing a BBufferIO object that
you want to be buffered, you can create this object. The constructor
takes a \a stream parameter that points to the object to be buffered.
You then use this object as a proxy to the resource you want to read
of or write to. As soon as you use ReadAt(), the buffer will be
initialized to the contents of the original stream, and subsequent calls
to the positions within the buffer will not be routed to the original
stream. In the same way WriteAt() will change the data in the buffer,
but not in the actual stream. In order to flush the changes to the
original stream, use the Flush() method. Deleting the object when you are
done with it will also flush the stream and update the original stream.
\note This class is not meant to be used in cases where the
original stream requires to be in a consistent state. Neither should
this class be used as a way to perform 'atomic' writes, because the
object might need to do partial writes if it needs to 'move' the
buffer. This happens for instance if the original stream is bigger
than the buffer.
*/
/*!
\class BBufferIO
\ingroup support
\ingroup libbe
\brief A buffered adapter for BPositionIO objects.
\author Stefano Ceccherini \<[email protected]\>
\fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize,
bool ownsStream)
\brief Initialize a BBufferIO object.
This class differs from other classes derived from BPositionIO in a sense that
it does not actually provide an actual entity to be read or written to, but
rather acts like a "frontend" to a stream. This class especially comes in
handy when working with files that are constantly written and rewritten and
where you want do this writing buffered so that the hard disk or the network
will not have to be accessed so frequently.
The constructor will create a buffer of the given size
and associate the object with the given BPositionIO stream.
This class works as follows. After constructing a BBufferIO object that you
want to be buffered, you can create this object. The constructor takes a
\a stream parameter that points to the object to be buffered. You then use
this object as a proxy to the resource you want to read of or write to. As
soon as you use ReadAt(), the buffer will be initialised to the contents
of the original stream,
and subsequent calls to the positions within the buffer will not be
routed to the original stream. In the same way WriteAt() will change
the data in the buffer, but not in the actual stream. In order to flush
the changes to the original stream, use the Flush() method. Deleting
the object when you are done with it will also flush the stream and
update the original stream.
\note This class is not meant to be used in cases where the
original stream requires to be in a consistent state. Neither should this
class be used as a way to perform 'atomic' writes, because the object
might need to do partial writes if it needs to 'move' the buffer. This
happens for instance if the original stream is bigger than the buffer.
\param stream A pointer to a BPositionIO object.
\param bufferSize The size of the buffer that the object will allocate and
use.
\param ownsStream Specifies if the object will delete the stream on
destruction.
*/
/*!
\fn BBufferIO::BBufferIO(BPositionIO *stream, size_t bufferSize, bool ownsStream)
\brief Initialize a BBufferIO object.
The constructor will create a buffer of the given size
and associate the object with the given BPositionIO stream.
\fn BBufferIO::~BBufferIO()
\brief Free the resources allocated by the object
\param stream A pointer to a BPositionIO object.
\param bufferSize The size of the buffer that the object will allocate and
use.
\param ownsStream Specifies if the object will delete the stream on
destruction.
*/
/*!
\fn BBufferIO::~BBufferIO()
\brief Free the resources allocated by the object
Flush pending changes to the stream and free the allocated memory.
If the \c owns_stream property is \c true, the destructor also
deletes the stream associated with the BBufferIO object.
Flush pending changes to the stream and free the allocated memory.
If the \c owns_stream property is \c true, the destructor also
deletes the stream associated with the BBufferIO object.
*/
/*!
\fn ssize_t BBufferIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read the specified amount of bytes at the given position.
\param pos The offset into the stream where to read.
\param buffer A pointer to a buffer where to copy the read data.
\param size The amount of bytes to read.
\return The amount of bytes actually read, or an error code.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
\fn ssize_t BBufferIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read the specified amount of bytes at the given position.
\param pos The offset into the stream where to read.
\param buffer A pointer to a buffer where to copy the read data.
\param size The amount of bytes to read.
\return The amount of bytes actually read, or an error code.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
\retval B_BAD_VALUE The \c buffer parameter is not valid.
\retval B_BAD_VALUE The \c buffer parameter is not valid.
*/
/*!
\fn ssize_t BBufferIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write the specified amount of bytes at the given position.
\param pos The offset into the stream where to write.
\param buffer A pointer to a buffer which contains the data to write.
\param size The amount of bytes to write.
\return The amount of bytes actually written, or an error code.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
\retval B_BAD_VALUE The \c buffer parameter is not valid.
\fn ssize_t BBufferIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write the specified amount of bytes at the given position.
\param pos The offset into the stream where to write.
\param buffer A pointer to a buffer which contains the data to write.
\param size The amount of bytes to write.
\return The amount of bytes actually written, or an error code.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
\retval B_BAD_VALUE The \c buffer parameter is not valid.
*/
/*!
\fn off_t BBufferIO::Seek(off_t position, uint32 seekMode)
\brief Set the position in the stream.
Set the position in the stream where the Read() and Write() functions
(inherited from BPositionIO) begin reading and writing.
How the position argument is understood depends on the seek_mode flag.
\param position The position where you want to seek.
\param seekMode Can have three values:
- \c SEEK_SET. The position passed is an offset from the beginning of the
stream; in other words, the current position is set to position.
For this mode, position should be a positive value.
- \c SEEK_CUR. The position argument is an offset from the current position;
the value of the argument is added to the current position.
- \c SEEK_END. The position argument is an offset from the end of the
stream. In this mode the position argument should be negative (or zero).
\fn off_t BBufferIO::Seek(off_t position, uint32 seekMode)
\brief Set the position in the stream.
\return The current position as an offset in bytes from the beginning of
the stream.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
*/
Set the position in the stream where the Read() and Write() functions
(inherited from BPositionIO) begin reading and writing.
How the position argument is understood depends on the seek_mode flag.
/*!
\fn off_t BBufferIO::Position() const
\brief Return the current position in the stream.
\return The current position as an offset in bytes
from the beginning of the stream.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
*/
\param position The position where you want to seek.
\param seekMode Can have three values:
- \c SEEK_SET The position passed is an offset from the beginning of
the stream; in other words, the current position is set to
position. For this mode, position should be a positive value.
- \c SEEK_CUR The position argument is an offset from the current
position; the value of the argument is added to the current
position.
- \c SEEK_END. The position argument is an offset from the end of the
stream. In this mode the position argument should be negative
(or zero).
/*!
\fn status_t BBufferIO::SetSize(off_t size)
\brief Call the SetSize() function of the assigned BPositionIO stream.
\param size The new size of the BPositionIO object.
\retval B_OK The stream is resized.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
\return The current position as an offset in bytes from the beginning of
the stream.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
*/
/*!
\fn status_t BBufferIO::Flush()
\brief Write pending modifications to the stream.
\return The amount of bytes written, or if it failed it will return an error
\fn off_t BBufferIO::Position() const
\brief Return the current position in the stream.
\return The current position as an offset in bytes
from the beginning of the stream.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
*/
/*!
\fn status_t BBufferIO::SetSize(off_t size)
\brief Call the SetSize() function of the assigned BPositionIO stream.
\param size The new size of the BPositionIO object.
\returns A status code.
\retval B_OK The stream is resized.
\retval B_NO_INIT The object is not associated with a valid BPositionIO
stream.
*/
/*!
\fn status_t BBufferIO::Flush()
\brief Write pending modifications to the stream.
\return The amount of bytes written, or if it failed it will return an error
code.
*/
/*!
\fn BPositionIO *BBufferIO::Stream() const
\brief Return a pointer to the stream specified on construction.
\return A pointer to the BPositionIO stream specified on construction.
\fn BPositionIO *BBufferIO::Stream() const
\brief Return a pointer to the stream specified on construction.
\return A pointer to the BPositionIO stream specified on construction.
*/
/*!
\fn size_t BBufferIO::BufferSize() const
\brief Return the size of the internal buffer.
\return The size of the buffer allocated by the object.
*/
/*!
\fn size_t BBufferIO::BufferSize() const
\brief Return the size of the internal buffer.
/*!
\fn bool BBufferIO::OwnsStream() const
\brief Tell if the BBufferIO object "owns" the specified stream.
\retval true The object "owns" the stream and will destroy it upon
destruction.
\retval false The object does not own the stream.
\see SetOwnsStream()
*/
/*!
\fn void BBufferIO::SetOwnsStream(bool owns_stream)
\brief Set the \c owns_stream property of the object.
\param owns_stream If you pass \c true, the object will delete the stream
upon destruction, if you pass \c false it will not.
\return The size of the buffer allocated by the object.
*/
/*!
\fn void BBufferIO::PrintToStream() const
\brief Print the object to stdout.
/*!
\fn bool BBufferIO::OwnsStream() const
\brief Tell if the BBufferIO object "owns" the specified stream.
\retval true The object "owns" the stream and will destroy it upon
destruction.
\retval false The object does not own the stream.
\see SetOwnsStream()
*/
/*!
\fn void BBufferIO::SetOwnsStream(bool owns_stream)
\brief Set the \c owns_stream property of the object.
\param owns_stream If you pass \c true, the object will delete the stream
upon destruction, if you pass \c false it will not.
*/
/*!
\fn void BBufferIO::PrintToStream() const
\brief Print the object to stdout.
*/
docs/user/support/DataIO.dox
+294 -248
View File
@@ -1,424 +1,470 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Stefano Ceccherini ([email protected])
* Authors:
* Stefano Ceccherini, [email protected]
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/DataIO.h rev 17981
* /trunk/src/kits/support/DataIO.cpp rev 20510
* headers/os/support/DataIO.h rev 17981
* src/kits/support/DataIO.cpp rev 20510
*/
/*!
\file DataIO.h
\brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes.
\file DataIO.h
\ingroup support
\ingroup libbe
\brief Defines abstract BDataIO and BPositionIO and the derived BMallocIO and BMemoryIO classes.
Pure virtual BDataIO and BPositioIO classes provide
the protocol for Read()/Write()/Seek().
Pure virtual BDataIO and BPositioIO classes provide
the protocol for Read()/Write()/Seek().
BMallocIO and BMemoryIO classes implement the protocol,
as does BFile in the Storage Kit.
BMallocIO and BMemoryIO classes implement the protocol,
as does BFile in the Storage Kit.
*/
///// BDataIO /////
/*!
\class BDataIO
\ingroup support
\ingroup libbe
\brief Abstract interface for objects that provide read and write access to
data.
\class BDataIO
\ingroup support
\ingroup libbe
\brief Abstract interface for objects that provide read and write access to
data.
The interface provided by this class applies to objects or data that are
limited to reading and writing data. Classes derived from this class should
reimplement both the Read() and Write() method from this class.
The interface provided by this class applies to objects or data that are
limited to reading and writing data. Classes derived from this class should
re-implement both the Read() and Write() method from this class.
Candidates of types of data or objects that should be derived from this class
are probably broadcasting media streams (which don't support reading at a
certain point in the data) or network streams that output data continously.
Objects and data that support more advanced operations like seeking or
reading at writing at defined positions should derive their classes from
BPositionIO, which inherits this class.
Candidates of types of data or objects that should be derived from this class
are probably broadcasting media streams (which don't support reading at a
certain point in the data) or network streams that output data continuously.
Objects and data that support more advanced operations like seeking or
reading at writing at defined positions should derive their classes from
BPositionIO, which inherits this class.
*/
/*!
\fn BDataIO::BDataIO()
\brief This constructor does nothing.
\fn BDataIO::BDataIO()
\brief This constructor does nothing.
*/
/*!
\fn BDataIO::~BDataIO()
\brief This destructor does nothing.
\fn BDataIO::~BDataIO()
\brief This destructor does nothing.
*/
/*!
\fn virtual ssize_t BDataIO::Read(void *buffer, size_t size) = 0
\brief Pure virtual to read data.
Your implementation should copy data into \c buffer, with the maximum size
of \c size.
\return You should return the amount of bytes actually read, or an error code
/*!
\fn virtual ssize_t BDataIO::Read(void *buffer, size_t size) = 0
\brief Pure virtual to read data.
Your implementation should copy data into \c buffer, with the maximum size
of \c size.
\return You should return the amount of bytes actually read, or an error code
in case of failure.
*/
/*!
\fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size) = 0
\brief Pure virtual to write data.
Your implementation should copy data from \c buffer, with the maximum size
of \c size.
\return You should return the amount of bytes actually written, or an error
/*!
\fn virtual ssize_t BDataIO::Write(const void *buffer, size_t size) = 0
\brief Pure virtual to write data.
Your implementation should copy data from \c buffer, with the maximum size
of \c size.
\return You should return the amount of bytes actually written, or an error
code in case of failure.
*/
//////////// BPositionIO
/*!
\class BPositionIO
\ingroup support
\ingroup libbe
\brief Abstract interface that provides advanced read, write and seek access
to data.
\class BPositionIO
\ingroup support
\ingroup libbe
\brief Abstract interface that provides advanced read, write and seek access
to data.
The interface of this object applies to objects or data that allows
position-aware reading and writing of data. Classes that derive from this
class should at least reimplement ReadAt(), WriteAt(), Seek(), Position(),
SetSize() and GetSize() methods.
The interface of this object applies to objects or data that allows
position-aware reading and writing of data. Classes that derive from this
class should at least re-implement ReadAt(), WriteAt(), Seek(), Position(),
SetSize() and GetSize() methods.
A good example of a form of data that can derive from this object, are files.
The BFile class derives from BPositionIO and provides this interface to
files. If your object or data only supports linear reading and writing,
consider deriving from the baseclass BDataIO.
A good example of a form of data that can derive from this object, are files.
The BFile class derives from BPositionIO and provides this interface to
files. If your object or data only supports linear reading and writing,
consider deriving from the base-class BDataIO.
A final note, from BDataIO this class inherits Read() and Write(). The
default implementation is to read or write the data at the current position
indicated by Position(). Reimplement the methods if you require a different
behaviour.
A final note, from BDataIO this class inherits Read() and Write(). The
default implementation is to read or write the data at the current position
indicated by Position(). Re-implement the methods if you require a different
behavior.
*/
/*!
\fn BPositionIO::BPositionIO()
\brief This constructor does nothing.
\fn BPositionIO::BPositionIO()
\brief This constructor does nothing.
*/
/*!
\fn virtual BPositionIO::~BPositionIO()
\brief This destructor does nothing.
\fn virtual BPositionIO::~BPositionIO()
\brief This destructor does nothing.
*/
/*!
\fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size)
\brief Read data from current position.
This method is derived from BDataIO. The default implementation reads data
from the current position of the cursor, pointed at by Position(). If you
require different behaviour, please look at BDataIO::Read() for what is
expected of this method.
/*!
\fn virtual ssize_t BPositionIO::Read(void *buffer, size_t size)
\brief Read data from current position.
This method is derived from BDataIO. The default implementation reads data
from the current position of the cursor, pointed at by Position(). If you
require different behaviour, please look at BDataIO::Read() for what is
expected of this method.
*/
/*!
\fn virtual ssize_t BPositionIO::Write(const void *buffer, size_t size)
\brief Write data to the current position.
This method is derived from BDataIO. The default implementation writes data
to the current position of the cursor, pointed at by Position(). If you
require different behaviour, please look at BDataIO::Write() for what is
expected of this method.
/*!
\fn virtual ssize_t BPositionIO::Write(const void *buffer, size_t size)
\brief Write data to the current position.
This method is derived from BDataIO. The default implementation writes data
to the current position of the cursor, pointed at by Position(). If you
require different behaviour, please look at BDataIO::Write() for what is
expected of this method.
*/
/*!
\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0
\brief Pure virtual to read data from a certain position.
\fn virtual ssize_t BPositionIO::ReadAt(off_t position, void *buffer, size_t size) = 0
\brief Pure virtual to read data from a certain position.
Your implementation should copy data from the position indicated by
\a position into the \a buffer with the maximum size of \a size.
Your implementation should copy data from the position indicated by
\a position into the \a buffer with the maximum size of \a size.
\return The amount of bytes actually read, or an error code.
\return The amount of bytes actually read, or an error code.
*/
/*!
\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0
\brief Pure virtual to write data to a certain position.
\fn virtual ssize_t BPositionIO::WriteAt(off_t position, const void *buffer, size_t size) = 0
\brief Pure virtual to write data to a certain position.
Your implementation should copy data from \a buffer to the position indicated
by \a buffer with the maximum size of \a size.
Your implementation should copy data from \a buffer to the position indicated
by \a buffer with the maximum size of \a size.
\return The amount of bytes actually written, or an error code.
\return The amount of bytes actually written, or an error code.
*/
/*!
\fn virtual off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0
\brief Pure virtual to move the cursor to a certain position.
\fn virtual off_t BPositionIO::Seek(off_t position, uint32 seekMode) = 0
\brief Pure virtual to move the cursor to a certain position.
Your implementation should move the position of the cursor to the provided
point. What this actually means, depends on your object or data.
Your implementation should move the position of the cursor to the provided
point. What this actually means, depends on your object or data.
\param position An integer that defines a position.
\param seekMode You will get one of the following values:
\param position An integer that defines a position.
\param seekMode You will get one of the following values:
- \c SEEK_SET Set the cursor to the position indicated by \c position.
- \c SEEK_END Set the cursor to the end of the buffer, and go
\c position beyond that.
- \c SEEK_CUR Set the cursor the the current position plus \c position.
\return The new position.
\return The new position.
*/
/*!
\fn virtual off_t BPositionIO::Position() const = 0
\brief Pure virtual to return the current position of the cursor.
\return Your implementation should return the current position of the cursor.
/*!
\fn virtual off_t BPositionIO::Position() const = 0
\brief Pure virtual to return the current position of the cursor.
\return Your implementation should return the current position of the cursor.
*/
/*!
\fn virtual status_t BPositionIO::SetSize(off_t size)
\brief Set the size of the object or data.
\fn virtual status_t BPositionIO::SetSize(off_t size)
\brief Set the size of the object or data.
The default implementation returns \c B_ERROR. If your object or data allows
the size to be changed, reimplement this method.
The default implementation returns \c B_ERROR. If your object or data allows
the size to be changed, reimplement this method.
\return Return \c B_OK if everything succeeded, else return the appropriate
\return Return \c B_OK if everything succeeded, else return the appropriate
error code.
*/
/*!
\fn virtual status_t BPositionIO::GetSize(off_t* size) const
\brief Get the size of the object or data.
\fn virtual status_t BPositionIO::GetSize(off_t* size) const
\brief Get the size of the object or data.
The default implementation uses Seek() with the \c SEEK_END flag to
determine the size of the buffer. If your data or object has a different way
of determining size, reimplement this method.
The default implementation uses Seek() with the \c SEEK_END flag to
determine the size of the buffer. If your data or object has a different way
of determining size, reimplement this method.
Please check that NULL is not passed into \c size if you reimplement it in
your class.
Please check that NULL is not passed into \c size if you reimplement it in
your class.
\param[out] size The size of the object is put into this parameter.
\return This method returns \c B_OK on success or an error code on error.
\see Seek()
\param[out] size The size of the object is put into this parameter.
\return This method returns \c B_OK on success or an error code on error.
\see Seek()
*/
//////////// BMemoryIO
/*!
\class BMemoryIO
\ingroup support
\ingroup libbe
\brief A BPositionIO derived class that works on memory buffers.
\class BMemoryIO
\ingroup support
\ingroup libbe
\brief A BPositionIO derived class that works on memory buffers.
This class is used if you require access that confirms to the BPositionIO
interface on memory buffers that you created. If you would like to use that
interface on new buffers, have a look at BMallocIO.
This class is used if you require access that confirms to the BPositionIO
interface on memory buffers that you created. If you would like to use that
interface on new buffers, have a look at BMallocIO.
This class is particularly useful if you would like to use a class or method
that are written to make use of the BPositionIO interface. It might also
be used for 'secure' reading and writing from buffers, since this class
automatically checks the bounds of anything you might want to do.
This class is particularly useful if you would like to use a class or method
that are written to make use of the BPositionIO interface. It might also
be used for 'secure' reading and writing from buffers, since this class
automatically checks the bounds of anything you might want to do.
This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
Position() interface from BPositionIO.
This class reimplements the Read(), Write(), ReadAt(), Writeat(), Seek() and
Position() interface from BPositionIO.
*/
/*!
\fn BMemoryIO::BMemoryIO(void *data, size_t length)
\brief Create a read/write object.
\param data A pointer to the buffer to adopt.
\param length The size of the buffer.
\see BMemoryIO(const void *buffer, size_t length) for a read-only
/*!
\fn BMemoryIO::BMemoryIO(void *data, size_t length)
\brief Create a read/write object.
\param data A pointer to the buffer to adopt.
\param length The size of the buffer.
\see BMemoryIO(const void *buffer, size_t length) for a read-only
implementation.
*/
/*!
\fn BMemoryIO::BMemoryIO(const void *buffer, size_t length)
\brief Create a read-only object.
\param buffer A pointer to the \c const (read-only) buffer to adopt.
\param length The size of the buffer.
\see BMemoryIO(void *buffer, size_t length) for a read-write implementation.
/*!
\fn BMemoryIO::BMemoryIO(const void *buffer, size_t length)
\brief Create a read-only object.
\param buffer A pointer to the \c const (read-only) buffer to adopt.
\param length The size of the buffer.
\see BMemoryIO(void *buffer, size_t length) for a read-write implementation.
*/
/*!
\fn BMemoryIO::~BMemoryIO()
\brief The destructor does nothing.
\fn BMemoryIO::~BMemoryIO()
\brief The destructor does nothing.
*/
/*!
\fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read from a given position.
\param[in] pos The offset where to start reading data.
\param[out] buffer The buffer to copy the read bytes into.
\param[in] size The size of the \a buffer.
\return The amount of read bytes or an error code.
\retval B_BAD_VALUE The position is less than zero or the buffer given on
/*!
\fn ssize_t BMemoryIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read from a given position.
\param[in] pos The offset where to start reading data.
\param[out] buffer The buffer to copy the read bytes into.
\param[in] size The size of the \a buffer.
\return The amount of read bytes or an error code.
\retval B_BAD_VALUE The position is less than zero or the buffer given on
construction is invalid.
*/
/*!
\fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write at a given position.
\param pos The offset to write to.
\param buffer The buffer to copy the bytes from.
\param size The number of bytes to write.
\return The amount of bytes written or an error code.
\retval B_NOT_ALLOWED The object is constructed as a read-only object.
\retval B_BAD_VALUE The position is less than zero or the buffer given on
/*!
\fn ssize_t BMemoryIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write at a given position.
\param pos The offset to write to.
\param buffer The buffer to copy the bytes from.
\param size The number of bytes to write.
\return The amount of bytes written or an error code.
\retval B_NOT_ALLOWED The object is constructed as a read-only object.
\retval B_BAD_VALUE The position is less than zero or the buffer given on
construction is invalid.
*/
/*!
\fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode)
\brief Move the cursor to a given position.
\param position The position to move the cursor to.
\param seek_mode The mode determines where the cursor is placed.
/*!
\fn off_t BMemoryIO::Seek(off_t position, uint32 seek_mode)
\brief Move the cursor to a given position.
\param position The position to move the cursor to.
\param seek_mode The mode determines where the cursor is placed.
Possibilities:
- \c SEEK_SET The cursor is set to \a position.
- \c SEEK_CUR The \a position is added to the current position of the
cursor.
- \c SEEK_END The cursor is put at the end of the data, plus
\a position added to it.
\return The new position.
\return The new position.
*/
/*!
\fn off_t BMemoryIO::Position() const
\brief Return the current position.
\fn off_t BMemoryIO::Position() const
\brief Return the current position.
*/
/*!
\fn status_t BMemoryIO::SetSize(off_t size)
\brief Resize the buffer.
\fn status_t BMemoryIO::SetSize(off_t size)
\brief Resize the buffer.
This method does not actually resize the buffer. If the new size is greater
than the size of the buffer, resizing will fail. It will only succeed if the
new size is less than the size of the buffer. The buffer itself will not be
resized though.
This method does not actually resize the buffer. If the new size is greater
than the size of the buffer, resizing will fail. It will only succeed if the
new size is less than the size of the buffer. The buffer itself will not be
resized though.
This method might be useful in some cases. If the buffer is larger than the
data it holds, changing the size will enable you to use the Seek() method
with the flag \c SEEK_END and not get an error if you read or write from
that position, since you actually have a buffer at the end.
This method might be useful in some cases. If the buffer is larger than the
data it holds, changing the size will enable you to use the Seek() method
with the flag \c SEEK_END and not get an error if you read or write from
that position, since you actually have a buffer at the end.
\retval B_OK The buffer is resized.
\retval B_NOT_ALLOWED The buffer is read-only.
\retval B_ERROR The \c size is larger than the size of the buffer.
\retval B_OK The buffer is resized.
\retval B_NOT_ALLOWED The buffer is read-only.
\retval B_ERROR The \c size is larger than the size of the buffer.
*/
//////////// BMallocIO
/*!
\class BMallocIO
\ingroup support
\ingroup libbe
\brief A BPositionIO derived class that creates a memory buffer.
\class BMallocIO
\ingroup support
\ingroup libbe
\brief A BPositionIO derived class that creates a memory buffer.
This class creates a memory buffer and provides a BPositionIO interface to
work on it. The memory buffer grows and shrinks automatically.
This is especially useful if you want to use a method or function that
works on an object derived from BPositionIO and you want to do something with
the resulting data, or it could be useful if you want to read and write to
memory in a safe way, since this class has boundary checking.
This class creates a memory buffer and provides a BPositionIO interface to
work on it. The memory buffer grows and shrinks automatically.
This is especially useful if you want to use a method or function that
works on an object derived from BPositionIO and you want to do something with
the resulting data, or it could be useful if you want to read and write to
memory in a safe way, since this class has boundary checking.
BMallocIO allocates a buffer based on a certain blocksize. This provides a
mechanism that will prevent it from needing to allocate new memory too often.
The default blocksize is 256 bytes, you can change it with SetBlockSize(). If
you are sure you are going to use a bigger buffer, change the blocksize so
that you won't have to allocate more memory too often, especially if you use
this class in performance-critical code.
BMallocIO allocates a buffer based on a certain block size. This provides a
mechanism that will prevent it from needing to allocate new memory too often.
The default block size is 256 bytes, you can change it with SetBlockSize(). If
you are sure you are going to use a bigger buffer, change the block size so
that you won't have to allocate more memory too often, especially if you use
this class in performance-critical code.
If you require a BPositionIO derived object that works on buffers you
provide, have a look at BMemoryIO.
If you require a BPositionIO derived object that works on buffers you
provide, have a look at BMemoryIO.
*/
/*!
\fn BMallocIO::BMallocIO()
\brief Create a new memory buffer with block size 256.
\see SetBlockSize()
\fn BMallocIO::BMallocIO()
\brief Create a new memory buffer with block size 256.
\see SetBlockSize()
*/
/*!
\fn BMallocIO::~BMallocIO()
\brief Destroy the object and free the internal buffer.
\fn BMallocIO::~BMallocIO()
\brief Destroy the object and free the internal buffer.
*/
/*!
\fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read data at a certain position.
\param[in] pos Offset into the data where to read from.
\param[out] buffer The buffer to copy the read bytes in.
\param [in] size Size of the buffer.
\return The number of read bytes, or \c B_BAD_VALUE if
/*!
\fn ssize_t BMallocIO::ReadAt(off_t pos, void *buffer, size_t size)
\brief Read data at a certain position.
\param[in] pos Offset into the data where to read from.
\param[out] buffer The buffer to copy the read bytes in.
\param [in] size Size of the buffer.
\return The number of read bytes, or \c B_BAD_VALUE if
the provided \a buffer is invalid.
*/
/*!
\fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write data to a certain position.
\param pos Offset into the data where to write to.
\param buffer The buffer to copy from.
\param size The size of the buffer.
\return The number of bytes written or \c B_BAD_VALUE if the provided.
\a buffer is invalid.
/*!
\fn ssize_t BMallocIO::WriteAt(off_t pos, const void *buffer, size_t size)
\brief Write data to a certain position.
\param pos Offset into the data where to write to.
\param buffer The buffer to copy from.
\param size The size of the buffer.
\return The number of bytes written or \c B_BAD_VALUE if the provided.
\a buffer is invalid.
*/
/*!
\fn off_t BMallocIO::Seek(off_t position, uint32 seekMode)
\brief Move the cursor to a given position.
\param position The position to move the cursor to.
\param seekMode The mode determines where the cursor is placed. Possibilities:
/*!
\fn off_t BMallocIO::Seek(off_t position, uint32 seekMode)
\brief Move the cursor to a given position.
\param position The position to move the cursor to.
\param seekMode The mode determines where the cursor is placed. Possibilities:
- \c SEEK_SET The cursor is set to \a position.
- \c SEEK_CUR The \c position is added to the current position of the
cursor.
- \c SEEK_END The cursor is put at the end of the data, plus
\a position added to it.
\return The new position.
\return The new position.
*/
/*!
\fn off_t BMallocIO::Position() const
\brief Return the position of the cursor.
\fn off_t BMallocIO::Position() const
\brief Return the position of the cursor.
*/
/*!
\fn status_t BMallocIO::SetSize(off_t size)
\brief Change the size of the buffer.
\fn status_t BMallocIO::SetSize(off_t size)
\brief Change the size of the buffer.
This method changes the size of the current buffer. If \a size is smaller
than the current size, the data will be cleared.
This method changes the size of the current buffer. If \a size is smaller
than the current size, the data will be cleared.
\param size The new size of the buffer.
\retval B_OK Resizing the data succeeded.
\retval B_NO_MEMORY Failed to allocate the necessary memory.
\param size The new size of the buffer.
\retval B_OK Resizing the data succeeded.
\retval B_NO_MEMORY Failed to allocate the necessary memory.
*/
/*!
\fn void BMallocIO::SetBlockSize(size_t blockSize)
\brief Change the block size to a certain value.
\fn void BMallocIO::SetBlockSize(size_t blockSize)
\brief Change the block size to a certain value.
This class allocates memory in blocks. If you are in performance-critical
code you might want to tweak this setting to create a better performance in
case you know you are going to allocate more than the default blocksize of
256.
This class allocates memory in blocks. If you are in performance-critical
code you might want to tweak this setting to create a better performance in
case you know you are going to allocate more than the default blocksize of
256.
\param blockSize The new block size.
\param blockSize The new block size.
*/
/*!
\fn const void *BMallocIO::Buffer() const
\brief Return a pointer to the internal buffer.
\fn const void *BMallocIO::Buffer() const
\brief Return a pointer to the internal buffer.
As with any pointer to internal buffers the Haiku API exposes,
make sure you don't change anything since it doesn't belong to you.
As with any pointer to internal buffers the Haiku API exposes,
make sure you don't change anything since it doesn't belong to you.
*/
/*!
\fn size_t BMallocIO::BufferLength() const
\brief Return the number of bytes in the buffer.
\fn size_t BMallocIO::BufferLength() const
\brief Return the number of bytes in the buffer.
This number doesn't have to be the same size as the buffer is. Because memory
is allocated in blocks the actual size of the buffer may be greater, but this
method only returns the number of bytes that are actually used.
This number doesn't have to be the same size as the buffer is. Because memory
is allocated in blocks the actual size of the buffer may be greater, but this
method only returns the number of bytes that are actually used.
*/
docs/user/support/Flattenable.dox
+157 -140
View File
@@ -1,171 +1,188 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation written by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk <[email protected]>
*
* Corresponds to:
* /trunk/headers/os/support/Flattenable.h rev 19972
* /trunk/src/kits/support/Flattenable.cpp rev 12963
* headers/os/support/Flattenable.h rev 19972
* src/kits/support/Flattenable.cpp rev 12963
*/
/*!
\file Flattenable.h
\brief Provides the BFlattenable interface
*/
/*!
\class BFlattenable
\ingroup support
\ingroup libbe
\brief Interface for classes that can flatten and unflatten themselves to
a stream of bytes.
It is convenient that objects can be stored as a flat stream of bytes. In
this way, they can be written to disk, exchanged between applications or send
over networks. This ability, which is known in many other programming
languages as marshalling, is not native in C++. The Haiku API has created a
universal interface that classes have if they are able to be flattened. This
class defines the interface. This class does nothing on its own, and
therefore contains pure virtuals. By inheriting this class and inmplementing
the methods in your own class, you will be able to use your objects as
flattenable objects throughout the Haiku API.
Flattened objects can be used for example when sending messages within an
application or between applications. The BMessage class uses the interface
to store and transmit custom classes.
If you want to be able to flatten your objects, you will need to implement
various methods. Flatten() and Unflatten() are where the magic happen. These
methods handle the actual flattening and unflattening. To identify flattened
data in for example BMessage, the object has a type_code. Type codes are
four byte long integers. You can choose to flatten to one of the existing
types, if you are certain that you are compatible to those, but you'll
usually define your own type. Your best option is by using a multicharacter
constant, such as 'STRI'. Implement TypeCode() to return the type you
support. Implement FlattenedSize() to make sure that other objects can
provide the right buffers. Implement IsFixedSize() to return whether your
objects always store to a fixed size.
See the following example:
\code
\file Flattenable.h
\ingroup support
\ingroup libbe
\brief Provides the BFlattenable interface
*/
/*!
\class BFlattenable
\ingroup support
\ingroup libbe
\brief Interface for classes that can flatten and unflatten themselves to
a stream of bytes.
It is convenient that objects can be stored as a flat stream of bytes. In
this way, they can be written to disk, exchanged between applications or send
over networks. This ability, which is known in many other programming
languages as marshalling, is not native in C++. The Haiku API has created a
universal interface that classes have if they are able to be flattened. This
class defines the interface. This class does nothing on its own, and
therefore contains pure virtuals. By inheriting this class and inmplementing
the methods in your own class, you will be able to use your objects as
flattenable objects throughout the Haiku API.
Flattened objects can be used for example when sending messages within an
application or between applications. The BMessage class uses the interface
to store and transmit custom classes.
If you want to be able to flatten your objects, you will need to implement
various methods. Flatten() and Unflatten() are where the magic happen. These
methods handle the actual flattening and unflattening. To identify flattened
data in for example BMessage, the object has a type_code. Type codes are
four byte long integers. You can choose to flatten to one of the existing
types, if you are certain that you are compatible to those, but you'll
usually define your own type. Your best option is by using a multicharacter
constant, such as 'STRI'. Implement TypeCode() to return the type you
support. Implement FlattenedSize() to make sure that other objects can
provide the right buffers. Implement IsFixedSize() to return whether your
objects always store to a fixed size.
See the following example:
\code
type_code CUSTOM_STRING_TYPE = 'CUST';
class CustomString : public BFlattenable
{
public:
char data[100];
char data[100];
// From BFlattenable
bool IsFixedSize() const { return false; };
type_code TypeCode() const { return CUSTOM_STRING_TYPE; };
ssize_t FlattenedSize() const { return strlen(data); };
status_t Flatten(void* buffer, ssize_t size) const
{
if ((strlen(data) + 1) < size)
return B_BAD_VALUE;
memcpy(buffer, data, size);
return B_OK;
};
status_t Unflatten(type_code code, const void* buffer, ssize_t size)
{
if (code != CUSTOM_STRING_TYPE)
return B_BAD_TYPE;
if (size > 100)
return B_NO_MEMORY;
memcpy(data, buffer, size);
return B_OK;
};
// From BFlattenable
bool IsFixedSize() const { return false; };
type_code TypeCode() const { return CUSTOM_STRING_TYPE; };
ssize_t FlattenedSize() const { return strlen(data); };
status_t Flatten(void* buffer, ssize_t size) const
{
if ((strlen(data) + 1) < size)
return B_BAD_VALUE;
memcpy(buffer, data, size);
return B_OK;
};
status_t Unflatten(type_code code, const void* buffer, ssize_t size)
{
if (code != CUSTOM_STRING_TYPE)
return B_BAD_TYPE;
if (size > 100)
return B_NO_MEMORY;
memcpy(data, buffer, size);
return B_OK;
};
};
\endcode
Have a look at TypeConstants.h for a list of all the types that the Haiku
API defines.
The Haiku API has a second interface for storing objects, which is with
BArchivable. BArchivable is for more complex cases. Instead of one flat
datastream, it stores an object in a BMessage. In that way you can reflect
internals of a class better. It also provides an interface for instantiating
objects, that is, for objects to restore themselves from a BMessage. In
essence, BArchivable is more suitable for objects that are alive. In short
BFlattenable is for data objects, BArchivable is for 'live' objects.
Other classes in the API that support flattening and unflattening are for
example BMessage, which enables you to conveniently write flattened data
to disk. Another example is BPath. Because of that you can store paths and
send them over via messages. Throughout the Haiku API you will find classes
that provide the flattening interface.
\endcode
Have a look at TypeConstants.h for a list of all the types that the Haiku
API defines.
The Haiku API has a second interface for storing objects, which is with
BArchivable. BArchivable is for more complex cases. Instead of one flat
datastream, it stores an object in a BMessage. In that way you can reflect
internals of a class better. It also provides an interface for instantiating
objects, that is, for objects to restore themselves from a BMessage. In
essence, BArchivable is more suitable for objects that are alive. In short
BFlattenable is for data objects, BArchivable is for 'live' objects.
Other classes in the API that support flattening and unflattening are for
example BMessage, which enables you to conveniently write flattened data
to disk. Another example is BPath. Because of that you can store paths and
send them over via messages. Throughout the Haiku API you will find classes
that provide the flattening interface.
*/
/*!
\fn virtual bool BFlattenable::IsFixedSize() const = 0
\brief Pure virtual that should return whether or not flattened objects of
this type always have a fixed size.
*/
/*!
\fn virtual type_code BFlattenable::TypeCode() const = 0
\brief Pure virtual that should return which type_code this class flattens
to.
\return Either one of the existing typecodes, found in TypeConstants.h,
<em>if your class actually is compatible to those formats</em>, or a custom
four byte integer constant.
\fn virtual bool BFlattenable::IsFixedSize() const
\brief Pure virtual that should return whether or not flattened objects of
this type always have a fixed size.
*/
/*!
\fn virtual ssize_t BFlattenable::FlattenedSize() const = 0
\brief Pure virtual that should return the size of the flattened object in
bytes.
*/
/*!
\fn virtual status_t BFlattenable::Flatten(void* buffer, ssize_t size) const = 0
\brief Pure virtual that should flatten the object into the supplied
\a buffer.
Please make sure that you check that the supplied buffer is not a \c NULL
pointer. Also make sure that the size of the flattened object does isn't
larger than the size of the buffer.
\param buffer The buffer to flatten in.
\param size The size of the buffer.
\retval B_OK The object was flattened.
\retval B_NO_MEMORY The buffer was smaller than required.
\retval B_BAD_VALUE The buffer was a \c NULL pointer.
\fn virtual type_code BFlattenable::TypeCode() const
\brief Pure virtual that returns the type_code this class flattens to.
\return Either one of the existing typecodes found in TypeConstants.h
if your class actually is compatible to those formats, or a
custom four-byte integer constant if not.
*/
/*!
\fn bool BFlattenable::AllowsTypeCode(type_code code) const
\brief Return whether or not the supplied type_code is supported.
This default implementation checks the \a code argument against the type_code
returned by TypeCode().
\param code The type_code constant you want to check for.
\retval true The type_code is supported.
\retval false The type_code is not supported.
*/
/*!
\fn virtual status_t BFlattenable::Unflatten(type_code code, const void* buffer, ssize_t size) = 0
\brief Pure virtual that should unflatten the buffer and put the contents
into the current object.
Make sure that the supplied buffer is not \c NULL and that you actually
support the typecode.
\param code The type_code this data is.
\param buffer The buffer to unflatten the data from.
\param size The size of the data.
\retval B_OK The object is unflattened.
\retval B_BAD_VALUE The \a buffer pointer is \c NULL or the data is invalid.
\retval B_BAD_TYPE You don't support data with this \a code.
\fn virtual ssize_t BFlattenable::FlattenedSize() const
\brief Pure virtual that should return the size of the flattened object in
bytes.
*/
/*!
\fn virtual BFlattenable::~BFlattenable()
\brief Destructor. Does nothing.
\fn virtual status_t BFlattenable::Flatten(void* buffer, ssize_t size) const
\brief Pure virtual that should flatten the object into the supplied
\a buffer.
Please make sure that you check that the supplied buffer is not a \c NULL
pointer. Also make sure that the size of the flattened object does isn't
larger than the size of the buffer.
\param buffer The buffer to flatten in.
\param size The size of the buffer.
\retval B_OK The object was flattened.
\retval B_NO_MEMORY The buffer was smaller than required.
\retval B_BAD_VALUE The buffer was a \c NULL pointer.
*/
/*!
\fn bool BFlattenable::AllowsTypeCode(type_code code) const
\brief Get whether or not the supplied type_code is supported.
This default implementation checks the \a code argument against the type_code
returned by TypeCode().
\param code The type_code constant you want to check for.
\returns Whether or not the supplied type_code is supported.
\retval true The type_code is supported.
\retval false The type_code is not supported.
*/
/*!
\fn virtual status_t BFlattenable::Unflatten(type_code code,
const void* buffer, ssize_t size)
\brief Pure virtual that should unflatten the buffer and put the contents
into the current object.
Make sure that the supplied buffer is not \c NULL and that you actually
support the typecode.
\param code The type_code this data is.
\param buffer The buffer to unflatten the data from.
\param size The size of the data.
\returns A status code.
\retval B_OK The object is unflattened.
\retval B_BAD_VALUE The \a buffer pointer is \c NULL or the data is invalid.
\retval B_BAD_TYPE You don't support data with this \a code.
*/
/*!
\fn virtual BFlattenable::~BFlattenable()
\brief Destructor. Does nothing.
*/
docs/user/support/List.dox
+44 -84
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
@@ -11,13 +11,15 @@
* John Drinkwater, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/List.h rev 19972
* /trunk/src/kits/support/List.cpp rev 18649
* headers/os/support/List.h rev 19972
* src/kits/support/List.cpp rev 18649
*/
/*!
\file List.h
\ingroup support
\ingroup libbe
\brief Defines the BList class.
*/
@@ -28,37 +30,36 @@
\ingroup libbe
\brief An ordered container that is designed to hold generic \c void*
objects.
This class is designed to be used for a variety of tasks. Unlike similar
implementations in other libraries, this class is not based on templates
and as such is inherently not typed. So it will be the job of the programmer
to make sure proper data is entered since the compiler cannot check this by
itself.
BList contains a list of items that will grow and shrink depending on how
many items are in it. So you will not have to do any of the memory
management nor any ordering. These properties makes it useful in a whole
range of situations such as the interface kit within the BListView class.
A note on the ownership of the objects might come in handy. BList never
assumes ownership of the objects. As such, removing items from the list will
only remove the entries from the list; it will not delete the items
themselves. Similarly, you should also make sure that before you might
delete an object that is in a list, you will have to remove it from the list
first.
\warning This class is not thread-safe.
The class implements methods to add, remove, reorder, retrieve, and query
items as well as some advanced methods which let you perform a task on all
the items in the list.
*/
/*!
\fn BList::BList(int32 count = 20)
\brief Create a new list with a number of empty slots.
The memory management of this class allocates new memory per block. The
\c count parameter can be tweaked to determine the size of these blocks.
In general, if you know your list is only going to contain a certain number
@@ -68,49 +69,43 @@
large number of items, choose a higher value. Every time the memory is full,
all the items have to be copied into a new piece of allocated memory, which
is an expensive operation.
If you are unsure, you do not have to worry too much. Just make sure you do
not use a lot of lists, and as long as the list is not used in one of the
performance critical parts of the code, you are safe to go with the default
values.
\param count The size of the blocks allocated in memory.
*/
/*!
\fn BList::BList(const BList& anotherList)
\brief Copy constructor. Copy a complete list into this one.
*/
/*!
\fn BList::~BList()
\brief Destroy the list.
Please note that as BList does not assume ownership of the objects,
only the list will be freed, not the objects that are held in it.
*/
/*!
\fn BList& BList::operator=(const BList &list)
\brief Copy another list into this object.
*/
/*!
\name Adding and Removing Items
*/
//! @{
/*!
\fn bool BList::AddItem(void *item, int32 index)
\brief Add an item at a certain position.
\param item The item to add.
\param index The place in the list.
\retval true The item was added.
@@ -119,25 +114,23 @@
\see AddItem(void *item)
*/
/*!
\fn bool BList::AddItem(void *item)
\brief Append an item to the list.
\param item The item to add.
\retval true The item was appended.
\retval false Item was not appended, since resizing the list failed.
\see AddItem(void *item, int32 index)
*/
/*!
\fn bool BList::AddList(const BList *list, int32 index)
\brief Add items from another list to this list at a certain position.
Note that the \a list parameter is \c const, so the original list will not
be altered.
\param list The list to be added.
\param index The position in the current list where the new item(s) should
be put.
@@ -147,14 +140,13 @@
\see AddList(const BList *list)
*/
/*!
\fn bool BList::AddList(const BList *list)
\brief Append a list to this list.
Note that the \a list parameter is a \c const, so the original list will not
be altered.
\param list The list to be appended.
\retval true The list was appended.
\retval false Failed to append the list, due to the fact that resizing of
@@ -162,160 +154,142 @@
\see AddList(const BList *list, int32 index)
*/
/*!
\fn bool BList::RemoveItem(void *item)
\brief Remove an item from the list.
\param item The item that should be removed.
\retval true The item was found and removed.
\retval false The item was not in this list and thus not removed.
\see RemoveItem(int32 index)
*/
/*!
\fn void * BList::RemoveItem(int32 index)
\brief Remove the item at \a index from the list.
\param index The item that should be removed.
\return The pointer to the item that was removed, or \c NULL in case the
index was invalid.
\see RemoveItem(void *item)
*/
/*!
\fn bool BList::RemoveItems(int32 index, int32 count)
\brief Remove a number of items starting at a certain position.
If the count parameter is larger than the number of items in the list,
all the items from the offset to the end will be removed.
\param index The offset in the list where removal should start.
\param count The number of items to remove.
\retval true Removal succeeded.
\retval false Failed to remove the items because the index was invalid.
*/
/*!
\fn bool BList::ReplaceItem(int32 index, void *newItem)
\brief Replace an item with another one.
\param index The offset in the list where to put the item.
\param newItem The new item to put in the list.
\retval true Item replaced.
\retval false The index was invalid.
*/
/*!
\fn void BList::MakeEmpty()
\brief Clear all the items from the list.
Please note that this does not free the items.
*/
//! @}
/*!
\name Reordering Items
*/
//! @{
/*!
\fn void BList::SortItems(int (*compareFunc)(const void *, const void *))
\brief Sort the items with the use of a supplied comparison function.
The function should take two \c const pointers as arguments and should
return an integer.
For an example, see the Compare(const BString *, const BString *) function.
*/
/*!
\fn bool BList::SwapItems(int32 indexA, int32 indexB)
\brief Swap two items.
\param indexA The first item.
\param indexB The second item.
\retval true Swap succeeded.
\retval false Swap failed because one of the indexes was invalid.
*/
/*!
\fn bool BList::MoveItem(int32 fromIndex, int32 toIndex)
\brief Move an item to a new place
This moves a list item from position A to position B, moving the appropriate
block of list elements to make up for the move. For example, in the array:
\verbatim
A B C D E F G H I J
\endverbatim
Moving 1(B)->6(G) would result in this:
\verbatim
A C D E F G B H I J
\endverbatim
\param fromIndex The original location.
\param toIndex The new location.
\retval true Move succeeded.
\retval false Move failed due to the indexes being invalid.
*/
//! @}
/*!
\name Retrieving Items
*/
//! @{
/*!
\fn void *BList::ItemAt(int32 index) const
\brief Get an item.
\param index The item to retrieve.
\return A pointer to the item in that position, or \c NULL if the index is
out of bounds.
\see ItemAtFast(int32 index) const
*/
/*!
\fn void *BList::FirstItem() const
\brief Get the first item.
\return A pointer to the first item or \c NULL if the list is empty.
\see LastItem() const
*/
/*!
\fn void *BList::ItemAtFast(int32 index) const
\brief Get an item.
This method does not perform any boundary checks when it retrieves an item.
Use this method in a performance critical area of your program where you are
sure you will not get an invalid item.
\return A pointer to the item.
*/
/*!
\fn void *BList::LastItem() const
\brief Get the last item.
@@ -323,18 +297,17 @@ A C D E F G B H I J
\see FirstItem() const
*/
/*!
\fn void *BList::Items() const
\brief Return the internal list of objects.
This method will return a pointer to the internal pointer list. This means
that you should be careful what you are doing, since you are working with
the internals of the class directly.
It is not a good idea to make any changes to the list, since that will mess
up the internal consistency.
\warning If there is anything you want, for which you need the list of
objects, please realize that that probably means that what you want to
do is a bad idea to begin with and that you should avoid this method.
@@ -343,75 +316,63 @@ A C D E F G B H I J
\return The internal list of pointers.
*/
//! @}
/*!
\name Querying for Items
*/
//! @{
/*!
\fn bool BList::HasItem(void *item) const
\brief Check if an item is in the list.
*/
/*!
\fn int32 BList::IndexOf(void *item) const
\brief Get the index of an item.
\return The index of the item, or -1 when the item is not in the list.
*/
/*!
\fn int32 BList::CountItems() const
\brief Get the number of items in the list.
*/
/*!
\fn bool BList::IsEmpty() const
\brief Check if there are items in the list.
*/
//! @}
/*!
\name Iterating over the List
*/
//! @{
/*!
\fn void BList::DoForEach(bool (*func)(void* item))
\brief Perform an action on every item in the list.
If one of the actions on the items fails it means that the \a func function
returned \c false and the processing of the list will be stopped.
\param func A function that takes a \c void* argument and returns a
boolean.
\see DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
*/
/*!
\fn void BList::DoForEach(bool (*func)(void* item, void* arg2), void *arg2)
\brief Perform an action on every item in the list with an argument.
If one of the actions on the items fails it means that the \a func function
returned \c false and the processing of the list will be stopped.
\param func A function with the first \c void* argument being the item
and the second \c void* being the argument that you supply. It should
return a boolean value on whether it succeeded or not.
@@ -419,5 +380,4 @@ A C D E F G B H I J
\see DoForEach(bool (*func)(void* item))
*/
//! @}
docs/user/support/Locker.dox
+139 -134
View File
@@ -1,203 +1,208 @@
/*
* Copyright 2007, Haiku, Inc. All Rights Reserved.
* Copyright 2007 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Documentation by:
* Niels Sascha Reedijk <[email protected]>
* Authors:
* Niels Sascha Reedijk, [email protected]
*
* Corresponds to:
* /trunk/headers/os/support/Locker.h rev 19972
* /trunk/src/kits/support/Locker.cpp rev 13826
* headers/os/support/Locker.h rev 19972
* src/kits/support/Locker.cpp rev 13826
*/
/*!
\file Locker.h
\brief Provides locking class BLocker.
\file Locker.h
\ingroup support
\ingroup libbe
\brief Provides locking class BLocker.
*/
/*!
\class BLocker
\ingroup support
\ingroup libbe
\brief Semaphore-type class for thread safety.
\class BLocker
\ingroup support
\ingroup libbe
\brief Semaphore-type class for thread safety.
The BLocker interface is not merely a wrapper around a semaphore, but it
also has two advantages. First of all, it implements a benaphore.
A benaphore is in some ways more speed efficient,
because before it uses the internal semaphore, it first checks against a
variable that is only operated on with atomic operations. Setting a variable
is a lot more efficient than acquiring a semaphore, thus this type of locking
is much prefered.
The BLocker interface is not merely a wrapper around a semaphore, but it
also has two advantages. First of all, it implements a benaphore.
A benaphore is in some ways more speed efficient,
because before it uses the internal semaphore, it first checks against a
variable that is only operated on with atomic operations. Setting a variable
is a lot more efficient than acquiring a semaphore, thus this type of locking
is much prefered.
It basically works as follows. Whenever you newly created BLocker object
recieves a locking request, it atomically sets the benaphore variable to
\c 1. Then only additional calls from different threads will utilize the
semaphore. You can imagine that in many cases where you protect
of data that \em might be accessed by two or more concurrent threads, but
the chances of it happening being very small, the benaphore benefits the
most from it's speed.
It basically works as follows. Whenever you newly created BLocker object
recieves a locking request, it atomically sets the benaphore variable to
\c 1. Then only additional calls from different threads will utilize the
semaphore. You can imagine that in many cases where you protect
of data that \em might be accessed by two or more concurrent threads, but
the chances of it happening being very small, the benaphore benefits the
most from it's speed.
The other feature of BLocker that improves basic semaphore handling is that
it allows for recursive locks. The following piece of code works with a
BLocker, but block inevitably with a semaphore. Let's pretend I call
The other feature of BLocker that improves basic semaphore handling is that
it allows for recursive locks. The following piece of code works with a
BLocker, but block inevitably with a semaphore. Let's pretend I call
\c Water():
\code
status_t
Flower::Grow(int length)
{
\code
status_t
Flower::Grow(int length)
{
if (fLock->Lock()) {
fLength += length;
fLock->Unlock();
return B_OK;
fLength += length;
fLock->Unlock();
return B_OK;
} else {
return B_ERROR;
return B_ERROR;
}
}
}
status_t
Flower::Water(int amount)
{
status_t
Flower::Water(int amount)
{
if (fLock->Lock()) {
status_t status = Grow(amount * 2);
fLock->Unlock();
return status;
status_t status = Grow(amount * 2);
fLock->Unlock();
return status;
} else {
return B_ERROR;
return B_ERROR;
}
}
\endcode
}
\endcode
This code would work because BLocker keeps track of the amount of lock
requests from the same thread. A normal semaphore would block in \c Grow()
because the semaphore would be acquired already. Please do make sure you
pair every Lock() with an Unlock() though, or you'll create a deadlock.
This code would work because BLocker keeps track of the amount of lock
requests from the same thread. A normal semaphore would block in \c Grow()
because the semaphore would be acquired already. Please do make sure you
pair every Lock() with an Unlock() though, or you'll create a deadlock.
*/
/*!
\fn BLocker::BLocker()
\brief Constructor.
\fn BLocker::BLocker()
\brief Constructor.
Create a new BLocker with the default name of <tt>some BLocker</tt>. This
BLocker will use the benaphore-style locking.
\note For debugging purposes, it's extremely convenient to actually give a
Create a new BLocker with the default name of <tt>some BLocker</tt>. This
BLocker will use the benaphore-style locking.
\note For debugging purposes, it's extremely convenient to actually give a
name to the object. In case of a deadlock, it's easier to track down which
BLocker object might have caused the problems.
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
*/
/*!
\fn BLocker::BLocker(const char* name)
\brief Constructor.
Create a new BLocker with benaphore-style locking.
\param name A NULL-terminated string that contains the name of the semaphore.
Note that the length of the names are limited to B_OS_NAME_LENGTH constant,
which includes the \c \\0 character.
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
\fn BLocker::BLocker(const char* name)
\brief Constructor.
Create a new BLocker with benaphore-style locking.
\param name A NULL-terminated string that contains the name of the
semaphore. Note that the length of the names are limited to
\c B_OS_NAME_LENGTH constant, which includes the \c \\0
character.
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
*/
/*!
\fn BLocker::BLocker(bool benaphoreStyle)
\brief Constructor.
Creates a BLocker with the default name of <tt>some BLocker</tt>.
\note For debugging purposes, it's extremely convenient to actually give a
name to the object. In case of a deadlock, it's easier to track down which
BLocker object might have caused the problems.
\param benaphoreStyle If you pass \c true, the locker will be in benaphore
style (which is the default option for other constructors). If you pass
\c false, the object will completely rely on semaphores for it's
functioning.
\see BLocker(const char* name, bool benaphoreStyle) if you also want to set a
name.
\fn BLocker::BLocker(bool benaphoreStyle)
\brief Constructor.
Creates a BLocker with the default name of <tt>some BLocker</tt>.
\note For debugging purposes, it's extremely convenient to actually give a
name to the object. In case of a deadlock, it's easier to track down
which BLocker object might have caused the problems.
\param benaphoreStyle If you pass \c true, the locker will be in benaphore
style (which is the default option for other constructors). If you
pass \c false, the object will completely rely on semaphores for
it's functioning.
\see BLocker(const char* name, bool benaphoreStyle) if you also want
to set a name.
*/
/*!
\fn BLocker::BLocker(const char* name, bool benaphoreStyle)
\brief Constructor.
\param name A NULL-terminated string that contains the name of the semaphore.
Note that the length of the names are limited to B_OS_NAME_LENGTH constant,
which includes the \c \\0 character.
\param benaphoreStyle If you pass \c true, the locker will be in benaphore
style (which is the default option for other constructors). If you pass
\c false, the object will completely rely on semaphores for it's
functioning.
\fn BLocker::BLocker(const char* name, bool benaphoreStyle)
\brief Constructor.
\param name A NULL-terminated string that contains the name of the
semaphore. Note that the length of the names are limited to
\c B_OS_NAME_LENGTH constant, which includes the \c \\0
character.
\param benaphoreStyle If you pass \c true, the locker will be in benaphore
style (which is the default option for other constructors). If
you pass \c false, the object will completely rely on semaphores
for its functioning.
*/
/*!
\fn virtual BLocker::~BLocker()
\brief Destructor.
Release the internal semaphore. Because of this, any pending Lock() calls
from other threads be cancelled. The return code will be \c false for
those calls.
\fn virtual BLocker::~BLocker()
\brief Destructor.
Release the internal semaphore. Because of this, any pending Lock() calls
from other threads be cancelled. The return code will be \c false for
those calls.
*/
/*!
\fn bool BLocker::Lock()
\brief Add a lock request and block on it until we get it.
\retval true Lock acquired succesfully.
\retval false Failed to acquire the lock. Most probable cause is that the
object is deleted. This frees the semaphore and releases the pending Lock()
requests.
\see LockWithTimeout(bigtime_t timeout), Unlock()
\fn bool BLocker::Lock()
\brief Add a lock request and block on it until we get it.
\retval true Lock acquired succesfully.
\retval false Failed to acquire the lock. Most probable cause is that the
object is deleted. This frees the semaphore and releases the
pending Lock() requests.
\see LockWithTimeout(bigtime_t timeout), Unlock()
*/
/*!
\fn status_t BLocker::LockWithTimeout(bigtime_t timeout)
\brief Add a lock request and block until we get it or until it times out.
\param timeout This is a timeout in microseconds (one millionth of a second),
\e relative from now.
\see Lock(), Unlock()
\fn status_t BLocker::LockWithTimeout(bigtime_t timeout)
\brief Add a lock request and block until we get it or until it times out.
\param timeout This is a timeout in microseconds (one millionth of a
second) relative to now.
\see Lock(), Unlock()
*/
/*!
\fn void BLocker::Unlock(void)
\brief Release the lock that's currently held.
\fn void BLocker::Unlock(void)
\brief Release the lock that's currently held.
*/
/*!
\fn thread_id BLocker::LockingThread(void) const
\brief Return the \c thread_id of the thread that's currently holding the
lock.
\fn thread_id BLocker::LockingThread(void) const
\brief Return the \c thread_id of the thread that's currently holding the
lock.
*/
/*!
\fn bool BLocker::IsLocked(void) const
\brief Check if the calling thread is actually holding the lock.
\retval true The thread from which this method is called from is currently
\fn bool BLocker::IsLocked(void) const
\brief Check if the calling thread is actually holding the lock.
\retval true The thread from which this method is called from is currently
holding the lock.
\retval false The object is unlocked or the lock is held by another thread.
\retval false The object is unlocked or the lock is held by another thread.
*/
/*!
\fn int32 BLocker::CountLocks(void) const
\brief Return the number of recursive locks that are currently held.
\fn int32 BLocker::CountLocks(void) const
\brief Return the number of recursive locks that are currently held.
*/
/*!
\fn nt32 BLocker::CountLockRequests(void) const
\brief Return the number of threads with a pending lock request.
\fn nt32 BLocker::CountLockRequests(void) const
\brief Return the number of threads with a pending lock request.
*/
/*!
\fn sem_id BLocker::Sem(void) const
\brief Return the sem_id of the semaphore this object holds.
\warning Like any other internal objects that the Haiku API might expose,
\fn sem_id BLocker::Sem(void) const
\brief Return the sem_id of the semaphore this object holds.
\warning Like any other internal objects that the Haiku API might expose,
this semaphore id should in general be left alone. You should not use any
of the public low-level semaphore functions on this semaphore, because it
will harm the internal consistency of the object.
docs/user/support/string.dox → docs/user/support/String.dox
+335 -116
View File
File diff suppressed because it is too large Load Diff
docs/user/support/SupportDefs.dox
+352 -151
View File
File diff suppressed because it is too large Load Diff

Some files were not shown because too many files have changed in this diff Show More