diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index 43e0c1f2ced..340997c279e 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -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 diff --git a/docs/user/apidoc.dox b/docs/user/apidoc.dox index 7cbaad9fb8e..7faff5305f3 100644 --- a/docs/user/apidoc.dox +++ b/docs/user/apidoc.dox @@ -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, niels.reedijk@gmail.com + * John Scipione, jscipione@gmail.com + * * Proofreaders: * Alan Smale, ajsmale@gmail.com */ @@ -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, niels.reedijk@gmail.com -* Proofreaders: -* Alan Smale, ajsmale@gmail.com -* 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, niels.reedijk@gmail.com + * + * Proofreaders: + * Alan Smale, ajsmale@gmail.com + * + * 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 Authors, 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 Authors:, 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 Proofreaders: in case the file has been proofread. -# The final part is underneath the label Corresponds to:. 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. Try - not to cross this limit, because it will severely limit + -# The maximum width of the contents between blocks is 80 columns. Try + not to cross this limit, 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 \ and the (title). 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, //! \@{, 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. - */ diff --git a/docs/user/app/Application.dox b/docs/user/app/Application.dox index f48beb9817e..aa18feaf89e 100644 --- a/docs/user/app/Application.dox +++ b/docs/user/app/Application.dox @@ -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, jscipione@gmail.com * * 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. */ diff --git a/docs/user/app/Clipboard.dox b/docs/user/app/Clipboard.dox index 3cc3e89df0a..f1fbbc280d8 100644 --- a/docs/user/app/Clipboard.dox +++ b/docs/user/app/Clipboard.dox @@ -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, jscipione@gmail.com * * 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. diff --git a/docs/user/app/Cursor.dox b/docs/user/app/Cursor.dox index 56d9dbe7e95..4b266d8b625 100644 --- a/docs/user/app/Cursor.dox +++ b/docs/user/app/Cursor.dox @@ -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, jscipione@gmail.com * * 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 diff --git a/docs/user/app/Handler.dox b/docs/user/app/Handler.dox index 33fc2a0e5bc..227971815ba 100644 --- a/docs/user/app/Handler.dox +++ b/docs/user/app/Handler.dox @@ -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, niels.reedijk@gmail.com * * 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 diff --git a/docs/user/app/Looper.dox b/docs/user/app/Looper.dox index cfabdee7e45..b3ac2e91ae4 100644 --- a/docs/user/app/Looper.dox +++ b/docs/user/app/Looper.dox @@ -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, niels.reedijk@gmail.com * * 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 diff --git a/docs/user/app/Message.dox b/docs/user/app/Message.dox index 123c743eddc..e7ea4e51230 100644 --- a/docs/user/app/Message.dox +++ b/docs/user/app/Message.dox @@ -1,18 +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, niels.reedijk@gmail.com * * Corresponds to: - * /trunk/headers/os/app/Message.h rev 21562 - * /trunk/src/kits/app/Message.cpp rev 22240 + * headers/os/app/Message.h rev 21562 + * src/kits/app/Message.cpp rev 22240 */ /*! \file Message.h + \ingroup app + \ingroup libroot \brief Provides the BMessage class. */ @@ -90,35 +92,36 @@ /*! \class BMessage \ingroup app + \ingroup libbe \brief A container that can be send and received using the Haiku messaging subsystem. - + This class is at the center of the web of messaging classes, in the sense that it defines the actual structure of the messages. Messages have two important elements: the #what identifier, and the data members. The first can be directly manipulated, the latter can be manipulated through AddData(), FindData() and ReplaceData() and their derivatives. Neither of these elements are mandatory. - + The second important role of BMessage is that it stores meta data: who sent the message and with what intention? The methods of BMessage will disclose if the message was a reply (IsReply()), where it came from (IsSourceRemote()), whether a reply is expected (IsSourceWaiting()), and in case the message is a reply, what it's a reply to (Previous()). - + Mostly, messages are used to pass information between the the objects in your application, but because messages are such flexible data containers, they are also often used for other data storage purposes. Many applications store their settings as messages. Because messages can be flattened to data streams (such as files), they provide an easy but powerful tool for data storage. - + All methods can be classified in these areas: - Adding, Finding, Replacing and Removing Data. - Statistics and Miscellaneous information. - Delivery information. - Utilities to reply to messages. - + To see how messages fit in with the greater picture, have a look at the \ref app_messaging "Messaging Introduction". */ @@ -127,7 +130,7 @@ /*! \var BMessage::what \brief A 4-byte constant that determines the type of message. - + You can directly manipulate this data member. */ @@ -136,7 +139,7 @@ \fn BMessage::BMessage() \brief Construct an empty message, without any data members and with a \a what constant set to \c 0. - + \see BMessage(uint32 what) \see BMessage(const BMessage &other) */ @@ -146,7 +149,7 @@ \fn BMessage::BMessage(uint32 what) \brief Construct an empty message with the \a what member set to the specified value. - + \see BMessage::BMessage() \see BMessage::BMessage(const BMessage &other) */ @@ -155,13 +158,13 @@ /*! \fn BMessage::BMessage(const BMessage &other) \brief Construct a new message that is a copy of another message. - + The \a what member and the data values are copied. The metadata, such as whether or not the message is a drop message or reply information, is not copied. So if the original message is a reply to a previous message, which will make IsReply() return \c true, calling the same method on a copy of the message will return \c false. - + \remarks BeOS R5 did keep the metadata of the message. Haiku deviates from this behavior. Please use the Haiku implementation of message copying as the default behavior. This will keep your applications backwards @@ -175,7 +178,7 @@ /*! \fn BMessage::~BMessage() \brief Free the data members associated with the message. - + If there still is a sender waiting for a reply, the \c B_NO_REPLY message will be sent to inform them that there won't be a reply. */ @@ -184,7 +187,7 @@ /*! \fn BMessage &BMessage::operator=(const BMessage &other) \brief Copy one message into another. - + See the copy constructor, BMessage(const BMessage &other), for details on what is copied, and what isn't. */ @@ -203,7 +206,7 @@ char **nameFound, type_code *typeFound, int32 *countFound) const \brief Retrieve the name, the type and the number of items in a message by an \a index. - + \param[in] typeRequested If you want to limit the search to only one type, pass that type code here. If you don't care which type the data has, you can pass \c B_ANY_TYPE. @@ -221,7 +224,7 @@ \return If the \a index is found, and matches the requested type, then the other parameters will be filled in. If this is not the case, the method will return with an error. - + \retval B_OK An match was found. The values have been filled in. \retval B_BAD_INDEX The \a index was out of range. None of the passed variables have been altered. @@ -235,7 +238,7 @@ int32 *countFound) const \brief Retrieve the type and the number of data items in this message that are associated with a \a name. - + \param[in] name The name of the data member that you are looking for. \param[out] typeFound In case of a match, the name of the data member will be put in this parameter. In case you are not interested, you can pass @@ -243,11 +246,11 @@ \param[out] countFound In case of a match, the number of items at this label will be in this parameter. In case you are not interested, you can safely pass \c NULL. - + \return If the message has data associated with the given \a name, the other parameters will contain information associated with the data, else, the method will return with an error. - + \retval B_OK A match was found. The other parameters have been filled in. \retval B_BAD_VALUE You passed \c NULL as argument to \a name. \retval B_NAME_NOT_FOUND There is no data with the label \a name. @@ -259,7 +262,7 @@ bool *fixedSize) const \brief Retrieve the type and whether or not the size of the data is fixed associated with a \a name. - + This method is the same as GetInfo(const char *,type_code *, int32 *) const, with the difference that you can find out whether or not the size of the data associated with the \a name is fixed. You will get this value @@ -270,13 +273,13 @@ /*! \fn int32 BMessage::CountNames(type_code type) const \brief Count the number of names of a certain \a type. - + This method can be used to count the number of items of a certain type. It's practical use is limited to debugging purposes. - + \param type The type you want to find. If you pass \c B_ANY_TYPE, this method will return the total number of data items. - + \return The number of data items in this message with the specified \a type, or \c 0 in case no items match the type. */ @@ -285,7 +288,7 @@ /*! \fn bool BMessage::IsEmpty() const \brief Check if the message has data members. - + \return If this message contains data members, this method will return \c true, else it will return \c false. \see MakeEmpty() @@ -295,7 +298,7 @@ /*! \fn bool BMessage::IsSystem() const \brief Check if the message is a system message. - + \return If this message is a system message, the method will return \c true. */ @@ -304,7 +307,7 @@ /*! \fn bool BMessage::IsReply() const \brief Check if the message is a reply to a (previous) message. - + \return If this message is a reply, this method will return \c true. */ @@ -312,7 +315,7 @@ /*! \fn void BMessage::PrintToStream() const \brief Print the message to the standard output. - + This method can be used to debug your application. It can be used to check if it creates the messages properly, by checking if all the required fields are present, and it can be used to debug your message handling routines, @@ -324,10 +327,10 @@ /*! \fn status_t BMessage::Rename(const char *oldEntry, const char *newEntry) \brief Rename a data label. - + \param oldEntry The name of the label you want to rename. \param newEntry The new name of the data entry. - + \retval B_OK Renaming succeeded. \retval B_BAD_VALUE Either the \a oldEntry or the \a newEntry pointers are \c NULL. @@ -348,15 +351,15 @@ /*! \fn bool BMessage::WasDelivered() const \brief Check if this message was delivered through the delivery methods. - + If this message is passed via a BMessenger or BLooper::PostMessage(), this method will return \c true. - + \warning This method should not be abused by a thread that sends a message to track whether or not a message was delivered. This is because the ownership of the message goes to the receiving looper, which will delete the message as soon as it is done with it. - + \warning If you need to check whether a message is delivered, you should either ask for a reply, or use one of the synchronous BMessenger::SendMessage() methods. @@ -366,7 +369,7 @@ /*! \fn bool BMessage::IsSourceWaiting() const \brief Check if the sender expects a reply. - + This method will return \c true, if the sender flagged that it is waiting for a reply, and such a reply has not yet been sent. */ @@ -381,18 +384,18 @@ /*! \fn BMessenger BMessage::ReturnAddress() const \brief Get a messenger that points to the sender of the message. - + Using this method, you can fetch a BMessenger that can be used to deliver replies to this message. This method works both for local and remote deliveries. - + For remote deliveries, this approach is preferred over sending the reply using a standard BMessenger that is created with the signature of the application. A standard BMessenger sends the messages to the main BLooper of the application, the BApplication object. With the delivery data stored in the messages, the reply using this messenger will be directed at a specific looper that is able to handle the replies. - + If this method is called on a message that has not been delivered (yet), it will return an empty BMessenger object. */ @@ -401,7 +404,7 @@ /*! \fn const BMessage *BMessage::Previous() const \brief Get the message to which this message is a reply. - + \return Returns a new BMessage with the same data stuctures as the message to which this message is a reply. You get the ownership of this message, so free it when you're done. If this message isn't a reply to @@ -412,7 +415,7 @@ /*! \fn bool BMessage::WasDropped() const \brief Check if the message was delivered through 'drag and drop'. - + \return This method returns \c true if the message has been delivered through drag and drop. It returns \c false if it has been delivered through the regular messaging functions, or if the message has not @@ -424,18 +427,18 @@ /*! \fn BPoint BMessage::DropPoint(BPoint *offset) const \brief Get the coordinates of the drop point of the message. - + If the message has been delivered because of drag and drop, which can be verified with the WasDropped() method, this method will return a BPoint to where exactly the drop off was made. - + Because drop messages are delivered to the BWindow in which they were dropped, and BWindow is a subclass of BLooper, you can use BWindow to determine based on the location, how you should react to it. - + If this message was not delivered through drag and drop, it will return a \c NULL pointer. - + \see WasDropped() */ @@ -454,7 +457,7 @@ /*! \fn status_t BMessage::SendReply(uint32 command, BHandler *replyTo) \brief Asynchronously send a reply to this message. - + This is an overloaded member of SendReply(BMessage *, BMessenger, bigtime_t). Use this variant if you want to send a message without data members. */ @@ -464,7 +467,7 @@ \fn status_t BMessage::SendReply(BMessage *reply, BHandler *replyTo, bigtime_t timeout) \brief Asynchronously send a reply to this message. - + This is an overloaded member of SendReply(BMessage *, BMessenger, bigtime_t). Use this variant if you want to send the message to a specific handler (instead of a complete messenger). @@ -475,13 +478,13 @@ \fn status_t BMessage::SendReply(BMessage *reply, BMessenger replyTo, bigtime_t timeout) \brief Asynchronously send a reply to this message. - + This method sends a reply to this message to the sender. On your turn, you specify a messenger that handles a reply back to the message you specify as the \a reply argument. You can set a timeout for the message to be delivered. This method blocks until the message has been received, or the \a timeout has been reached. - + \param reply The message that is in reply to this message. \param replyTo In case the receiver needs to reply to the message you are sending, you can specify the return address with this argument. @@ -489,7 +492,7 @@ \a timeout is a relative timeout. You can also use \c B_INFINITE_TIMEOUT if you want to wait infinitely for the message to be delivered. - + \retval B_OK The message has been delivered. \retval B_DUPLICATE_REPLY There already has been a reply to this message. \retval B_BAD_PORT_ID The reply address is not valid (anymore). @@ -506,7 +509,7 @@ \fn status_t BMessage::SendReply(uint32 command, BMessage *replyToReply) \brief Synchronously send a reply to this message, and wait for a reply back. - + This is an overloaded member of SendReply(BMessage *, BMessage *, bigtime_t, bigtime_t) Use this variant if you want to send a message without data members. @@ -518,7 +521,7 @@ bigtime_t sendTimeout, bigtime_t replyTimeout) \brief Synchronously send a reply to this message, and wait for a reply back. - + This method sends a reply to this message to the sender. The \a reply is delivered, and then the method waits for a reply from the receiver. If a reply is received, that reply is copied into the @@ -526,7 +529,7 @@ If the message was delivered properly, but the receiver did not reply within the specified \a replyTimeout, the \a what member of \a replyToReply will be set to \c B_NO_REPLY. - + \param reply The message that is in reply to this message. \param[out] replyToReply The reply is copied into this argument. \param sendTimeout The maximum time in microseconds this delivery may take. @@ -535,7 +538,7 @@ to be delivered. \param replyTimeout The maximum time in microseconds you want to wait for a reply. Note that the timer starts when the message has been delivered. - + \retval B_OK The message has been delivered. \retval B_DUPLICATE_REPLY There already has been a reply to this message. \retval B_BAD_VALUE Either \a reply or \a replyToReply is @@ -556,7 +559,7 @@ /*! \name Flattening methods - + Because of historical reasons and for binary compatibility, this class provides a flattening API without inheriting the BFlattenable class. The API is more or less the same, but you are inconvenienced when you want to @@ -565,7 +568,7 @@ //! @{ - + /*! \fn ssize_t BMessage::FlattenedSize() const @@ -577,13 +580,13 @@ /*! \fn status_t BMessage::Flatten(char *buffer, ssize_t size) const \brief Flatten the message to a \a buffer. - + \param buffer The buffer to write the data to. \param size The size of the buffer. - + \return \c B_OK in case of success, or an error code in case something went awry. - + \warning Make sure the buffer is large enough to hold the message. This method does not double-check for you! \see FlattenedSize() @@ -594,13 +597,13 @@ /*! \fn status_t BMessage::Flatten(BDataIO *stream, ssize_t *size) const \brief Flatten the message to a \a stream. - + \param[in] stream The stream to flatten the message to. \param[out] size The method writes the number of bytes actually written to this argument. \return \c B_OK in case of success, or an error code in case something went awry. - + \warning Make sure the subclass of the BDataIO interface either protects against buffer overwrites, or check if the number of bytes that is going to be written isn't larger than it can handle. @@ -613,11 +616,11 @@ \fn status_t BMessage::Unflatten(const char *flatBuffer) \brief Unflatten a message from a buffer and put it into the current object. - + This action clears the current contents of the message. - + \param flatBuffer The buffer that contains the message. - + \retval B_OK The buffer has been unflattened. \retval B_BAD_VALUE The buffer does not contain a valid message. \retval B_NO_MEMORY An error occured whilst allocating memory for the data @@ -631,11 +634,11 @@ \fn status_t BMessage::Unflatten(BDataIO *stream) \brief Unflatten a message from a stream and put it into the current object. - + This action clears the current contents of the message. - + \param stream The stream that contains the message. - + \retval B_OK The message has been unflattened. \retval B_BAD_VALUE The stream does not contain a valid message. \retval B_NO_MEMORY An error occured whilst allocating memory for the data @@ -650,9 +653,9 @@ /*! \name Specifiers (Scripting) */ - + //! @{ - + /*! \fn status_t BMessage::AddSpecifier(const char *property) @@ -719,19 +722,19 @@ //! @{ - + /*! \fn status_t BMessage::AddData(const char *name, type_code type, const void *data, ssize_t numBytes, bool isFixedSize, int32 count) \brief Add \a data of a certain \a type to the message. - + The amount of \a numBytes is copied into the message. The data is stored at the label specified in \a name. You are responsible for specifying the correct \a type. The Haiku API already specifies many constants, such as \c B_FLOAT_TYPE or \c B_RECT_TYPE. See TypeConstants.h for more information on the system-wide defined types. - + If the field with the \a name already exists, the data is added in an array-like form. If you are adding a certain \a name for the first time, you are able to specify some properties of this array. You can @@ -743,12 +746,12 @@ If consecutive method calls specify a different \a type than the initial, these calls will fail. - + There is no limit to the number of labels, or the amount of data, but note that searching of data members is linear, as well as that some messages will be copied whilst being passed around, so if the amount of data you need to pass is too big, find another way to pass it. - + \param name The label to which this data needs to be associated. If the \a name already exists, the new data will be added in an array-like style. @@ -767,7 +770,7 @@ \a name, you can instruct this message to allocate a number of items in advance. This does not limit the amount of items though. The array will grow if needed. - + \retval B_OK The \a data is succesfully added. \retval B_BAD_VALUE The \a numBytes is less than, or equal to \c 0, or the size of this item is larger than the \a name allows, @@ -782,9 +785,9 @@ /*! \fn status_t BMessage::AddRect(const char *name, BRect aRect) \brief Convenience method to add a BRect to the label \a name. - + This method calls AddData() with the \c B_RECT_TYPE \a type. - + \param name The label to associate the data with. \param aRect The rectangle to store in the message. \see AddData() for a more detailed overview of the inner workings. @@ -796,9 +799,9 @@ /*! \fn status_t BMessage::AddPoint(const char *name, BPoint aPoint) \brief Convenience method to add a BPoint to the label \a name. - + This method calls AddData() with the \c B_POINT_TYPE \a type. - + \param name The label to associate the data with. \param aPoint The point to store in the message. \see AddData() for a more detailed overview of the inner workings. @@ -810,9 +813,9 @@ /*! \fn status_t BMessage::AddString(const char *name, const char *aString) \brief Convenience method to add a C-string to the label \a name. - + This method calls AddData() with the \c B_STRING_TYPE \a type. - + \param name The label to associate the data with. \param aString The string to copy to the message. \see AddData() for a more detailed overview of the inner workings. @@ -824,9 +827,9 @@ /*! \fn status_t BMessage::AddString(const char *name, const BString &aString) \brief Convenience method to add a BString to the label \a name. - + This method calls AddData() with the \c B_STRING_TYPE \a type. - + \param name The label to associate the data with. \param aString The string to copy to the message. \see AddData() for a more detailed overview of the inner workings. @@ -838,23 +841,23 @@ /*! \fn status_t BMessage::AddInt8(const char *name, int8 value) \brief Convenience method to add an \c int8 to the label \a name. - + This method calls AddData() with the \c B_INT8_TYPE \a type. - + \param name The label to associate the data with. \param value The value to store in the message. \see AddData() for a more detailed overview of the inner workings. \see FindInt8() \see ReplaceInt8() */ - + /*! \fn status_t BMessage::AddInt16(const char *name, int16 value) \brief Convenience method to add an \c int16 to the label \a name. - + This method calls AddData() with the \c B_INT16_TYPE \a type. - + \param name The label to associate the data with. \param value The value to store in the message. \see AddData() for a more detailed overview of the inner workings. @@ -866,9 +869,9 @@ /*! \fn status_t BMessage::AddInt32(const char *name, int32 value) \brief Convenience method to add an \c int32 to the label \a name. - + This method calls AddData() with the \c B_INT32_TYPE \a type. - + \param name The label to associate the data with. \param value The value to store in the message. \see AddData() for a more detailed overview of the inner workings. @@ -880,9 +883,9 @@ /*! \fn status_t BMessage::AddInt64(const char *name, int64 value) \brief Convenience method to add an \c int64 to the label \a name. - + This method calls AddData() with the \c B_INT64_TYPE \a type. - + \param name The label to associate the data with. \param value The value to store in the message. \see AddData() for a more detailed overview of the inner workings. @@ -894,9 +897,9 @@ /*! \fn status_t BMessage::AddBool(const char *name, bool aBoolean) \brief Convenience method to add a \c bool to the label \a name. - + This method calls AddData() with the \c B_BOOL_TYPE \a type. - + \param name The label to associate the data with. \param aBoolean The value to store in the message. \see AddData() for a more detailed overview of the inner workings. @@ -937,7 +940,7 @@ \brief Convenience method to add a \c pointer to the label \a name. This method calls AddData() with the \c B_POINTER_TYPE \a type. - + \warning If you want to share objects between applications, please remember that each application has its own address space, and that it therefore is useless to try to pass around objects by sending pointers in @@ -1031,10 +1034,10 @@ \fn status_t BMessage::RemoveData(const char *name, int32 index) \brief Remove data associated with \a name at a specified \a index. - + If this is the only instance of the data, then the entire label will be removed. This means you can recreate it with another type. - + \param name The \a name of which the associated data should be cleared. \param index The \a index of the item that should be cleared. \retval B_OK The data has been removed. @@ -1050,10 +1053,10 @@ /*! \fn status_t BMessage::RemoveName(const char *name) \brief Remove all data associated with a \a name. - + This also removes the label, so that you can recreate it with another type, if you want to. - + \param name The \a name that refers to the data you want to clear out. \retval B_OK All the data is removed. @@ -1067,10 +1070,10 @@ /*! \fn status_t BMessage::MakeEmpty() \brief Clear all data and metadata in this message. - + Everything is cleared out, all labels and all associated data, as well as metadata such as reply info. - + \return This method always returns \c B_OK. \see RemoveData() \see RemoveName() @@ -1082,13 +1085,13 @@ /*! \name Finding Data - + Look at FindData() for a general introduction to finding data. */ /* TODO: Quick overview: - + @@ -1104,19 +1107,19 @@ int32 index, const void **data, ssize_t *numBytes) const \brief Find \a data that is stored in this message at an \a index. - + This method matches the label \a name with the \a type you are asking for, and it looks for the data that is stored at a certain \a index number. If all these things match, you will get a pointer to the internal buffer, and the method will put the size of the item in \a numBytes. - + Note that only this method, and FindString(const char *, const char **), pass a pointer to the internal buffer. The other more specific methods, such as FindBool() and FindRect() copy the data into a buffer you specify. This means that the data retrieved with this method is valid until the message is deleted. - + \param name The label the data should be associated with. \param type The type of data you want to retrieve. You can pass \c B_ANY_TYPE if you don't mind which type the data is. @@ -1138,7 +1141,7 @@ \fn status_t BMessage::FindData(const char *name, type_code type, const void **data, ssize_t *numBytes) const \brief Find \a data that is stored in this message. - + This is an overloaded method of FindData(const char *, type_code, int32, const void **, ssize_t *) const where data is sought at \a index \c 0. @@ -1148,7 +1151,7 @@ /*! \fn status_t BMessage::FindRect(const char *name, BRect *rect) const \brief Find a rectangle at the label \a name. - + This is an overloaded method of FindRect(const char *, int32, BRect *) const where the data is sought at \a index \c 0. @@ -1158,10 +1161,10 @@ /*! \fn status_t BMessage::FindRect(const char *name, int32 index, BRect *rect) const \brief Find a rectangle at the label \a name at an \a index. - + This method looks for the data with the \c B_RECT_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param rect The object in which the data should be copied. @@ -1175,7 +1178,7 @@ /*! \fn status_t BMessage::FindPoint(const char *name, BPoint *point) const \brief Find a point at the label \a name. - + This is an overloaded method of FindPoint(const char *, int32, BPoint *) const where the data is sought at \a index \c 0. @@ -1185,10 +1188,10 @@ /*! \fn status_t BMessage::FindPoint(const char *name, int32 index, BPoint *point) const \brief Find a point at the label \a name at an \a index. - + This method looks for the data with the \c B_POINT_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param point The object in which the data should be copied. @@ -1202,7 +1205,7 @@ /*! \fn status_t BMessage::FindString(const char *name, const char **string) const \brief Find a string at the label \a name. - + This is an overloaded method of FindString(const char *, int32, const char **) const where the data is sought at \a index \c 0. @@ -1213,11 +1216,11 @@ \fn status_t BMessage::FindString(const char *name, int32 index, const char ** string) const \brief Find a string at the label \a name at an \a index. - + This method looks for the data with the \c B_STRING_TYPE, and returns a pointer to the internal buffer of the message. Note that this pointer is valid, until the message is deleted. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param string The object in which the data should be copied. @@ -1232,7 +1235,7 @@ /*! \fn status_t BMessage::FindString(const char *name, BString *string) const \brief Find a string at the label \a name. - + This is an overloaded method of FindString(const char *, int32, BString *) const where the data is sought at \a index \c 0. @@ -1242,10 +1245,10 @@ /*! \fn status_t BMessage::FindString(const char *name, int32 index, BString *string) const \brief Find a string at the label \a name at an \a index. - + This method looks for the data with the \c B_STRING_TYPE, and copies it into the \a string object. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param string The object in which the data should be copied. @@ -1260,7 +1263,7 @@ /*! \fn status_t BMessage::FindInt8(const char *name, int8 *value) const \brief Find an integer at the label \a name. - + This is an overloaded method of FindInt8(const char *, int32, int8 *) const where the data is sought at \a index \c 0. */ @@ -1269,10 +1272,10 @@ /*! \fn status_t BMessage::FindInt8(const char *name, int32 index, int8 *value) const \brief Find an integer at the label \a name at an \a index. - + This method looks for the data with the \c B_INT8_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param value The object in which the data should be copied. @@ -1286,7 +1289,7 @@ /*! \fn status_t BMessage::FindInt16(const char *name, int16 *value) const \brief Find an integer at the label \a name. - + This is an overloaded method of FindInt8(const char *, int32, int16 *) const where the data is sought at \a index \c 0. */ @@ -1295,10 +1298,10 @@ /*! \fn status_t BMessage::FindInt16(const char *name, int32 index, int16 *value) const \brief Find an integer at the label \a name at an \a index. - + This method looks for the data with the \c B_INT16_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param value The object in which the data should be copied. @@ -1312,7 +1315,7 @@ /*! \fn status_t BMessage::FindInt32(const char *name, int32 *value) const \brief Find an integer at the label \a name. - + This is an overloaded method of FindInt32(const char *, int32, int32 *) const where the data is sought at \a index \c 0. @@ -1322,10 +1325,10 @@ /*! \fn status_t BMessage::FindInt32(const char *name, int32 index, int32 *value) const \brief Find an integer at the label \a name at an \a index. - + This method looks for the data with the \c B_INT32_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param value The object in which the data should be copied. @@ -1339,7 +1342,7 @@ /*! \fn status_t BMessage::FindInt64(const char *name, int64 *value) const \brief Find an integer at the label \a name. - + This is an overloaded method of FindInt64(const char *, int32, int64 *) const where the data is sought at \a index \c 0. @@ -1349,10 +1352,10 @@ /*! \fn status_t BMessage::FindInt64(const char *name, int32 index, int64 *value) const \brief Find an integer at the label \a name at an \a index. - + This method looks for the data with the \c B_INT64_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param value The object in which the data should be copied. @@ -1366,7 +1369,7 @@ /*! \fn status_t BMessage::FindBool(const char *name, bool *value) const \brief Find a boolean at the label \a name. - + This is an overloaded method of FindBool(const char *, int32, bool *) const where the data is sought at \a index \c 0. @@ -1376,10 +1379,10 @@ /*! \fn status_t BMessage::FindBool(const char *name, int32 index, bool *value) const \brief Find a boolean at the label \a name at an \a index. - + This method looks for the data with the \c B_BOOL_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param value The object in which the data should be copied. @@ -1393,7 +1396,7 @@ /*! \fn status_t BMessage::FindFloat(const char *name, float *value) const \brief Find a float at the label \a name. - + This is an overloaded method of FindFloat(const char *, int32, float *) const where the data is sought at \a index \c 0. @@ -1403,10 +1406,10 @@ /*! \fn status_t BMessage::FindFloat(const char *name, int32 index, float *value) const \brief Find a float at the label \a name at an \a index. - + This method looks for the data with the \c B_FLOAT_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param value The object in which the data should be copied. @@ -1420,7 +1423,7 @@ /*! \fn status_t BMessage::FindDouble(const char *name, double *value) const \brief Find a double at the label \a name. - + This is an overloaded method of FindDouble(const char *, int32, double *) const where the data is sought at \a index \c 0. @@ -1430,10 +1433,10 @@ /*! \fn status_t BMessage::FindDouble(const char *name, int32 index, double *value) const \brief Find a double at the label \a name at an \a index. - + This method looks for the data with the \c B_DOUBLE_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param value The object in which the data should be copied. @@ -1447,7 +1450,7 @@ /*! \fn status_t BMessage::FindPointer(const char *name, void **pointer) const \brief Find a pointer at the label \a name. - + This is an overloaded method of FindPointer(const char *, int32, void *) const where the data is sought at \a index \c 0. @@ -1457,16 +1460,16 @@ /*! \fn status_t BMessage::FindPointer(const char *name, int32 index, void **pointer) const \brief Find a pointer at the label \a name at an \a index. - + This method looks for the data with the \c B_POINTER_TYPE, and copies it into a provided buffer. - + \warning If you want to share objects between applications, please remember that each application has its own address space, and that it therefore is useless to try to pass around objects by sending pointers in messages. You should think about copying the entire object in the message, or you should consider using shared memory. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param pointer The object in which the data should be copied. @@ -1480,7 +1483,7 @@ /*! \fn status_t BMessage::FindMessenger(const char *name, BMessenger *messenger) const \brief Find a messenger at the label \a name. - + This is an overloaded method of FindMessenger(const char *, int32, BMessenger *) const where the data is sought at \a index \c 0. @@ -1490,10 +1493,10 @@ /*! \fn status_t BMessage::FindMessenger(const char *name, int32 index, BMessenger *messenger) const \brief Find a messenger at the label \a name at an \a index. - + This method looks for the data with the \c B_MESSENGER_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param messenger The object in which the data should be copied. @@ -1507,7 +1510,7 @@ /*! \fn status_t BMessage::FindRef(const char *name, entry_ref *ref) const \brief Find a reference to a file at the label \a name. - + This is an overloaded method of FindRef(const char *, int32, entry_ref *) const where the data is sought at \a index \c 0. @@ -1518,10 +1521,10 @@ \fn status_t BMessage::FindRef(const char *name, int32 index, entry_ref *ref) const \brief Find a reference to a file at the label \a name at an \a index. - + This method looks for the data with the \c B_REF_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param ref The object in which the data should be copied. @@ -1535,7 +1538,7 @@ /*! \fn status_t BMessage::FindMessage(const char *name, BMessage *message) const \brief Find a message at the label \a name. - + This is an overloaded method of FindMessage(const char *, int32, BMessage *) const where the data is sought at \a index \c 0. @@ -1545,10 +1548,10 @@ /*! \fn status_t BMessage::FindMessage(const char *name, int32 index, BMessage *message) const \brief Find a message at the label \a name at an \a index. - + This method looks for the data with the \c B_MESSAGE_TYPE, and copies it into a provided buffer. - + \param name The label to which the data is associated. \param index The index from which the data should be copied. \param message The object in which the data should be copied. @@ -1562,7 +1565,7 @@ /*! \fn status_t BMessage::FindFlat(const char *name, BFlattenable *object) const \brief Find a flattened object at the label \a name. - + This is an overloaded method of FindFlat(const char *, int32, BFlattenable *) const where the data is sought at \a index \c 0. @@ -1574,11 +1577,11 @@ BFlattenable *object) const \brief Find a flattened object at the label \a name at an \a index. - + The type is determined by the type of the passed object. If that type is available at the specified label, then the Unflatten() method of that object will be called. - + \param name The label to which the data is associated. \param index The index from which the data should be unflattened. \param object The object in which the data should be unflattened. @@ -1594,7 +1597,7 @@ /*! \name Replacing Data - + Look at ReplaceData() for a general introduction to replacing data. */ @@ -1606,7 +1609,7 @@ \fn status_t BMessage::ReplaceData(const char *name, type_code type, const void *data, ssize_t numBytes) \brief Replace the data at label \a name. - + This method is an overloaded method that replaces the data at \a index \c 0. See ReplaceData(const char *, type_code, int32, const void *, ssize_t). @@ -1618,22 +1621,22 @@ int32 index, const void *data, ssize_t numBytes) \brief Replace the data at label \a name at a specified \a index. - + The conditions for replacing data are that the\a name is correct, the \a type matches and the data entry at \a index exists. - + There is also a collection of convenience methods, that allow you to efficiently replace rectanges (ReplaceRect()), booleans (ReplaceBool()), and so on. - + \param name The name associated with the data to replace. \param type The type of the data. \param index The index in the array to replace. \param data A pointer to the new data that needs to be copied into the message. \param numBytes The size of the new data. - + \retval B_OK The operation succeeded. \retval B_BAD_VALUE One of the input parameters are invalid. Check that you did not pass \c NULL, and in case the field has fixed sized data, @@ -1645,7 +1648,7 @@ /*! \fn status_t BMessage::ReplaceRect(const char *name, BRect aRect) \brief Replace a rectangle at the label \a name. - + This method is an overloaded method of ReplaceRect(const char *, int32, BRect). It replaces the data at \a index \c 0. @@ -1656,7 +1659,7 @@ \fn status_t BMessage::ReplaceRect(const char *name, int32 index, BRect aRect) \brief Replace a rectangle at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_RECT_TYPE. \param name The name associated with the data to replace. @@ -1671,7 +1674,7 @@ /*! \fn status_t BMessage::ReplacePoint(const char *name, BPoint aPoint) \brief Replace a point at the label \a name. - + This method is an overloaded method of ReplacePoint(const char *, int32, BPoint). It replaces the data at \a index \c 0. @@ -1682,7 +1685,7 @@ \fn status_t BMessage::ReplacePoint(const char *name, int32 index, BPoint aPoint) \brief Replace a point at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_POINT_TYPE. \param name The name associated with the data to replace. @@ -1697,7 +1700,7 @@ /*! \fn status_t BMessage::ReplaceString(const char *name, const char *aString) \brief Replace a string at the label \a name. - + This method is an overloaded method of ReplaceString(const char *, int32, const char *). It replaces the data at \a index \c 0. @@ -1708,7 +1711,7 @@ \fn status_t BMessage::ReplaceString(const char *name, int32 index, const char *aString) \brief Replace a string at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_STRING_TYPE. \param name The name associated with the data to replace. @@ -1723,7 +1726,7 @@ /*! \fn status_t BMessage::ReplaceString(const char *name, const BString &aString) \brief Replace a string at the label \a name. - + This method is an overloaded method of ReplaceString(const char *, int32, BString &). It replaces the data at \a index \c 0. @@ -1734,7 +1737,7 @@ \fn status_t BMessage::ReplaceString(const char *name, int32 index, const BString &aString) \brief Replace a string at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_STRING_TYPE. \param name The name associated with the data to replace. @@ -1749,7 +1752,7 @@ /*! \fn status_t BMessage::ReplaceInt8(const char *name, int8 value) \brief Replace an integer at the label \a name. - + This method is an overloaded method of ReplaceInt8(const char *, int32, int8). It replaces the data at \a index \c 0. @@ -1760,7 +1763,7 @@ \fn status_t BMessage::ReplaceInt8(const char *name, int32 index, int8 value) \brief Replace an integer at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_INT8_TYPE. \param name The name associated with the data to replace. @@ -1775,7 +1778,7 @@ /*! \fn status_t BMessage::ReplaceInt16(const char *name, int16 value) \brief Replace an integer at the label \a name. - + This method is an overloaded method of ReplaceInt16(const char *, int32, int16). It replaces the data at \a index \c 0. @@ -1786,7 +1789,7 @@ \fn status_t BMessage::ReplaceInt16(const char *name, int32 index, int16 value) \brief Replace an integer at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_INT16_TYPE. \param name The name associated with the data to replace. @@ -1801,7 +1804,7 @@ /*! \fn status_t BMessage::ReplaceInt32(const char *name, int32 value) \brief Replace an integer at the label \a name. - + This method is an overloaded method of ReplaceInt8(const char *, int32, int32). It replaces the data at \a index \c 0. @@ -1812,7 +1815,7 @@ \fn status_t BMessage::ReplaceInt32(const char *name, int32 index, int32 value) \brief Replace an integer at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_INT32_TYPE. \param name The name associated with the data to replace. @@ -1827,7 +1830,7 @@ /*! \fn status_t BMessage::ReplaceInt64(const char *name, int64 value) \brief Replace an integer at the label \a name. - + This method is an overloaded method of ReplaceInt8(const char *, int32, int64). It replaces the data at \a index \c 0. @@ -1838,7 +1841,7 @@ \fn status_t BMessage::ReplaceInt64(const char *name, int32 index, int64 value) \brief Replace an integer at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_INT64_TYPE. \param name The name associated with the data to replace. @@ -1853,7 +1856,7 @@ /*! \fn status_t BMessage::ReplaceBool(const char *name, bool aBoolean) \brief Replace a boolean at the label \a name. - + This method is an overloaded method of ReplaceBool(const char *, int32, bool). It replaces the data at \a index \c 0. @@ -1864,7 +1867,7 @@ \fn status_t BMessage::ReplaceBool(const char *name, int32 index, bool aBoolean) \brief Replace a boolean at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_BOOL_TYPE. @@ -1880,7 +1883,7 @@ /*! \fn status_t BMessage::ReplaceFloat(const char *name, float aFloat) \brief Replace a float at the label \a name. - + This method is an overloaded method of ReplaceFloat(const char *, int32, float). It replaces the data at \a index \c 0. @@ -1891,7 +1894,7 @@ \fn status_t BMessage::ReplaceFloat(const char *name, int32 index, float aFloat) \brief Replace a float at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_FLOAT_TYPE. @@ -1907,7 +1910,7 @@ /*! \fn status_t BMessage::ReplaceDouble(const char *name, double aDouble) \brief Replace a double at the label \a name. - + This method is an overloaded method of ReplaceDouble(const char *, int32, double). It replaces the data at \a index \c 0. @@ -1918,7 +1921,7 @@ \fn status_t BMessage::ReplaceDouble(const char *name, int32 index, double aDouble) \brief Replace a double at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_DOUBLE_TYPE. @@ -1934,7 +1937,7 @@ /*! \fn status_t BMessage::ReplacePointer(const char *name, const void *pointer) \brief Replace a pointer at the label \a name. - + This method is an overloaded method of ReplacePointer(const char *, int32, const void *). It replaces the data at \a index \c 0. @@ -1944,7 +1947,7 @@ /*! \fn status_t BMessage::ReplacePointer(const char *name,int32 index, const void *pointer) \brief Replace a pointer at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_POINTER_TYPE. @@ -1960,7 +1963,7 @@ /*! \fn status_t BMessage::ReplaceMessenger(const char *name, BMessenger messenger) \brief Replace a messenger at the label \a name. - + This method is an overloaded method of ReplaceMessenger(const char *, int32, BMessenger). It replaces the data at \a index \c 0. @@ -1971,7 +1974,7 @@ \fn status_t BMessage::ReplaceMessenger(const char *name, int32 index, BMessenger messenger) \brief Replace a messenger at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_MESSENGER_TYPE. @@ -1987,7 +1990,7 @@ /*! \fn status_t BMessage::ReplaceRef(const char *name,const entry_ref *ref) \brief Replace a reference to a file at the label \a name. - + This method is an overloaded method of ReplaceRef(const char *, int32, entry_ref *). It replaces the data at \a index \c 0. @@ -1998,7 +2001,7 @@ \fn status_t BMessage::ReplaceRef( const char *name, int32 index, const entry_ref *ref) \brief Replace a reference to a file at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_REF_TYPE. @@ -2014,7 +2017,7 @@ /*! \fn status_t BMessage::ReplaceMessage(const char *name, const BMessage *message) \brief Replace a message at the label \a name. - + This method is an overloaded method of ReplaceMessage(const char *, int32, BMessage *). It replaces the data at \a index \c 0. @@ -2025,7 +2028,7 @@ \fn status_t BMessage::ReplaceMessage(const char *name, int32 index, const BMessage *message) \brief Replace a message at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the \c B_MESSAGE_TYPE. @@ -2041,7 +2044,7 @@ /*! \fn status_t BMessage::ReplaceFlat(const char *name, BFlattenable *object) \brief Replace a flattened object at the label \a name. - + This method is an overloaded method of ReplaceFlat(const char *, int32, BFlattenable *). @@ -2053,11 +2056,11 @@ \fn status_t BMessage::ReplaceFlat(const char *name, int32 index, BFlattenable *object) \brief Replace a flattened object at the label \a name at a specified \a index. - + The data at the specified \a name and \a index will be replaced, if it matches the type returned by your object. This method uses BFlattenable::TypeCode() to determine the type of the object. - + \param name The name associated with the data to replace. \param index The index in the array to replace. \param object The object to store in the message. @@ -2074,7 +2077,7 @@ /*! \name Deprecated methods - + These methods are \e very likely to disappear, and they have been replaced by safer and more powerful methods. These methods are still implemented for binary compatibility, but they are not documented. @@ -2199,13 +2202,13 @@ /*! - \fn bool BMessage::HasData(const char *, type_code , int32) const + \fn bool BMessage::HasData(const char *, type_code , int32) const \brief Deprecated. */ /*! - \fn BRect BMessage::FindRect(const char *, int32) const + \fn BRect BMessage::FindRect(const char *, int32) const \brief Deprecated. */ @@ -2229,7 +2232,7 @@ /*! - \fn int16 BMessage::FindInt16(const char *, int32) const + \fn int16 BMessage::FindInt16(const char *, int32) const \brief Deprecated. */ diff --git a/docs/user/app/MessageFilter.dox b/docs/user/app/MessageFilter.dox index 29b9bbe5f04..4d517f8c125 100644 --- a/docs/user/app/MessageFilter.dox +++ b/docs/user/app/MessageFilter.dox @@ -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, niels.reedijk@gmail.com + * + * 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 diff --git a/docs/user/app/MessageQueue.dox b/docs/user/app/MessageQueue.dox index 12c49140ba4..c02de9e3098 100644 --- a/docs/user/app/MessageQueue.dox +++ b/docs/user/app/MessageQueue.dox @@ -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, niels.reedijk@gmail.com - * + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * 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. */ diff --git a/docs/user/app/_app_intro.dox b/docs/user/app/_app_intro.dox index ab458fa9506..ac9aaee5d42 100644 --- a/docs/user/app/_app_intro.dox +++ b/docs/user/app/_app_intro.dox @@ -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 + * Authors: + * Niels Sascha Reedijk, niels.reedijk@gmail.com */ /*! \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 diff --git a/docs/user/app/_app_messaging.dox b/docs/user/app/_app_messaging.dox index 5236706a07d..d71586241ba 100644 --- a/docs/user/app/_app_messaging.dox +++ b/docs/user/app/_app_messaging.dox @@ -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, niels.reedijk@gmail.com */ - /*! \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. - + Table of contents - 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... - */ - \ No newline at end of file diff --git a/docs/user/book.css b/docs/user/book.css index bef8af336e6..a310bde7647 100644 --- a/docs/user/book.css +++ b/docs/user/book.css @@ -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 - * Stephan Aßmus - * Braden Ewing - * Humdinger - * John Scipione + * François Revol, revol@free.fr + * Stephan Aßmus, superstippi@gmx.de + * Braden Ewing, brewin@gmail.com + * Humdinger, humdingerb@gmail.com + * John Scipione, jscipione@gmail.com */ /* color names provided by: http://chir.ag/projects/name-that-color */ diff --git a/docs/user/drivers/USB3.dox b/docs/user/drivers/USB3.dox index b617a7de48a..9df6323588d 100644 --- a/docs/user/drivers/USB3.dox +++ b/docs/user/drivers/USB3.dox @@ -1,674 +1,785 @@ -/* - * Copyright 2007, Haiku, Inc. All Rights Reserved. - * Distributed under the terms of the MIT License. - * - * Documentation by: - * Niels Sascha Reedijk - * Corresponds to: - * /trunk/headers/os/drivers/USB3.h rev 19915 - */ - -/*! - \file USB3.h - \ingroup drivers - \brief Interface for the USB module. -*/ - -/*! - \typedef struct usb_module_info usb_module_info - \brief The main interface object. See the usb_module_info documentation. -*/ - -/*! - \typedef uint32 usb_id - \brief Uniquely identify various USB objects that are used in the module. -*/ - -/*! - \typedef usb_id usb_device - \brief Uniquely identify USB devices. -*/ - -/*! - \typedef usb_id usb_interface - \brief Uniquely identify USB interfaces. -*/ - -/*! - \typedef usb_id usb_pipe - \brief Uniquely identify USB pipes. -*/ - -/*! - \typedef struct usb_endpoint_info usb_endpoint_info - \brief Container for USB endpoint descriptors. - \see Documentation for usb_endpoint_info. -*/ - -/*! - \typedef struct usb_interface_info usb_interface_info - \brief Container for USB interface descriptors. - \see Documentation for usb_interface_info. -*/ - -/*! - \typedef struct usb_interface_list usb_interface_list - \brief Container that holds a list of USB interface descriptors. - \see Documentation for usb_interface_list. -*/ - -/*! - \typedef struct usb_configuration_info usb_configuration_info - \brief Container for USB configuration descriptors. - \see Documentation for usb_configuration_info. -*/ - -///// usb_notify_hooks ///// - -/*! - \struct usb_notify_hooks - \brief Hooks that the USB stack can callback in case of events. -*/ - -/*! - \fn status_t (*usb_notify_hooks::device_added)(usb_device device, void **cookie) - \brief Called by the stack in case a device is added. - - Once you have registered hooks using the - usb_module_info::install_notify() method, this hook will be called as soon as - a device is inserted that matches your provided usb_support_descriptor. - - \param device A unique id that identifies this USB device. - \param[in] cookie You can store a pointer to an object in this variable. - When the device is removed, this cookie will be provided to you. - \return You should return \c B_OK in case of success. The USB stack will then - request the kernel to republish your device names so that the new device - will be shown in the \c /dev tree. If you return an error value, the - \a device id will become invalid and you will not be notified if this - device is removed. - \see device_removed() -*/ - -/*! - \var status_t (*usb_notify_hooks::device_removed)(void *cookie) - \brief Called by the stack in case a device you are using is removed. - - If you have accepted a device in the device_added() hook, this hook will - be called as soon as the device is removed. - - \param cookie The cookie you provided in the device_added() hook. Make sure - that you free the cookie if necessary. - \return Currently the return value of this hook is ignored. It is recommended - to return \c B_OK though. -*/ - -///// usb_support_descriptor ///// - -/*! - \struct usb_support_descriptor - \brief Description of device descriptor that the driver can handle. - - Support descriptors can be used to match any form of class, subclass or - protocol, or they can be used to match a vendor and/or product. - If any field has the value \c 0, it is treated as a wildcard. - - For example, if you want to watch for all the hubs, which have a device - class of \c 0x09, you would pass this descriptor: - - \code - usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 }; - \endcode - - See usb_module_info::register_driver() for more information on how to use - this object. -*/ - -/*! - \var usb_support_descriptor::dev_class - \brief The supported device classes. -*/ - -/*! - \var usb_support_descriptor::dev_subclass - \brief The supported device subclasses. -*/ - -/*! - \var usb_support_descriptor::dev_protocol - \brief The supported device protocols. -*/ - -/*! - \var usb_support_descriptor::vendor - \brief The supported device vendor. -*/ - -/*! - \var usb_support_descriptor::product - \brief The supported device products. -*/ - -///// usb_endpoint_info ///// - -/*! - \struct usb_endpoint_info - \brief Container for endpoint descriptors and their Haiku USB stack - identifiers. -*/ - -/*! - \var usb_endpoint_descriptor *usb_endpoint_info::descr - \brief Pointer to the descriptor of the endpoint. -*/ - -/*! - \var usb_pipe usb_endpoint_info::handle - \brief Handle to use when using the stack to transfer data to and from this - endpoint. -*/ - -///// usb_interface_info ///// - -/*! - \struct usb_interface_info - \brief Container for interface descriptors and their Haiku USB stack - identifiers. -*/ - -//! @{ - -/*! - \var usb_interface_descriptor *usb_interface_info::descr - \brief Pointer to the descriptor of the interface. -*/ - -/*! - \var usb_interface usb_interface_info::handle - \brief Handle to use when using the stack to manipulate this interface. -*/ - -//! @} - -/*! - \name Endpoints -*/ - -//! @{ - -/*! - \var size_t usb_interface_info::endpoint_count - \brief The number of endpoints in this interface. -*/ - -/*! - \var usb_endpoint_info *usb_interface_info::endpoint - \brief An array of endpoints that are associated to this interface. -*/ - -//! @} - -/*! - \name Unparsed descriptors -*/ - -//! @{ - -/*! - \var size_t usb_interface_info::generic_count - \brief The number of unparsed descriptors in this interface. -*/ - -/*! - \var usb_descriptor **usb_interface_info::generic - \brief Unparsed descriptors in this interface. -*/ - -//! @} - -///// usb_interface_list ///// - -/*! - \struct usb_interface_list - \brief List of interfaces available to a configuration. -*/ - -/*! - \var size_t usb_interface_list::alt_count - \brief Number of available interfaces. -*/ - -/*! - \var usb_interface_info *usb_interface_list::alt - \brief Array of available interfaces. -*/ - -/*! - \var usb_interface_info *usb_interface_list::active - \brief Pointer to active interface. -*/ - -///// usb_configuration_info ///// - -/*! - \struct usb_configuration_info - \brief Container for a specific configuration descriptor of a device. -*/ - -/*! - \var usb_configuration_descriptor *usb_configuration_info::descr - \brief The configuration descriptor. -*/ - -/*! - \var size_t usb_configuration_info::interface_count - \brief The number of interfaces in this configuration. -*/ - -/*! - \var usb_interface_list *usb_configuration_info::interface - \brief The list of interfaces available to this configuration. -*/ - -///// usb_iso_packet_descriptor ///// - -/*! - \struct usb_iso_packet_descriptor - \brief The descriptor for data packets of isochronous transfers. -*/ - -/*! - \var int16 usb_iso_packet_descriptor::request_length - \brief Length of the request. -*/ - -/*! - \var int16 usb_iso_packet_descriptor::actual_length - \brief The USB stack writes the actual transferred length in this variable. -*/ - -/*! - \var status_t usb_iso_packet_descriptor::status - \brief The status of the transfer. -*/ - -///// usb_callback_func ///// - -/*! - \typedef typedef void (*usb_callback_func)(void *cookie, status_t status, void *data, size_t actualLength) - \brief Callback function for asynchronous transfers. - \param cookie The cookie you supplied when you queued the transfer. - \param status The status of the transfer. This is one of the following: -
Type of dataType codeMethod
BRect\c B_RECT_TYPEFindRect()
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
B_OKThe transfer succeeded.
B_CANCELEDThe transfer was cancelled by the user - via a usb_module_info::cancel_queued_transfers() call.
B_DEV_MULTIPLE_ERRORSMore than one of the errors - below occurred. Unfortunately, the stack cannot give you more - information.
B_DEV_STALLEDThe endpoint is stalled. You can - use usb_module_info::clear_feature() method with the associated pipe - and the USB_FEATURE_ENDPOINT_HALT arguments.
B_DEV_DATA_OVERRUNIncoming transfer: more data - flowing in than the size of the buffer.
B_DEV_DATA_UNDERRUNOutgoing transfer: more data - is flowing out than the endpoint accepts.
B_DEV_CRC_ERRORThe internal data consistency - checks of the USB protocol failed. It is best to retry. If you keep - on getting this error there might be something wrong with the - device.
B_DEV_UNEXPECTED_PIDThere was an internal error. - You should retry your transfer.
B_DEV_FIFO_OVERRUNinternal error. - You should retry your transfer.
B_DEV_FIFO_UNDERRUNThere was an internal error. - You should retry your transfer.
- \param data The provided buffer. - \param actualLength The amount of bytes read or written during the transfer. -*/ - -///// usb_module_info ///// - -/*! - \struct usb_module_info - \brief Interface for drivers to interact with Haiku's USB stack. -*/ - -/*! - \var usb_module_info::binfo - \brief Instance of the bus_manager_info object. -*/ - -/*! - \fn status_t (*usb_module_info::register_driver)(const char *driverName, const usb_support_descriptor *supportDescriptors, size_t supportDescriptorCount, const char *optionalRepublishDriverName) - \brief Register your driver. - - To let the USB stack know that a driver is available to support devices, a - driver needs to register itself first. To let the stack know about devices - it needs to notify the driver of, have a look at usb_support_descriptor. - - It is possible to supply a list of support constructors. You should allocate - an array of support constructors and give the amount of constructors in the - array using the \a supportDescriptorCount parameter. - - In case your driver supports all devices or, more likely, you want to - monitor all devices plugged in and removed, it is safe to pass \c NULL to - the \a supportDescriptors paramater and zero (0) to - \a supportDescriptorCount. - - \param driverName A unique name that identifies your driver. Avoid names - like \c webcam or \c mouse, instead use vendor names and device types to - avoid nameclashes. The install_notify() and uninstall_notify() functions use - the driver name as an identifier. - - \param supportDescriptors An array of the type usb_support_descriptor. Pass - the amount of objects in the next parameter. - \param supportDescriptorCount The number of objects in the array supplied in - the previous parameter. - \param optionalRepublishDriverName Unused parameter. You should pass - \c NULL. - - \retval B_OK The driver is registered. You can now call install_notify() - \retval B_BAD_VALUE You passed \c NULL as \a driverName. - \retval B_ERROR General internal error in the USB stack. You may retry the - request in this case. - \retval B_NO_MEMORY Error allocating some internal objects. The system is - out of memory. -*/ - -/*! - \fn status_t (*usb_module_info::install_notify)(const char *driverName, const usb_notify_hooks *hooks) - \brief Install notify hooks for your driver. - - After your driver is registered, you need to pass hooks to your driver that - are called whenever a device that matches your \link usb_support_descriptor - support descriptor \endlink . - - As soon as the hooks are installed, you'll receive callbacks for devices - that are already attached; so make sure your driver is initialized properly - when calling this method. - - \param driverName The name you passed in register_driver(). - \param hooks The hooks the stack should call in case the status of devices - that match your support descriptor changes. - - \retval B_OK Hooks are installed succesfully. - \retval B_NAME_NOT_FOUND Invalid \a driverName. - - \see usb_notify_hooks for information on how your hooks should behave. - \see uninstall_notify() -*/ - -/*! - \fn status_t (*usb_module_info::uninstall_notify)(const char *driverName) - \brief Uninstall notify hooks for your driver. - - If your driver needs to stop, you can uninstall the notifier hooks. This - will clear the stored hooks in the driver, and you will not receive any - notifications when new devices are attached. This method will also call - usb_notify_hooks::device_removed() for all the devices that you are using - and all the stack's resources that are allocated to your driver are - cleared. - - \param driverName The name you passed in register_driver(). - \retval B_OK Hooks are uninstalled. - \retval B_NAME_NOT_FOUND Invalid \a driverName. -*/ - -/*! - \fn const usb_device_descriptor *(*usb_module_info::get_device_descriptor)(usb_device device) - \brief Get the device descriptor. - - \param device The id of the device you want to query. - \return The standard usb_device_descriptor, or \c NULL in case of an error. -*/ - -/*! - \fn const usb_configuration_info *(*usb_module_info::get_nth_configuration)(usb_device device, uint index) - \brief Get a configuration descriptor by index. - - \param device The id of the device you want to query. - \param index The (zero based) offset of the list of configurations. - \return This will normally return the usb_configuration_info with the - standard usb configuration descriptor. \c NULL will be returned if the - \a id is invalid or the \a index is out of bounds. -*/ - -/*! - \fn const usb_configuration_info *(*usb_module_info::get_configuration)(usb_device device) - \brief Get the current configuration. - - \param id The id of the device you want to query. - \retval This will return usb_configuration_info with the standard usb - configuration descriptor, or it will return\c NULL if the \a id is invalid. -*/ - -/*! - \fn status_t (*usb_module_info::set_configuration)(usb_device device, const usb_configuration_info *configuration) - \brief Change the current configuration. - - Changing the configuration will destroy all the current endpoints. If the - \a configuration points to the current configuration, the request will be - ignored and \c B_OK will be returned. - - \param device The id of the device you want to query. - \param configuration The pointer to the new configuration you want to set. - \retval B_OK The new configuration is set succesfully. - \retval B_DEV_INVALID_PIPE The \a device parameter is invalid. - \retval B_BAD_VALUE The configuration does not exist. - - \note This method also allows you to completely unconfigure the device, which - means that all the current endpoints, pipes and transfers will be freed. - Pass \c NULL to the parameter \a configuration if you want to do that. -*/ - -/*! - \fn status_t (*usb_module_info::set_alt_interface)(usb_device device, const usb_interface_info *interface) - \brief Set an alternative interface. Not implemented. - - This method currently always returns \c B_ERROR. -*/ - -/*! - \fn status_t (*usb_module_info::set_feature)(usb_id handle, uint16 selector) - \brief Convenience function for standard control pipe set feature requests. - Both the set_feature() and clear_feature() requests work on all the Stack's - objects: devices, interfaces and pipes. - - \param handle The object you want to query. - \param selector The value you want to pass in the feature request. - \return \c B_OK in case the request succeeded and the device responded - positively, or an error code in case it failed. -*/ - -/*! - \fn status_t (*usb_module_info::clear_feature)(usb_id handle, uint16 selector) - \brief Convenience function for standard control pipe clear feature requests. - - \see set_feature() to see how this method works. -*/ - -/*! - \fn status_t (*usb_module_info::get_status)(usb_id handle, uint16 *status) - \brief Convenience function for standard usb status requests. - - \param[in] handle The object you want to query. - \param[out] status A variable in which the device can store it's status. - \return \c B_OK is returned in case the request succeeded and the device - responded positively, or an error code is returned in case it failed. -*/ - -/*! - \fn status_t (*usb_module_info::get_descriptor)(usb_device device, uint8 descriptorType, uint8 index, uint16 languageID, void *data, size_t dataLength, size_t *actualLength) - \brief Convenience function to get a descriptor from a device. - - \param[in] device The device you want to query. - \param[in] descriptorType The type of descriptor you are requesting. - \param[in] index In case there are multiple descriptors of this type, you - select which one you want. - \param[in] languageID The language you want the descriptor in (if applicable, - as with string_descriptors). - \param[out] data The buffer in which the descriptor can be written. - \param[in] dataLength The size of the buffer (in bytes). - \param[out] actualLength A pointer to a variable in which the actual number - of bytes written can be stored. - \retval B_OK The request succeeded, and the descriptor is written. - \retval B_DEV_INVALID_PIPE Invalid \a device parameter. - \retval "other errors" Request failed. -*/ - -/*! - \fn status_t (*usb_module_info::send_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, size_t *actualLength) - \brief Send a generic, synchronous request over the default control pipe. - - See queue_request() for an asynchronous version of this method. - - Most of the standard values of a request are defined in USB_spec.h. - - \param[in] device The device you want to query. - \param[in] requestType The request type. - \param[in] request The request you want to perform. - \param[in] value The value of the request. - \param[in] index The index for the request. - \param[in] length The size of the buffer pointed by \a data - \param[out] data The buffer where to put the result in. - \param[out] actualLength The actual numbers of bytes written. - - \retval B_OK The request succeeded. - \retval B_DEV_INVALID_PIPE Invalid \a device parameter. - \retval "other errors" Request failed. -*/ - -/*! - \fn status_t (*usb_module_info::queue_interrupt)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie) - \brief Asynchronously queue an interrupt transfer. - - \param pipe The id of the pipe you want to query. - \param data The data buffer you want to pass. - \param dataLength The size of the data buffer. - \param callback The callback function the stack should call after finishing. - \param callbackCookie A cookie that will be supplied to your callback - function when the transfer is finished. - - \return This will return a value indicating whether or not the queueing of - the transfer went well. The return value won't tell you if the transfer - actually succeeded. - \retval B_OK The interrupt transfer is queued. - \retval B_NO_MEMORY Error allocating objects. - \retval B_DEV_INVALID_PIPE The \a pipe is not a valid interrupt pipe. -*/ - -/*! - \fn status_t (*usb_module_info::queue_bulk)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie) - \brief Asynchronously queue a bulk transfer. - - This method behaves like the queue_interrupt() method, except that it queues - a bulk transfer. -*/ - -/*! - \fn status_t (*usb_module_info::queue_bulk_v)(usb_pipe pipe, iovec *vector, size_t vectorCount, usb_callback_func callback, void *callbackCookie) - \brief Asynchronously queue a bulk vector. - - This method behaves like the queue_interrupt() method, except that it queues - bulk transfers and that it is based on an (array of) io vectors. - - \param vector One or more io vectors. IO vectors are standard POSIX entities. - \param vectorCount The number of elements in the \a vector array. -*/ - -/*! - \fn status_t (*usb_module_info::queue_isochronous)(usb_pipe pipe, void *data, size_t dataLength, usb_iso_packet_descriptor *packetDesc, uint32 packetCount, uint32 *startingFrameNumber, uint32 flags, usb_callback_func callback, void *callbackCookie) - \brief Asynchronously queue a isochronous transfer. Not implemented. - - This is not implemented in the current Haiku USB Stack. -*/ - -/*! - \fn status_t (*usb_module_info::queue_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, usb_callback_func callback, void *callbackCookie) - \brief Asynchronously queue a control pipe request. - - This method does roughly the same as send_request(), however, it works - asynchronously. This means that the method will return as soon as the - transfer is queued. - - \param callback The callback function for when the transfer is done. - \param callbackCookie The cookie that the stack should pass to your callback - function. - \return Whether or not the queueing of the transfer went well. The return - value won't tell you if the transfer actually succeeded. - \retval B_OK The control transfer is queued. - \retval B_NO_MEMORY Error allocating objects. - \retval B_DEV_INVALID_PIPE The \a device argument is invalid. -*/ - -/*! - \fn status_t (*usb_module_info::set_pipe_policy)(usb_pipe pipe, uint8 maxNumQueuedPackets, uint16 maxBufferDurationMS, uint16 sampleSize) - \brief Set some pipe features. - - The USB standard specifies some properties that should be able to be set on - isochronous pipes. If your driver requires the properties to be changed, you - should use this method. - - \param pipe The id of the isochronous pipe you want to alter. - \param maxNumQueuedPackets The maximum number of queued packets allowed on - this pipe. - \param maxBufferDurationMS The maximum time in ms that the buffers are valid. - \param sampleSize The size of the samples through this pipe. - \retval B_OK Pipe policy changed. - \retval B_DEV_INVALID_PIPE The \a pipe argument is invalid or not an - isochronous pipe. -*/ - -/*! - \fn status_t (*usb_module_info::cancel_queued_transfers)(usb_pipe pipe) - \brief Cancel pending transfers on a pipe. - All the pending transfers will be cancelled. The stack will perform the - callback on all of them that are cancelled. - - \attention There might be transfers that are being executed the moment you - call this method. These will be executed, and their callbacks will be - performed. Make sure you don't delete any buffers that could still be used - by these transfers. - - \param pipe The id of the pipe to clear. - - \retval B_OK All the pending transfers on this pipe are deleted. - \retval B_DEV_INVALID_PIPE The supplied usb_id is not a valid pipe. - \retval "other errors" There was an error clearing the pipe. -*/ - -/*! - \fn status_t (*usb_module_info::usb_ioctl)(uint32 opcode, void *buffer, size_t bufferSize) - \brief Low level commands to the USB stack. - - This method is used to give lowlevel commands to the Stack. There are - currently no uses documented. -*/ - -///// B_USB_MODULE_NAME ///// - -/*! - \def B_USB_MODULE_NAME - \brief The identifier string for the USB Stack interface module. -*/ +/* + * Copyright 2007 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * + * Corresponds to: + * headers/os/drivers/USB3.h rev 19915 + */ + + +/*! + \file USB3.h + \ingroup drivers + \ingroup libbe + \brief Interface for the USB module. +*/ + + +/*! + \typedef struct usb_module_info usb_module_info + \brief The main interface object. See the usb_module_info documentation. +*/ + + +/*! + \typedef uint32 usb_id + \brief Uniquely identify various USB objects that are used in the module. +*/ + + +/*! + \typedef usb_id usb_device + \brief Uniquely identify USB devices. +*/ + + +/*! + \typedef usb_id usb_interface + \brief Uniquely identify USB interfaces. +*/ + + +/*! + \typedef usb_id usb_pipe + \brief Uniquely identify USB pipes. +*/ + + +/*! + \typedef struct usb_endpoint_info usb_endpoint_info + \brief Container for USB endpoint descriptors. + \see Documentation for usb_endpoint_info. +*/ + + +/*! + \typedef struct usb_interface_info usb_interface_info + \brief Container for USB interface descriptors. + \see Documentation for usb_interface_info. +*/ + + +/*! + \typedef struct usb_interface_list usb_interface_list + \brief Container that holds a list of USB interface descriptors. + \see Documentation for usb_interface_list. +*/ + + +/*! + \typedef struct usb_configuration_info usb_configuration_info + \brief Container for USB configuration descriptors. + \see Documentation for usb_configuration_info. +*/ + + +///// usb_notify_hooks ///// + + +/*! + \struct usb_notify_hooks + \ingroup drivers + \ingroup libbe + \brief Hooks that the USB stack can callback in case of events. +*/ + + +/*! + \fn status_t (*usb_notify_hooks::device_added)(usb_device device, void **cookie) + \brief Called by the stack in case a device is added. + + Once you have registered hooks using the + usb_module_info::install_notify() method, this hook will be called as soon as + a device is inserted that matches your provided usb_support_descriptor. + + \param device A unique id that identifies this USB device. + \param[in] cookie You can store a pointer to an object in this variable. + When the device is removed, this cookie will be provided to you. + \return You should return \c B_OK in case of success. The USB stack will then + request the kernel to republish your device names so that the new device + will be shown in the \c /dev tree. If you return an error value, the + \a device id will become invalid and you will not be notified if this + device is removed. + \see device_removed() +*/ + + +/*! + \var status_t (*usb_notify_hooks::device_removed)(void *cookie) + \brief Called by the stack in case a device you are using is removed. + + If you have accepted a device in the device_added() hook, this hook will + be called as soon as the device is removed. + + \param cookie The cookie you provided in the device_added() hook. Make sure + that you free the cookie if necessary. + \return Currently the return value of this hook is ignored. It is recommended + to return \c B_OK though. +*/ + + +///// usb_support_descriptor ///// + + +/*! + \struct usb_support_descriptor + \ingroup drivers + \ingroup libbe + \brief Description of device descriptor that the driver can handle. + + Support descriptors can be used to match any form of class, subclass or + protocol, or they can be used to match a vendor and/or product. + If any field has the value \c 0, it is treated as a wildcard. + + For example, if you want to watch for all the hubs, which have a device + class of \c 0x09, you would pass this descriptor: + + \code + usb_support_descriptor hub_devs = { 9, 0, 0, 0, 0 }; + \endcode + + See usb_module_info::register_driver() for more information on how to use + this object. +*/ + + +/*! + \var usb_support_descriptor::dev_class + \brief The supported device classes. +*/ + + +/*! + \var usb_support_descriptor::dev_subclass + \brief The supported device subclasses. +*/ + + +/*! + \var usb_support_descriptor::dev_protocol + \brief The supported device protocols. +*/ + + +/*! + \var usb_support_descriptor::vendor + \brief The supported device vendor. +*/ + + +/*! + \var usb_support_descriptor::product + \brief The supported device products. +*/ + + +///// usb_endpoint_info ///// + + +/*! + \struct usb_endpoint_info + \ingroup drivers + \ingroup libbe + \brief Container for endpoint descriptors and their Haiku USB stack + identifiers. +*/ + + +/*! + \var usb_endpoint_descriptor *usb_endpoint_info::descr + \brief Pointer to the descriptor of the endpoint. +*/ + + +/*! + \var usb_pipe usb_endpoint_info::handle + \brief Handle to use when using the stack to transfer data to and from this + endpoint. +*/ + + +///// usb_interface_info ///// + + +/*! + \struct usb_interface_info + \ingroup drivers + \ingroup libbe + \brief Container for interface descriptors and their Haiku USB stack + identifiers. +*/ + + +//! @{ + + +/*! + \var usb_interface_descriptor *usb_interface_info::descr + \brief Pointer to the descriptor of the interface. +*/ + + +/*! + \var usb_interface usb_interface_info::handle + \brief Handle to use when using the stack to manipulate this interface. +*/ + + +//! @} + + +/*! + \name Endpoints +*/ + + +//! @{ + + +/*! + \var size_t usb_interface_info::endpoint_count + \brief The number of endpoints in this interface. +*/ + + +/*! + \var usb_endpoint_info *usb_interface_info::endpoint + \brief An array of endpoints that are associated to this interface. +*/ + + +//! @} + + +/*! + \name Unparsed descriptors +*/ + + +//! @{ + + +/*! + \var size_t usb_interface_info::generic_count + \brief The number of unparsed descriptors in this interface. +*/ + + +/*! + \var usb_descriptor **usb_interface_info::generic + \brief Unparsed descriptors in this interface. +*/ + + +//! @} + + +///// usb_interface_list ///// + + +/*! + \struct usb_interface_list + \ingroup drivers + \ingroup libbe + \brief List of interfaces available to a configuration. +*/ + + +/*! + \var size_t usb_interface_list::alt_count + \brief Number of available interfaces. +*/ + + +/*! + \var usb_interface_info *usb_interface_list::alt + \brief Array of available interfaces. +*/ + + +/*! + \var usb_interface_info *usb_interface_list::active + \brief Pointer to active interface. +*/ + + +///// usb_configuration_info ///// + + +/*! + \struct usb_configuration_info + \ingroup drivers + \ingroup libbe + \brief Container for a specific configuration descriptor of a device. +*/ + + +/*! + \var usb_configuration_descriptor *usb_configuration_info::descr + \brief The configuration descriptor. +*/ + + +/*! + \var size_t usb_configuration_info::interface_count + \brief The number of interfaces in this configuration. +*/ + + +/*! + \var usb_interface_list *usb_configuration_info::interface + \brief The list of interfaces available to this configuration. +*/ + + +///// usb_iso_packet_descriptor ///// + + +/*! + \struct usb_iso_packet_descriptor + \ingroup drivers + \ingroup libbe + \brief The descriptor for data packets of isochronous transfers. +*/ + + +/*! + \var int16 usb_iso_packet_descriptor::request_length + \brief Length of the request. +*/ + + +/*! + \var int16 usb_iso_packet_descriptor::actual_length + \brief The USB stack writes the actual transferred length in this variable. +*/ + + +/*! + \var status_t usb_iso_packet_descriptor::status + \brief The status of the transfer. +*/ + + +///// usb_callback_func ///// + + +/*! + \typedef typedef void (*usb_callback_func)(void *cookie, status_t status, + void *data, size_t actualLength) + \brief Callback function for asynchronous transfers. + + \param cookie The cookie you supplied when you queued the transfer. + \param status The status of the transfer. This is one of the following: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
B_OKThe transfer succeeded.
B_CANCELEDThe transfer was cancelled by the user + via a usb_module_info::cancel_queued_transfers() call.
B_DEV_MULTIPLE_ERRORSMore than one of the errors + below occurred. Unfortunately, the stack cannot give you more + information.
B_DEV_STALLEDThe endpoint is stalled. You can + use usb_module_info::clear_feature() method with the associated pipe + and the USB_FEATURE_ENDPOINT_HALT arguments.
B_DEV_DATA_OVERRUNIncoming transfer: more data + flowing in than the size of the buffer.
B_DEV_DATA_UNDERRUNOutgoing transfer: more data + is flowing out than the endpoint accepts.
B_DEV_CRC_ERRORThe internal data consistency + checks of the USB protocol failed. It is best to retry. If you keep + on getting this error there might be something wrong with the + device.
B_DEV_UNEXPECTED_PIDThere was an internal error. + You should retry your transfer.
B_DEV_FIFO_OVERRUNinternal error. + You should retry your transfer.
B_DEV_FIFO_UNDERRUNThere was an internal error. + You should retry your transfer.
+ \param data The provided buffer. + \param actualLength The amount of bytes read or written during the transfer. +*/ + + +///// usb_module_info ///// + + +/*! + \struct usb_module_info + \ingroup drivers + \ingroup libbe + \brief Interface for drivers to interact with Haiku's USB stack. +*/ + + +/*! + \var usb_module_info::binfo + \brief Instance of the bus_manager_info object. +*/ + + +/*! + \fn status_t (*usb_module_info::register_driver)(const char *driverName, const usb_support_descriptor *supportDescriptors, size_t supportDescriptorCount, const char *optionalRepublishDriverName) + \brief Register your driver. + + To let the USB stack know that a driver is available to support devices, a + driver needs to register itself first. To let the stack know about devices + it needs to notify the driver of, have a look at usb_support_descriptor. + + It is possible to supply a list of support constructors. You should allocate + an array of support constructors and give the amount of constructors in the + array using the \a supportDescriptorCount parameter. + + In case your driver supports all devices or, more likely, you want to + monitor all devices plugged in and removed, it is safe to pass \c NULL to + the \a supportDescriptors paramater and zero (0) to + \a supportDescriptorCount. + + \param driverName A unique name that identifies your driver. Avoid names + like \c webcam or \c mouse, instead use vendor names and device types to + avoid nameclashes. The install_notify() and uninstall_notify() functions use + the driver name as an identifier. + + \param supportDescriptors An array of the type usb_support_descriptor. Pass + the amount of objects in the next parameter. + \param supportDescriptorCount The number of objects in the array supplied in + the previous parameter. + \param optionalRepublishDriverName Unused parameter. You should pass + \c NULL. + + \retval B_OK The driver is registered. You can now call install_notify() + \retval B_BAD_VALUE You passed \c NULL as \a driverName. + \retval B_ERROR General internal error in the USB stack. You may retry the + request in this case. + \retval B_NO_MEMORY Error allocating some internal objects. The system is + out of memory. +*/ + + +/*! + \fn status_t (*usb_module_info::install_notify)(const char *driverName, const usb_notify_hooks *hooks) + \brief Install notify hooks for your driver. + + After your driver is registered, you need to pass hooks to your driver that + are called whenever a device that matches your \link usb_support_descriptor + support descriptor \endlink . + + As soon as the hooks are installed, you'll receive callbacks for devices + that are already attached; so make sure your driver is initialized properly + when calling this method. + + \param driverName The name you passed in register_driver(). + \param hooks The hooks the stack should call in case the status of devices + that match your support descriptor changes. + + \retval B_OK Hooks are installed succesfully. + \retval B_NAME_NOT_FOUND Invalid \a driverName. + + \see usb_notify_hooks for information on how your hooks should behave. + \see uninstall_notify() +*/ + + +/*! + \fn status_t (*usb_module_info::uninstall_notify)(const char *driverName) + \brief Uninstall notify hooks for your driver. + + If your driver needs to stop, you can uninstall the notifier hooks. This + will clear the stored hooks in the driver, and you will not receive any + notifications when new devices are attached. This method will also call + usb_notify_hooks::device_removed() for all the devices that you are using + and all the stack's resources that are allocated to your driver are + cleared. + + \param driverName The name you passed in register_driver(). + \retval B_OK Hooks are uninstalled. + \retval B_NAME_NOT_FOUND Invalid \a driverName. +*/ + + +/*! + \fn const usb_device_descriptor *(*usb_module_info::get_device_descriptor)(usb_device device) + \brief Get the device descriptor. + + \param device The id of the device you want to query. + \return The standard usb_device_descriptor, or \c NULL in case of an error. +*/ + + +/*! + \fn const usb_configuration_info *(*usb_module_info::get_nth_configuration)(usb_device device, uint index) + \brief Get a configuration descriptor by index. + + \param device The id of the device you want to query. + \param index The (zero based) offset of the list of configurations. + \return This will normally return the usb_configuration_info with the + standard usb configuration descriptor. \c NULL will be returned if the + \a id is invalid or the \a index is out of bounds. +*/ + + +/*! + \fn const usb_configuration_info *(*usb_module_info::get_configuration)(usb_device device) + \brief Get the current configuration. + + \param id The id of the device you want to query. + \retval This will return usb_configuration_info with the standard usb + configuration descriptor, or it will return\c NULL if the \a id is invalid. +*/ + + +/*! + \fn status_t (*usb_module_info::set_configuration)(usb_device device, const usb_configuration_info *configuration) + \brief Change the current configuration. + + Changing the configuration will destroy all the current endpoints. If the + \a configuration points to the current configuration, the request will be + ignored and \c B_OK will be returned. + + \param device The id of the device you want to query. + \param configuration The pointer to the new configuration you want to set. + \retval B_OK The new configuration is set succesfully. + \retval B_DEV_INVALID_PIPE The \a device parameter is invalid. + \retval B_BAD_VALUE The configuration does not exist. + + \note This method also allows you to completely unconfigure the device, which + means that all the current endpoints, pipes and transfers will be freed. + Pass \c NULL to the parameter \a configuration if you want to do that. +*/ + + +/*! + \fn status_t (*usb_module_info::set_alt_interface)(usb_device device, const usb_interface_info *interface) + \brief Set an alternative interface. Not implemented. + + This method currently always returns \c B_ERROR. +*/ + + +/*! + \fn status_t (*usb_module_info::set_feature)(usb_id handle, uint16 selector) + \brief Convenience function for standard control pipe set feature requests. + Both the set_feature() and clear_feature() requests work on all the Stack's + objects: devices, interfaces and pipes. + + \param handle The object you want to query. + \param selector The value you want to pass in the feature request. + \return \c B_OK in case the request succeeded and the device responded + positively, or an error code in case it failed. +*/ + + +/*! + \fn status_t (*usb_module_info::clear_feature)(usb_id handle, uint16 selector) + \brief Convenience function for standard control pipe clear feature requests. + + \see set_feature() to see how this method works. +*/ + + +/*! + \fn status_t (*usb_module_info::get_status)(usb_id handle, uint16 *status) + \brief Convenience function for standard usb status requests. + + \param[in] handle The object you want to query. + \param[out] status A variable in which the device can store it's status. + \return \c B_OK is returned in case the request succeeded and the device + responded positively, or an error code is returned in case it failed. +*/ + + +/*! + \fn status_t (*usb_module_info::get_descriptor)(usb_device device, + uint8 descriptorType, uint8 index, uint16 languageID, void *data, + size_t dataLength, size_t *actualLength) + \brief Convenience function to get a descriptor from a device. + + \param[in] device The device you want to query. + \param[in] descriptorType The type of descriptor you are requesting. + \param[in] index In case there are multiple descriptors of this type, you + select which one you want. + \param[in] languageID The language you want the descriptor in (if applicable, + as with string_descriptors). + \param[out] data The buffer in which the descriptor can be written. + \param[in] dataLength The size of the buffer (in bytes). + \param[out] actualLength A pointer to a variable in which the actual number + of bytes written can be stored. + + \returns A status code. + \retval B_OK The request succeeded, and the descriptor is written. + \retval B_DEV_INVALID_PIPE Invalid \a device parameter. + \retval "other errors" Request failed. +*/ + + +/*! + \fn status_t (*usb_module_info::send_request)(usb_device device, + uint8 requestType, uint8 request, uint16 value, uint16 index, + uint16 length, void *data, size_t *actualLength) + \brief Send a generic, synchronous request over the default control pipe. + + See queue_request() for an asynchronous version of this method. + + Most of the standard values of a request are defined in USB_spec.h. + + \param[in] device The device you want to query. + \param[in] requestType The request type. + \param[in] request The request you want to perform. + \param[in] value The value of the request. + \param[in] index The index for the request. + \param[in] length The size of the buffer pointed by \a data + \param[out] data The buffer where to put the result in. + \param[out] actualLength The actual numbers of bytes written. + + \returns A status code. + \retval B_OK The request succeeded. + \retval B_DEV_INVALID_PIPE Invalid \a device parameter. + \retval "other errors" Request failed. +*/ + + +/*! + \fn status_t (*usb_module_info::queue_interrupt)(usb_pipe pipe, void *data, + size_t dataLength, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue an interrupt transfer. + + \param pipe The id of the pipe you want to query. + \param data The data buffer you want to pass. + \param dataLength The size of the data buffer. + \param callback The callback function the stack should call after finishing. + \param callbackCookie A cookie that will be supplied to your callback + function when the transfer is finished. + + \return This will return a value indicating whether or not the queueing of + the transfer went well. The return value won't tell you if the transfer + actually succeeded. + \retval B_OK The interrupt transfer is queued. + \retval B_NO_MEMORY Error allocating objects. + \retval B_DEV_INVALID_PIPE The \a pipe is not a valid interrupt pipe. +*/ + +/*! + \fn status_t (*usb_module_info::queue_bulk)(usb_pipe pipe, void *data, size_t dataLength, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a bulk transfer. + + This method behaves like the queue_interrupt() method, except that it queues + a bulk transfer. +*/ + + +/*! + \fn status_t (*usb_module_info::queue_bulk_v)(usb_pipe pipe, iovec *vector, size_t vectorCount, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a bulk vector. + + This method behaves like the queue_interrupt() method, except that it queues + bulk transfers and that it is based on an (array of) io vectors. + + \param vector One or more io vectors. IO vectors are standard POSIX entities. + \param vectorCount The number of elements in the \a vector array. +*/ + + +/*! + \fn status_t (*usb_module_info::queue_isochronous)(usb_pipe pipe, void *data, size_t dataLength, usb_iso_packet_descriptor *packetDesc, uint32 packetCount, uint32 *startingFrameNumber, uint32 flags, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a isochronous transfer. Not implemented. + + This is not implemented in the current Haiku USB Stack. +*/ + + +/*! + \fn status_t (*usb_module_info::queue_request)(usb_device device, uint8 requestType, uint8 request, uint16 value, uint16 index, uint16 length, void *data, usb_callback_func callback, void *callbackCookie) + \brief Asynchronously queue a control pipe request. + + This method does roughly the same as send_request(), however, it works + asynchronously. This means that the method will return as soon as the + transfer is queued. + + \param callback The callback function for when the transfer is done. + \param callbackCookie The cookie that the stack should pass to your callback + function. + \return Whether or not the queueing of the transfer went well. The return + value won't tell you if the transfer actually succeeded. + \retval B_OK The control transfer is queued. + \retval B_NO_MEMORY Error allocating objects. + \retval B_DEV_INVALID_PIPE The \a device argument is invalid. +*/ + + +/*! + \fn status_t (*usb_module_info::set_pipe_policy)(usb_pipe pipe, uint8 maxNumQueuedPackets, uint16 maxBufferDurationMS, uint16 sampleSize) + \brief Set some pipe features. + + The USB standard specifies some properties that should be able to be set on + isochronous pipes. If your driver requires the properties to be changed, you + should use this method. + + \param pipe The id of the isochronous pipe you want to alter. + \param maxNumQueuedPackets The maximum number of queued packets allowed on + this pipe. + \param maxBufferDurationMS The maximum time in ms that the buffers are valid. + \param sampleSize The size of the samples through this pipe. + \retval B_OK Pipe policy changed. + \retval B_DEV_INVALID_PIPE The \a pipe argument is invalid or not an + isochronous pipe. +*/ + + +/*! + \fn status_t (*usb_module_info::cancel_queued_transfers)(usb_pipe pipe) + \brief Cancel pending transfers on a pipe. + All the pending transfers will be cancelled. The stack will perform the + callback on all of them that are cancelled. + + \attention There might be transfers that are being executed the moment you + call this method. These will be executed, and their callbacks will be + performed. Make sure you don't delete any buffers that could still be used + by these transfers. + + \param pipe The id of the pipe to clear. + + \retval B_OK All the pending transfers on this pipe are deleted. + \retval B_DEV_INVALID_PIPE The supplied usb_id is not a valid pipe. + \retval "other errors" There was an error clearing the pipe. +*/ + + +/*! + \fn status_t (*usb_module_info::usb_ioctl)(uint32 opcode, void *buffer, size_t bufferSize) + \brief Low level commands to the USB stack. + + This method is used to give lowlevel commands to the Stack. There are + currently no uses documented. +*/ + + +///// B_USB_MODULE_NAME ///// + + +/*! + \def B_USB_MODULE_NAME + \brief The identifier string for the USB Stack interface module. +*/ diff --git a/docs/user/drivers/USB_spec.dox b/docs/user/drivers/USB_spec.dox index 954749a21c8..f3df995eaea 100644 --- a/docs/user/drivers/USB_spec.dox +++ b/docs/user/drivers/USB_spec.dox @@ -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 + * Authors: + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * 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. + \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). + \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_IN + \brief Endpoint. In. */ + /*! - \def USB_REQTYPE_ENDPOINT_OUT - \brief Endpoint. Out. + \def USB_REQTYPE_ENDPOINT_OUT + \brief Endpoint. Out. */ + /*! - \def USB_REQTYPE_OTHER_OUT - \brief Other. Out. + \def USB_REQTYPE_OTHER_OUT + \brief Other. Out. */ + /*! - \def USB_REQTYPE_OTHER_IN - \brief Other. In. + \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_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_CLASS + \brief Request that adheres to the specifications of the class. */ + /*! - \def USB_REQTYPE_VENDOR - \brief Request that is defined by the specifications of the vendor. + \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_RESERVED + \brief Reserved for special implementations. */ + /*! - \def USB_REQTYPE_MASK - \brief Constant that can be used as mask over the requesttype field. + \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_GET_STATUS + \brief Get the status of a device. */ + /*! - \def USB_REQUEST_CLEAR_FEATURE - \brief Clear a feature. + \def USB_REQUEST_CLEAR_FEATURE + \brief Clear a feature. */ + /*! - \def USB_REQUEST_SET_FEATURE - \brief Set a feature. + \def USB_REQUEST_SET_FEATURE + \brief Set a feature. */ + /*! - \def USB_REQUEST_SET_ADDRESS - \brief Set the device address. + \def USB_REQUEST_SET_ADDRESS + \brief Set the device address. */ + /*! - \def USB_REQUEST_GET_DESCRIPTOR - \brief Get a descriptor. + \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_DESCRIPTOR + \brief Update a descriptor to a supplied one. */ + /*! - \def USB_REQUEST_GET_CONFIGURATION - \brief Get a configuration. + \def USB_REQUEST_GET_CONFIGURATION + \brief Get a configuration. */ + /*! - \def USB_REQUEST_SET_CONFIGURATION - \brief Set the configuration. + \def USB_REQUEST_SET_CONFIGURATION + \brief Set the configuration. */ + /*! - \def USB_REQUEST_GET_INTERFACE - \brief Request an interface descriptor. + \def USB_REQUEST_GET_INTERFACE + \brief Request an interface descriptor. */ + /*! - \def USB_REQUEST_SET_INTERFACE - \brief Set a specific interface. + \def USB_REQUEST_SET_INTERFACE + \brief Set a specific interface. */ + /*! - \def USB_REQUEST_SYNCH_FRAME - \brief Synchronize a frame. + \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_DEVICE + \brief Constant for the device descriptor. */ + /*! - \def USB_DESCRIPTOR_CONFIGURATION - \brief Constant for a configuration descriptor. + \def USB_DESCRIPTOR_CONFIGURATION + \brief Constant for a configuration descriptor. */ + /*! - \def USB_DESCRIPTOR_STRING - \brief Constant for a string descriptor. + \def USB_DESCRIPTOR_STRING + \brief Constant for a string descriptor. */ + /*! - \def USB_DESCRIPTOR_INTERFACE - \brief Constant for an interface descriptor. + \def USB_DESCRIPTOR_INTERFACE + \brief Constant for an interface descriptor. */ + /*! - \def USB_DESCRIPTOR_ENDPOINT - \brief Constant for an endpoint 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_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_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_CONTROL + \brief Endpoint facilitates control transfers. */ + /*! - \def USB_ENDPOINT_ATTR_ISOCHRONOUS - \brief Endpoint facilitates isochronous transfers. + \def USB_ENDPOINT_ATTR_ISOCHRONOUS + \brief Endpoint facilitates isochronous transfers. */ + /*! - \def USB_ENDPOINT_ATTR_BULK - \brief Endpoint facilitates bulk 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_INTERRUPT + \brief Endpoint facilitates interrupt transfers. */ + /*! - \def USB_ENDPOINT_ATTR_MASK - \brief Constant to mask out transfer types. + \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_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_OUT + \brief The endpoint accepts data from the host. */ -//! @} +//! @} diff --git a/docs/user/drivers/drivers.dox b/docs/user/drivers/drivers.dox index edd6ae043fb..c006105c339 100644 --- a/docs/user/drivers/drivers.dox +++ b/docs/user/drivers/drivers.dox @@ -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 */ diff --git a/docs/user/drivers/fs_interface.dox b/docs/user/drivers/fs_interface.dox index 9c50e3b2305..ec891e1afa9 100644 --- a/docs/user/drivers/fs_interface.dox +++ b/docs/user/drivers/fs_interface.dox @@ -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 diff --git a/docs/user/drivers/fs_modules.dox b/docs/user/drivers/fs_modules.dox index 2a5f8fb4d9d..e386f195a90 100644 --- a/docs/user/drivers/fs_modules.dox +++ b/docs/user/drivers/fs_modules.dox @@ -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 diff --git a/docs/user/drivers/usb_modules.dox b/docs/user/drivers/usb_modules.dox index 621e14507c9..b75cdb92ecf 100644 --- a/docs/user/drivers/usb_modules.dox +++ b/docs/user/drivers/usb_modules.dox @@ -1,386 +1,387 @@ -/* - * Copyright 2007, Haiku, Inc. All Rights Reserved. - * Distributed under the terms of the MIT License. - * - * Documentation by: - * Niels Sascha Reedijk - */ - -/*! - \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, niels.reedijk@gmail.com + */ + + +/*! + \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. +*/ diff --git a/docs/user/game/DirectWindow.dox b/docs/user/game/DirectWindow.dox index 53b042d8bd5..5530e5b7fdf 100644 --- a/docs/user/game/DirectWindow.dox +++ b/docs/user/game/DirectWindow.dox @@ -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. */ diff --git a/docs/user/game/FileGameSound.dox b/docs/user/game/FileGameSound.dox index c01c33b3498..1333957a70e 100644 --- a/docs/user/game/FileGameSound.dox +++ b/docs/user/game/FileGameSound.dox @@ -13,6 +13,8 @@ /*! \file FileGameSound.h + \ingroup game + \ingroup libbe \brief Provides the BFileGameSound class. */ diff --git a/docs/user/game/GameProducer.dox b/docs/user/game/GameProducer.dox index 4cdd9df7e37..cf0c62d75ce 100644 --- a/docs/user/game/GameProducer.dox +++ b/docs/user/game/GameProducer.dox @@ -5,8 +5,10 @@ * Authors: * Christopher ML Zumwalt May, zummy@users.sf.net * Omri Barak + * * Proofreaders: * John Scipione, jscipione@gmail.com + * * 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. */ diff --git a/docs/user/interface/AbstractLayout.dox b/docs/user/interface/AbstractLayout.dox index bf1629edfed..4e04b49d829 100644 --- a/docs/user/interface/AbstractLayout.dox +++ b/docs/user/interface/AbstractLayout.dox @@ -1,3 +1,16 @@ +/* + * Copyright 2010 Haiku, Inc. All rights reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Alex Wilson, yourpalal2@gmail.com + * + * 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. diff --git a/docs/user/interface/Alert.dox b/docs/user/interface/Alert.dox index 8cccdaa9336..657b9f72f3d 100644 --- a/docs/user/interface/Alert.dox +++ b/docs/user/interface/Alert.dox @@ -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 + * Authors: + * John Scipione, jscipione@gmail.com + * * 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 diff --git a/docs/user/interface/Bitmap.dox b/docs/user/interface/Bitmap.dox index 9180c21af6e..0c2d5fa8b08 100644 --- a/docs/user/interface/Bitmap.dox +++ b/docs/user/interface/Bitmap.dox @@ -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, axeld@pinc-software.de + * John Scipione, jscipione@gmail.com * - * Documentation by: - * Axel Dörfler - * John Scipione * 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(), diff --git a/docs/user/interface/Box.dox b/docs/user/interface/Box.dox index 2c19b694828..8faebfd2d27 100644 --- a/docs/user/interface/Box.dox +++ b/docs/user/interface/Box.dox @@ -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 * John Scipione + * * 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. diff --git a/docs/user/interface/Button.dox b/docs/user/interface/Button.dox index 9932b70da54..78b604dcdb1 100644 --- a/docs/user/interface/Button.dox +++ b/docs/user/interface/Button.dox @@ -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, jscipione@gmail.com + * * 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. */ diff --git a/docs/user/interface/CheckBox.dox b/docs/user/interface/CheckBox.dox index 95c5607de7f..56039e7da09 100644 --- a/docs/user/interface/CheckBox.dox +++ b/docs/user/interface/CheckBox.dox @@ -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, superstippi@gmx.de * Marc Flerackers, mflerackers@androme.be * John Scipione, jscipione@gmail.com + * * 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 */ diff --git a/docs/user/interface/ColorControl.dox b/docs/user/interface/ColorControl.dox index 8350e468a51..0acadb7b2a6 100644 --- a/docs/user/interface/ColorControl.dox +++ b/docs/user/interface/ColorControl.dox @@ -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, jscipione@gmail.com + * * 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 diff --git a/docs/user/interface/Control.dox b/docs/user/interface/Control.dox index c3575fe27ac..af3c7b5b584 100644 --- a/docs/user/interface/Control.dox +++ b/docs/user/interface/Control.dox @@ -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, jscipione@gmail.com + * * 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. */ diff --git a/docs/user/interface/Dragger.dox b/docs/user/interface/Dragger.dox index d86936e9a87..cba488799a9 100644 --- a/docs/user/interface/Dragger.dox +++ b/docs/user/interface/Dragger.dox @@ -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, jscipione@gmail.com * * Corresponds to: @@ -12,6 +12,8 @@ /*! \file Dragger.h + \ingroup interface + \ingroup libbe \brief Provides the BDragger class. */ diff --git a/docs/user/interface/Font.dox b/docs/user/interface/Font.dox index 71a1740d563..6e5c2b40056 100644 --- a/docs/user/interface/Font.dox +++ b/docs/user/interface/Font.dox @@ -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 + * Authors: + * John Scipione, jscipione@gmail.com + * * 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. */ diff --git a/docs/user/interface/GridLayout.dox b/docs/user/interface/GridLayout.dox index f2e709c9061..60194435d07 100644 --- a/docs/user/interface/GridLayout.dox +++ b/docs/user/interface/GridLayout.dox @@ -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 + * Authors: + * Alex Wilson, yourpalal2@gmail.com + * * 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, diff --git a/docs/user/interface/GroupLayout.dox b/docs/user/interface/GroupLayout.dox index 0749828d482..75a9ab43b5d 100644 --- a/docs/user/interface/GroupLayout.dox +++ b/docs/user/interface/GroupLayout.dox @@ -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 + * Authors: + * Alex Wilson, yourpalal2@gmail.com + * * 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. */ diff --git a/docs/user/interface/IconUtils.dox b/docs/user/interface/IconUtils.dox index 245ae36d759..a4330a33813 100644 --- a/docs/user/interface/IconUtils.dox +++ b/docs/user/interface/IconUtils.dox @@ -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 + * Authors: + * Adrien Destugues, pulkomandy@pulkomandy.ath.cx + * * 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 */ diff --git a/docs/user/interface/InterfaceDefs.dox b/docs/user/interface/InterfaceDefs.dox index f90e15196be..4bcd47c1da9 100644 --- a/docs/user/interface/InterfaceDefs.dox +++ b/docs/user/interface/InterfaceDefs.dox @@ -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, jscipione@gmail.com + * + * 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. */ diff --git a/docs/user/interface/Layout.dox b/docs/user/interface/Layout.dox index 9f9e51dc25b..627c8ebd61c 100644 --- a/docs/user/interface/Layout.dox +++ b/docs/user/interface/Layout.dox @@ -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 + * Authors: + * Alex Wilson, yourpalal2@gmail.com + * * 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'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'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'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). diff --git a/docs/user/interface/LayoutBuilder.Group.dox b/docs/user/interface/LayoutBuilder.Group.dox index 94ae3527ebe..fc68ca77877 100644 --- a/docs/user/interface/LayoutBuilder.Group.dox +++ b/docs/user/interface/LayoutBuilder.Group.dox @@ -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::View() const + \fn BView* BLayoutBuilder::Group::View() const \brief Get the BView this builder's BGroupLayout is attached to. */ @@ -361,7 +365,7 @@ /*! - \fn ThisBuilder& BLayoutBuilder::Group::GetView( + \fn ThisBuilder& BLayoutBuilder::Group::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. diff --git a/docs/user/interface/LayoutBuilder.dox b/docs/user/interface/LayoutBuilder.dox index 528a398827b..957300d207d 100644 --- a/docs/user/interface/LayoutBuilder.dox +++ b/docs/user/interface/LayoutBuilder.dox @@ -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 + * Authors: + * Alex Wilson, yourpalal2@gmail.com + * + * 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. diff --git a/docs/user/interface/LayoutItem.dox b/docs/user/interface/LayoutItem.dox index e4c069c5c9c..5d56d7c2b48 100644 --- a/docs/user/interface/LayoutItem.dox +++ b/docs/user/interface/LayoutItem.dox @@ -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 + * Authors: + * Alex Wilson, yourpalal2@gmail.com + * * 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's height constraints are dependent on its width. - + \note By default, this method returns \c false. */ diff --git a/docs/user/interface/Screen.dox b/docs/user/interface/Screen.dox index d8eb5cd9946..995dff12b9a 100644 --- a/docs/user/interface/Screen.dox +++ b/docs/user/interface/Screen.dox @@ -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, burton666@libero.it * Axel Dörfler, axeld@pinc-software.de * John Scipione, jscipione@gmail.com + * * 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 diff --git a/docs/user/interface/TwoDimensionalLayout.dox b/docs/user/interface/TwoDimensionalLayout.dox index df46a08e165..2acd2b8919a 100644 --- a/docs/user/interface/TwoDimensionalLayout.dox +++ b/docs/user/interface/TwoDimensionalLayout.dox @@ -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 + * Authors: + * Alex Wilson, yourpalal2@gmail.com + * * 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 diff --git a/docs/user/interface/View.dox b/docs/user/interface/View.dox index c8a81696b4e..c213b5fd94d 100644 --- a/docs/user/interface/View.dox +++ b/docs/user/interface/View.dox @@ -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, jscipione@gmail.com + * * 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. */ diff --git a/docs/user/interface/_interface_intro.dox b/docs/user/interface/_interface_intro.dox index 9133fd605ba..0f36cefb907 100644 --- a/docs/user/interface/_interface_intro.dox +++ b/docs/user/interface/_interface_intro.dox @@ -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 + * Authors: + * Alex Wilson, yourpalal2@gmail.com */ /*! \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 diff --git a/docs/user/interface/_layout_intro.dox b/docs/user/interface/_layout_intro.dox index 67dc7240eda..44bb17570d0 100644 --- a/docs/user/interface/_layout_intro.dox +++ b/docs/user/interface/_layout_intro.dox @@ -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 + * Authors: + * Alex Wilson, yourpalal2@gmail.com */ @@ -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. - */ - diff --git a/docs/user/interface/BAlert_example.png b/docs/user/interface/images/BAlert_example.png similarity index 100% rename from docs/user/interface/BAlert_example.png rename to docs/user/interface/images/BAlert_example.png diff --git a/docs/user/interface/BBox_example.png b/docs/user/interface/images/BBox_example.png similarity index 100% rename from docs/user/interface/BBox_example.png rename to docs/user/interface/images/BBox_example.png diff --git a/docs/user/interface/BBox_with_checkbox.png b/docs/user/interface/images/BBox_with_checkbox.png similarity index 100% rename from docs/user/interface/BBox_with_checkbox.png rename to docs/user/interface/images/BBox_with_checkbox.png diff --git a/docs/user/interface/BButton_example.png b/docs/user/interface/images/BButton_example.png similarity index 100% rename from docs/user/interface/BButton_example.png rename to docs/user/interface/images/BButton_example.png diff --git a/docs/user/interface/BCheckBox_example.png b/docs/user/interface/images/BCheckBox_example.png similarity index 100% rename from docs/user/interface/BCheckBox_example.png rename to docs/user/interface/images/BCheckBox_example.png diff --git a/docs/user/interface/BColorControl_example.png b/docs/user/interface/images/BColorControl_example.png similarity index 100% rename from docs/user/interface/BColorControl_example.png rename to docs/user/interface/images/BColorControl_example.png diff --git a/docs/user/interface/BColorControl_example_256_colors.png b/docs/user/interface/images/BColorControl_example_256_colors.png similarity index 100% rename from docs/user/interface/BColorControl_example_256_colors.png rename to docs/user/interface/images/BColorControl_example_256_colors.png diff --git a/docs/user/interface/BDragger_example.png b/docs/user/interface/images/BDragger_example.png similarity index 100% rename from docs/user/interface/BDragger_example.png rename to docs/user/interface/images/BDragger_example.png diff --git a/docs/user/interface/B_FANCY_BORDER.png b/docs/user/interface/images/B_FANCY_BORDER.png similarity index 100% rename from docs/user/interface/B_FANCY_BORDER.png rename to docs/user/interface/images/B_FANCY_BORDER.png diff --git a/docs/user/interface/B_PLAIN_BORDER.png b/docs/user/interface/images/B_PLAIN_BORDER.png similarity index 100% rename from docs/user/interface/B_PLAIN_BORDER.png rename to docs/user/interface/images/B_PLAIN_BORDER.png diff --git a/docs/user/interface/layout_tips.dox b/docs/user/interface/layout_tips.dox index 891ca1abaee..659529eef24 100644 --- a/docs/user/interface/layout_tips.dox +++ b/docs/user/interface/layout_tips.dox @@ -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 diff --git a/docs/user/locale/Catalog.dox b/docs/user/locale/Catalog.dox index d3da6b8df3c..e1358965fef 100644 --- a/docs/user/locale/Catalog.dox +++ b/docs/user/locale/Catalog.dox @@ -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, axeld@pinc-software.de * John Scipione, jscipione@gmail.com * Oliver Tappe, zooey@hirschkaefer.de - * + * * 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. */ diff --git a/docs/user/locale/Collator.dox b/docs/user/locale/Collator.dox index f126c2a5e65..aa4355a6cd5 100644 --- a/docs/user/locale/Collator.dox +++ b/docs/user/locale/Collator.dox @@ -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, jscipione@gmail.com * * 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 diff --git a/docs/user/locale/Country.dox b/docs/user/locale/Country.dox index 80231ec1d5a..1e2438aa7bc 100644 --- a/docs/user/locale/Country.dox +++ b/docs/user/locale/Country.dox @@ -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, jscipione@gmail.com * * 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. */ diff --git a/docs/user/locale/DurationFormat.dox b/docs/user/locale/DurationFormat.dox index b35c57f0141..7922ce5e731 100644 --- a/docs/user/locale/DurationFormat.dox +++ b/docs/user/locale/DurationFormat.dox @@ -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, jscipione@gmail.com * * 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 diff --git a/docs/user/locale/Locale.dox b/docs/user/locale/Locale.dox index c3ee32eef8a..66f726523cc 100644 --- a/docs/user/locale/Locale.dox +++ b/docs/user/locale/Locale.dox @@ -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, axeld@pinc-software.de. * John Scipione, jscipione@gmail.com * Oliver Tappe, zooey@hirschkaefer.de. - * + * * 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. diff --git a/docs/user/locale/LocaleRoster.dox b/docs/user/locale/LocaleRoster.dox index f65b404beda..0ea29fe8266 100644 --- a/docs/user/locale/LocaleRoster.dox +++ b/docs/user/locale/LocaleRoster.dox @@ -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, zooey@hirschkaefer.de * * 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 diff --git a/docs/user/locale/TimeZone.dox b/docs/user/locale/TimeZone.dox index d100ef759e7..53593409089 100644 --- a/docs/user/locale/TimeZone.dox +++ b/docs/user/locale/TimeZone.dox @@ -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, pulkomandy@pulkomandy.ath.cx + * John Scipione, jscipione@gmail.com + * Oliver Tappe, zooey@hirschkaefer.de * - * Documentation by: - * Adrien Destugues - * John Scipione - * Oliver Tappe * 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. */ diff --git a/docs/user/locale/UnicodeChar.dox b/docs/user/locale/UnicodeChar.dox index 91709dc4add..f4187f77e3a 100644 --- a/docs/user/locale/UnicodeChar.dox +++ b/docs/user/locale/UnicodeChar.dox @@ -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 - * John Scipione - * + * Axel Dörfler, axeld@pinc-software.de + * John Scipione, jscipione@gmail.com + * * 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 */ + /*! - \class BUnicodeChar + \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. */ diff --git a/docs/user/media/Buffer.dox b/docs/user/media/Buffer.dox index 71345f9d827..ca6a4ffb4d2 100644 --- a/docs/user/media/Buffer.dox +++ b/docs/user/media/Buffer.dox @@ -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, jscipione@gmail.com * * 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. */ diff --git a/docs/user/media/FileInterface.dox b/docs/user/media/FileInterface.dox index c91dd3a61e2..e4ef9cdc16b 100644 --- a/docs/user/media/FileInterface.dox +++ b/docs/user/media/FileInterface.dox @@ -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, jscipione@gmail.com * * 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. */ diff --git a/docs/user/midi2/Midi2Defs.dox b/docs/user/midi2/Midi2Defs.dox index 49ee5574c92..f846992c637 100644 --- a/docs/user/midi2/Midi2Defs.dox +++ b/docs/user/midi2/Midi2Defs.dox @@ -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_OFF */ + /*! -\var B_NOTE_ON + \var B_NOTE_ON */ + /*! -\var B_KEY_PRESSURE + \var B_KEY_PRESSURE */ + /*! -\var B_CONTROL_CHANGE + \var B_CONTROL_CHANGE */ + /*! -\var B_PROGRAM_CHANGE + \var B_PROGRAM_CHANGE */ + /*! -\var B_CHANNEL_PRESSURE + \var B_CHANNEL_PRESSURE */ + /*! -\var B_PITCH_BEND + \var B_PITCH_BEND */ + //! @} /*! -\name System Messages -\brief Some definitions to define the raw MIDI system messages. + \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. + 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_SYS_EX_START */ + /*! -\var B_MIDI_TIME_CODE + \var B_MIDI_TIME_CODE */ + /*! -\var B_SONG_POSITION + \var B_SONG_POSITION */ + /*! -\var B_SONG_SELECT + \var B_SONG_SELECT */ + /*! -\var B_CABLE_MESSAGE + \var B_CABLE_MESSAGE */ + /*! -\var B_TUNE_REQUEST + \var B_TUNE_REQUEST */ + /*! -\var B_SYS_EX_END + \var B_SYS_EX_END */ + /*! -\var B_TIMING_CLOCK + \var B_TIMING_CLOCK */ + /*! -\var B_START + \var B_START */ + /*! -\var B_CONTINUE + \var B_CONTINUE */ + /*! -\var B_STOP + \var B_STOP */ + /*! -\var B_ACTIVE_SENSING + \var B_ACTIVE_SENSING */ + /*! -\var B_SYSTEM_RESET + \var B_SYSTEM_RESET */ + //! @} + /*! -\name Controller Numbers -\brief Constants that represent specific controller messages. + \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. + These constants can be used in BMidiLocalProducer::SprayControlChange() + and BMidiLocalConsumer::ControlChange(). These constants represent the + MIDI specification. */ + //! @{ */ + /*! -\var B_MODULATION + \var B_MODULATION */ + /*! -\var B_BREATH_CONTROLLER + \var B_BREATH_CONTROLLER */ + /*! -\var B_FOOT_CONTROLLER + \var B_FOOT_CONTROLLER */ + /*! -\var B_PORTAMENTO_TIME + \var B_PORTAMENTO_TIME */ + /*! -\var B_DATA_ENTRY + \var B_DATA_ENTRY */ + /*! -\var B_MAIN_VOLUME + \var B_MAIN_VOLUME */ + /*! -\var B_MIDI_BALANCE + \var B_MIDI_BALANCE */ + /*! -\var B_PAN + \var B_PAN */ + /*! -\var B_EXPRESSION_CTRL + \var B_EXPRESSION_CTRL */ + /*! -\var B_GENERAL_CTRL_1 + \var B_GENERAL_CTRL_1 */ + /*! -\var B_GENERAL_CTRL_2 + \var B_GENERAL_CTRL_2 */ + /*! -\var B_GENERAL_CTRL_3 + \var B_GENERAL_CTRL_3 */ + /*! -\var B_GENERAL_CTRL_4 + \var B_GENERAL_CTRL_4 */ + /*! -\var B_SUSTAIN_PEDAL + \var B_SUSTAIN_PEDAL */ + /*! -\var B_PORTAMENTO + \var B_PORTAMENTO */ + /*! -\var B_SOSTENUTO + \var B_SOSTENUTO */ + /*! -\var B_SOFT_PEDAL + \var B_SOFT_PEDAL */ + /*! -\var B_HOLD_2 + \var B_HOLD_2 */ + /*! -\var B_GENERAL_CTRL_5 + \var B_GENERAL_CTRL_5 */ + /*! -\var B_GENERAL_CTRL_6 + \var B_GENERAL_CTRL_6 */ + /*! -\var B_TEMPO_CHANGE + \var B_TEMPO_CHANGE */ + /*! -\var B_GENERAL_CTRL_7 + \var B_GENERAL_CTRL_7 */ + /*! -\var B_GENERAL_CTRL_8 + \var B_GENERAL_CTRL_8 */ + /*! -\var B_EFFECTS_DEPTH + \var B_EFFECTS_DEPTH */ + /*! -\var B_TREMOLO_DEPTH + \var B_TREMOLO_DEPTH */ + /*! -\var B_CHORUS_DEPTH + \var B_CHORUS_DEPTH */ + /*! -\var B_CELESTE_DEPTH + \var B_CELESTE_DEPTH */ + /*! -\var B_PHASER_DEPTH + \var B_PHASER_DEPTH */ + /*! -\var B_DATA_INCREMENT + \var B_DATA_INCREMENT */ + /*! -\var B_DATA_DECREMENT + \var B_DATA_DECREMENT */ + /*! -\var B_RESET_ALL_CONTROLLERS + \var B_RESET_ALL_CONTROLLERS */ + /*! -\var B_LOCAL_CONTROL + \var B_LOCAL_CONTROL */ + /*! -\var B_ALL_NOTES_OFF + \var B_ALL_NOTES_OFF */ + /*! -\var B_OMNI_MODE_OFF + \var B_OMNI_MODE_OFF */ + /*! -\var B_OMNI_MODE_ON + \var B_OMNI_MODE_ON */ + /*! -\var B_MONO_MODE_ON + \var B_MONO_MODE_ON */ + /*! -\var B_POLY_MODE_ON + \var B_POLY_MODE_ON */ //! @} - - diff --git a/docs/user/midi2/MidiConsumer.dox b/docs/user/midi2/MidiConsumer.dox new file mode 100644 index 00000000000..03660a24f9e --- /dev/null +++ b/docs/user/midi2/MidiConsumer.dox @@ -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 (when - latency). 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 set 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 always 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. +*/ diff --git a/docs/user/midi2/MidiEndpoint.dox b/docs/user/midi2/MidiEndpoint.dox new file mode 100644 index 00000000000..7ad6768fd47 --- /dev/null +++ b/docs/user/midi2/MidiEndpoint.dox @@ -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 not 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(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(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 + not receive notifications for any local endpoints you register or + unregister. Of course, other applications will be notified about + your endpoints. + + Existing connections will not be broken when an object is unregistered, + but future remote connections will be denied. When objects are destroyed, + they automatically become unregistered. + + \returns B_OK on success, or an error code (typically \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. + + + + + +
propertyVector icon (raw data)
field name"icon"
field type'VICN'
+ + This vector icon is available under Haiku only, and comes as raw data, + not a BBitmap. Before being able to display it, you first must render + the vector icon in the size of your choice. + + + + + +
propertyLarge (32x32) icon
field name"be:large_icon"
field type'ICON'
+ + + + + +
propertySmall (16x16) icon
field name"be:mini_icon"
field type'MICN'
+ + The MidiUtil package (downloadable from the OpenBeOS website) contains a + number of convenient functions to associate icons with endpoints, so you + don't have to write that code all over again. + + \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() +*/ diff --git a/docs/user/midi2/MidiProducer.dox b/docs/user/midi2/MidiProducer.dox new file mode 100644 index 00000000000..36c1fa13604 --- /dev/null +++ b/docs/user/midi2/MidiProducer.dox @@ -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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
0xF1\c B_MIDI_TIME_CODEdata1 only
0xF2\c B_SONG_POSITIONdata1 and data2
0xF3\c B_SONG_SELECTdata1 only
0xF5\c B_CABLE_MESSAGEdata1 only
0xF6\c B_TUNE_REQUESTno data
0xF7\c B_SYS_EX_ENDno data
+ + \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: + + + + + + + +
0xf8\c B_TIMING_CLOCK
0xfa\c B_START
0xfb\c B_CONTINUE
0xfc\c B_STOP
0xfe\c B_ACTIVE_SENSING
0xff\c B_SYSTEM_RESET
+ + 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() +*/ diff --git a/docs/user/midi2/MidiRoster.dox b/docs/user/midi2/MidiRoster.dox new file mode 100644 index 00000000000..78a911c170f --- /dev/null +++ b/docs/user/midi2/MidiRoster.dox @@ -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 not + 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 any 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(endp); +} +else if (endp->IsConsumer()) +{ + cons = dynamic_cast(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. + + + + + + + + + + + + + + + + + +
be:opint32\c B_MIDI_REGISTERED
be:idint32id of the endpoint
be:typestring"producer" or "consumer"
+ + + + + + + + + + + + + + + + +
be:opint32\c B_MIDI_UNREGISTERED
be:idint32id of the endpoint
be:typestring"producer" or "consumer"
+ + 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. + + + + + + + + + + + + + + + + +
be:op\c int32\c B_MIDI_CONNECTED
be:producer\c int32id of the connector
be:consumer\c int32id of the connectee
+ + + + + + + + + + + + + + + + + +
be:op\c int32\c B_MIDI_DISCONNECTED
be:producer\c int32id of the connector
be:consumerint32id of the connectee
+ + 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. + + + + + + + + + + + + + + + + + + + + + + +
be:op\c int32\c B_MIDI_CHANGED_NAME
be:id\c int32id of the endpoint
be:typestring"producer" or "consumer"
be:namestringthe endpoint's new name
+ + + + + + + + + + + + + + + + + + + + + + +
be:op\c int32\c B_MIDI_CHANGED_LATENCY
be:id\c int32id of the endpoint
be:typestring"producer" or "consumer"
be:latencyint64the new latency (microseconds)
+ + + + + + + + + + + + + + + + + + + + + + +
be:opint32\c B_MIDI_CHANGED_PROPERTIES
be:id\c int32id of the endpoint
be:typestring"producer" or "consumer"
be:propertiesbmessagethe new properties
+ + 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. +*/ diff --git a/docs/user/midi2/midi2concepts.png b/docs/user/midi2/images/midi2concepts.png similarity index 100% rename from docs/user/midi2/midi2concepts.png rename to docs/user/midi2/images/midi2concepts.png diff --git a/docs/user/midi2/midiconsumer.dox b/docs/user/midi2/midiconsumer.dox deleted file mode 100644 index 5d6db32cb55..00000000000 --- a/docs/user/midi2/midiconsumer.dox +++ /dev/null @@ -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 (when - latency). 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 set 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 always 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 -*/ - - diff --git a/docs/user/midi2/midiendpoint.dox b/docs/user/midi2/midiendpoint.dox deleted file mode 100644 index aceafed2b25..00000000000 --- a/docs/user/midi2/midiendpoint.dox +++ /dev/null @@ -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 not 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(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(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 -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 -not receive notifications for any local endpoints you register or -unregister. Of course, other applications will be notified about your -endpoints. - -Existing connections will not be broken when an object is unregistered, but -future remote connections will be denied. When objects are destroyed, they -automatically become unregistered. - -\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. - - - - - -
propertyVector icon (raw data)
field name"icon"
field type'VICN'
- -This vector icon is available under Haiku only, and comes as raw data, not a BBitmap. -Before being able to display it, you first must render the vector icon in the size of -your choice. - - - - - -
propertyLarge (32x32) icon
field name"be:large_icon"
field type'ICON'
- - - - - -
propertySmall (16x16) icon
field name"be:mini_icon"
field type'MICN'
- -The MidiUtil package (downloadable from the OpenBeOS website) contains a number -of convenient functions to associate icons with endpoints, so you don't have to -write that code all over again. - -\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() -*/ diff --git a/docs/user/midi2/midifiles.dox b/docs/user/midi2/midifiles.dox deleted file mode 100644 index 34e2bb227d9..00000000000 --- a/docs/user/midi2/midifiles.dox +++ /dev/null @@ -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 -*/ diff --git a/docs/user/midi2/midiproducer.dox b/docs/user/midi2/midiproducer.dox deleted file mode 100644 index 11f60df9899..00000000000 --- a/docs/user/midi2/midiproducer.dox +++ /dev/null @@ -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: - - - - - - - - -
0xF1B_MIDI_TIME_CODEdata1 only
0xF2B_SONG_POSITIONdata1 and data2
0xF3B_SONG_SELECTdata1 only
0xF5B_CABLE_MESSAGEdata1 only
0xF6B_TUNE_REQUESTno data
0xF7B_SYS_EX_ENDno data
- -\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: - - - - - - - - -
0xF8B_TIMING_CLOCK
0xFAB_START
0xFBB_CONTINUE
0xFCB_STOP
0xFEB_ACTIVE_SENSING
0xFFB_SYSTEM_RESET
- -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() -*/ - - diff --git a/docs/user/midi2/midiroster.dox b/docs/user/midi2/midiroster.dox deleted file mode 100644 index c03c5fda0d2..00000000000 --- a/docs/user/midi2/midiroster.dox +++ /dev/null @@ -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 not 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 any 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(endp); -} -else if (endp->IsConsumer()) -{ - cons = dynamic_cast(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 -published 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. - - - - - -
be:opint32B_MIDI_REGISTERED
be:idint32ID of the endpoint
be:typestring"producer" or "consumer"
- - - - - -
be:opint32B_MIDI_UNREGISTERED
be:idint32ID of the endpoint
be:typestring"producer" or "consumer"
- -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 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 will be notified when another app connects one of your -published endpoints. - - - - - -
be:opint32B_MIDI_CONNECTED
be:producerint32ID of the connector
be:consumerint32ID of the connectee
- - - - - -
be:opint32B_MIDI_DISCONNECTED
be:producerint32ID of the connector
be:consumerint32ID of the connectee
- -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. - - - - - - -
be:opint32B_MIDI_CHANGED_NAME
be:idint32ID of the endpoint
be:typestring"producer" or "consumer"
be:namestringthe endpoint's new name
- - - - - - -
be:opint32B_MIDI_CHANGED_LATENCY
be:idint32ID of the endpoint
be:typestring"producer" or "consumer"
be:latencyint64the new latency (microseconds)
- - - - - - -
be:opint32B_MIDI_CHANGED_PROPERTIES
be:idint32ID of the endpoint
be:typestring"producer" or "consumer"
be:propertiesBMessagethe new properties
- -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. -*/ diff --git a/docs/user/storage/AppFileInfo.dox b/docs/user/storage/AppFileInfo.dox index d6c5d5374d3..a78c8a2b9b2 100644 --- a/docs/user/storage/AppFileInfo.dox +++ b/docs/user/storage/AppFileInfo.dox @@ -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, jscipione@gmail.com + * Ingo Weinhold, bonefish@users.sf.net * - * Documentation by: - * John Scipione - * Ingo Weinhold * 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. diff --git a/docs/user/storage/Directory.dox b/docs/user/storage/Directory.dox index e5b641b5ff1..98b1f19d903 100644 --- a/docs/user/storage/Directory.dox +++ b/docs/user/storage/Directory.dox @@ -7,6 +7,7 @@ * Ingo Weinhold, bonefish@users.sf.net * Axel Dörfler, axeld@pinc-software.de * John Scipione, jscipione@gmail.com + * * 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. */ diff --git a/docs/user/storage/Entry.dox b/docs/user/storage/Entry.dox index 7f1bd9704a6..d4b25ef9f68 100644 --- a/docs/user/storage/Entry.dox +++ b/docs/user/storage/Entry.dox @@ -6,6 +6,7 @@ * Tyler Dauwalder * Simon Cusack, scusack@users.sf.net * John Scipione, jscipione@gmail.com + * * 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. */ diff --git a/docs/user/storage/EntryList.dox b/docs/user/storage/EntryList.dox index 323852984c9..b36eb59e938 100644 --- a/docs/user/storage/EntryList.dox +++ b/docs/user/storage/EntryList.dox @@ -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, jscipione@gmail.com * * 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. */ diff --git a/docs/user/storage/File.dox b/docs/user/storage/File.dox index d6e256d2d67..786d8425fd8 100644 --- a/docs/user/storage/File.dox +++ b/docs/user/storage/File.dox @@ -15,6 +15,8 @@ /*! \file File.h + \ingroup storage + \ingroup libbe \brief Provides the BFile class. */ diff --git a/docs/user/storage/FilePanel.dox b/docs/user/storage/FilePanel.dox index b04804c050c..b9ef489cf55 100644 --- a/docs/user/storage/FilePanel.dox +++ b/docs/user/storage/FilePanel.dox @@ -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 */ diff --git a/docs/user/storage/FindDirectory.dox b/docs/user/storage/FindDirectory.dox index b507e5a119b..5b130042254 100644 --- a/docs/user/storage/FindDirectory.dox +++ b/docs/user/storage/FindDirectory.dox @@ -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 + * Adrien Destugues, pulkomandy@pulkomandy.ath.cx + * * 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 diff --git a/docs/user/storage/Mime.dox b/docs/user/storage/Mime.dox index 2488a75cbae..f7de2ca70a4 100644 --- a/docs/user/storage/Mime.dox +++ b/docs/user/storage/Mime.dox @@ -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, bonefish@users.sf.net * John Scipione, jscipione@gmail.com * @@ -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) diff --git a/docs/user/storage/MimeType.dox b/docs/user/storage/MimeType.dox index 6879b46552d..f7310f0bbff 100644 --- a/docs/user/storage/MimeType.dox +++ b/docs/user/storage/MimeType.dox @@ -7,6 +7,7 @@ * Ingo Weinhold, bonefish@users.sf.net * Axel Dörfler, axeld@pinc-software.de * John Scipione, jscipione@gmail.com + * * 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. */ diff --git a/docs/user/storage/Node.dox b/docs/user/storage/Node.dox index 861ac2dc94c..a9fcdbc2304 100644 --- a/docs/user/storage/Node.dox +++ b/docs/user/storage/Node.dox @@ -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, tylerdauwalder@users.sf.net * John Scipione, jscipione@gmail.com * Ingo Weinhold, bonefish@users.sf.net + * * 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. */ diff --git a/docs/user/storage/BFilePanel_example.png b/docs/user/storage/images/BFilePanel_example.png similarity index 100% rename from docs/user/storage/BFilePanel_example.png rename to docs/user/storage/images/BFilePanel_example.png diff --git a/docs/user/support/Archivable.dox b/docs/user/support/Archivable.dox index bb3f0b2c91e..2a7a328bd32 100644 --- a/docs/user/support/Archivable.dox +++ b/docs/user/support/Archivable.dox @@ -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, slakje@quicknet.nl * * 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. */ diff --git a/docs/user/support/Archiver.dox b/docs/user/support/Archiver.dox index a3a8fd334ae..0c2532b5d56 100644 --- a/docs/user/support/Archiver.dox +++ b/docs/user/support/Archiver.dox @@ -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, yourpalal2@gmail.com * * 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 diff --git a/docs/user/support/Autolock.dox b/docs/user/support/Autolock.dox index 6b0c6f5b9ff..ad6e27f59dc 100644 --- a/docs/user/support/Autolock.dox +++ b/docs/user/support/Autolock.dox @@ -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 + * Authors: + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * 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. - - 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: + \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. + + 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. - - 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. + \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. + + 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. */ diff --git a/docs/user/support/Beep.dox b/docs/user/support/Beep.dox index c4a30c35caf..fa5124cbfa2 100644 --- a/docs/user/support/Beep.dox +++ b/docs/user/support/Beep.dox @@ -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 + * Authors: + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * 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. - + + +/////!!!!!! 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. + \file Beep.h + \ingroup support + \ingroup libbe + \brief Functions to generate sounds from the computer. */ + /*! - \addtogroup support_globals + \addtogroup support_globals */ + //! @{ -/*! \fn status_t beep() - \brief Invoke the standard system beep to alert users. +/*! + \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) - \brief Invokes the sound for event \a 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) - \brief Adds an event to the media server. +/*! + \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. */ + //! @} diff --git a/docs/user/support/BlockCache.dox b/docs/user/support/BlockCache.dox index 15d2f963e34..44ff4cf9c48 100644 --- a/docs/user/support/BlockCache.dox +++ b/docs/user/support/BlockCache.dox @@ -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, niels.reedijk@gmail.com + * Niels Sascha Reedijk, niels.reedijk@gmail.com * * Proofreading: - * David Weizades, ddewbofh@hotmail.com + * David Weizades, ddewbofh@hotmail.com * Thom Holwerda, slakje@quicknet.nl - * + * * 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. */ diff --git a/docs/user/support/BufferIO.dox b/docs/user/support/BufferIO.dox index df9d97f9c23..81e235819c4 100644 --- a/docs/user/support/BufferIO.dox +++ b/docs/user/support/BufferIO.dox @@ -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 - * Stefano Ceccherini (burton666@libero.it) + * Authors: + * Stefano Ceccherini, burton666@libero.it + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * 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 \ - - 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 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. + \class BBufferIO + \ingroup support + \ingroup libbe + \brief A buffered adapter for BPositionIO objects. + \author Stefano Ceccherini \ + + 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. */ /*! - \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. - - \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. + + \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 + \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). - - \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 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). + + \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 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 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. - \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::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 + \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. + + \return The size of the buffer allocated by the object. */ -/*! - \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 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::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. +/*! + \fn void BBufferIO::PrintToStream() const + \brief Print the object to stdout. */ diff --git a/docs/user/support/DataIO.dox b/docs/user/support/DataIO.dox index 6fb9a8bcafd..bc6e61c2aa3 100644 --- a/docs/user/support/DataIO.dox +++ b/docs/user/support/DataIO.dox @@ -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 - * Stefano Ceccherini (burton666@libero.it) + * Authors: + * Stefano Ceccherini, burton666@libero.it + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * 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. + \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 + 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. + \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 + 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. + \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. + 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. + \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. + 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. + \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. + \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. + \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 + \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. + \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. + \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. + \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 + \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. + \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 + \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. + \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. + \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. + \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 + \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. + \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. + \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. + \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: + \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. */ - diff --git a/docs/user/support/Flattenable.dox b/docs/user/support/Flattenable.dox index 3edf9af6211..eaa4ba5b097 100644 --- a/docs/user/support/Flattenable.dox +++ b/docs/user/support/Flattenable.dox @@ -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 + * Authors: + * Niels Sascha Reedijk + * * 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 + \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 + \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]; - - // 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; - }; + 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; + }; }; - \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 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 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, - if your class actually is compatible to those formats, or a custom - four byte integer constant. + \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 virtual ssize_t BFlattenable::FlattenedSize() const = 0 - \brief Pure virtual that should return the size of the flattened object in - bytes. + \fn virtual ssize_t BFlattenable::FlattenedSize() const + \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 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 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 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) = 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 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. + \fn virtual BFlattenable::~BFlattenable() + \brief Destructor. Does nothing. */ diff --git a/docs/user/support/List.dox b/docs/user/support/List.dox index 75deacb4d31..2773cb411bd 100644 --- a/docs/user/support/List.dox +++ b/docs/user/support/List.dox @@ -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, jdrinkwater@gmail.com * * 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)) */ - //! @} diff --git a/docs/user/support/Locker.dox b/docs/user/support/Locker.dox index 41f7fd3063c..5bbe97272fe 100644 --- a/docs/user/support/Locker.dox +++ b/docs/user/support/Locker.dox @@ -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 + * Authors: + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * 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. - - 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. - - 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 + \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. + + 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 \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 some BLocker. This + BLocker will use the benaphore-style locking. - Create a new BLocker with the default name of some BLocker. This - BLocker will use the benaphore-style locking. - - \note For debugging purposes, it's extremely convenient to actually give a + \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 some BLocker. - - \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 some BLocker. + + \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. diff --git a/docs/user/support/string.dox b/docs/user/support/String.dox similarity index 89% rename from docs/user/support/string.dox rename to docs/user/support/String.dox index e3281b81df3..c6cebbce94f 100644 --- a/docs/user/support/string.dox +++ b/docs/user/support/String.dox @@ -1,16 +1,22 @@ /* - * Copyright 2007-11, Haiku, Inc. All Rights Reserved. + * Copyright 2007-2011 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * - * Documentation by: - * Niels Sascha Reedijk + * Authors: + * Stefano Ceccherini, burton666@freemail.it + * Marc Flerackers, mflerackers@androme.be + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * Oliver Tappe, openbeos@hirschaefer.de + * * Corresponds to: - * /trunk/headers/os/support/String.h rev 43319 - * /trunk/src/kits/support/String.cpp rev 42682 + * headers/os/support/String.h rev 43319 + * src/kits/support/String.cpp rev 42682 */ /*! \file String.h + \ingroup support + \ingroup libroot \brief Defines the BString class and global operators and functions for handling strings. */ @@ -24,7 +30,7 @@ BString is a string allocation and manipulation class. The object takes care to allocate and free memory for you, so it will always be "big enough" to store your strings. - + While BString is in essence a wrapper around a byte-array, which can always be accessed with the BString::String() method, it does have some understanding of UTF-8 and it can be used for the manipulation of UTF-8 @@ -32,28 +38,28 @@ that operates on UTF-8 strings. See for example the BString::CopyInto() and BString::CopyCharsInto() methods. The main difference is that if there are any position argumens, the regular method counts the bytes and the - *Chars-methods counts characters. - - \author Marc Flerackers \ - \author Stefano Ceccherini \ - \author Oliver Tappe \ + Chars methods counts characters. */ + /*! \fn BString::BString() \brief Creates an empty BString. */ + /*! \fn BString::BString(const char* string) \brief Creates and initializes a BString from a \a string. */ + /*! \fn BString::BString(const BString &string) \brief Creates and initializes a BString from another BString. */ + /*! \fn BString::BString(const char *string, int32 maxLength) \brief Creates and initializes a BString from a \a string up to @@ -67,6 +73,7 @@ the entire \a string. */ + /*! \fn BString::~BString() \brief Free all resources associated with the object. @@ -79,8 +86,10 @@ \name Access Methods */ + //! @{ + /*! \fn const char* BString::String() const \brief Return a pointer to the object string, \c NUL terminated. @@ -91,23 +100,24 @@ If you want to manipulate the internal string of the object directly, have a look at LockBuffer(). - + \return A pointer to the object string. */ + /*! \fn int32 BString::Length() const \brief Get the length of the string in bytes. \return An integer with the length of the string, measured in bytes. \sa CountChars() - */ + /*! \fn int32 BString::CountChars() const \brief Returns the length of the object measured in characters. - + BString is aware of UTF8 characters, so this method will count the actual number of characters in the string. @@ -115,50 +125,55 @@ \sa Length() */ + /*! \fn int32 BString::CountBytes(int32 fromCharOffset, int32 charCount) const \brief Count the number of bytes starting from a specified character - + BString is somewhat aware of UTF8 characters, which can take up more than one byte. With this method you can count the number of bytes a subset of the string contains. - + \warning This method does not check whether the input is outside of the boundaries, so make sure that you check your input values. - + \param fromCharOffset The index of the character (not the byte!) from which to start the count \param charCount The number of characters to count - + \return An integer with the number of bytes. */ + /*! \fn bool BString::IsEmpty() const \brief Check whether the string is empty. - + \return Returns \c true if the string is empty. */ + /*! \fn uint32 BString::HashValue() const \brief Return a hash value for the current string - + \sa HashValue(const char *string) */ + /*! \fn static uint32 BString::HashValue(const char* string) \brief Return the hash value of a specified \c string - + This allows you to use the BString::HashValue() method on any arbitrary - \c string. - + \c string. + \param string The string that you want to have hashed. - + \sa HashValue() */ + //! @} @@ -172,20 +187,23 @@ use one of the SetTo() methods for more advanced copying. */ + //! @{ + /*! \fn BString& BString::operator=(const BString &string) \brief Re-initialize the object to a copy of the data of a BString. \param string The string object to copy. - \return The function always returns \c *this . + \return The function always returns \c *this. \sa Adopt(BString &from) \sa SetTo(const BString &string, int32 length) */ + /*! \fn BString& BString::operator=(const char *str) \brief Re-initialize the object to a copy of the data of a string. @@ -193,6 +211,7 @@ \sa SetTo(const char *str, int32 maxLength) */ + /*! \fn BString& BString::operator=(char c) \brief Re-initialize the object to a character. @@ -200,6 +219,7 @@ \param c The character which you want to initialize the string to. */ + /*! \fn BString& BString::SetTo(const char *str) \brief Re-initialize the object to a copy of the data of a string. @@ -209,6 +229,7 @@ \sa SetTo(const char *str, int32 maxLength) */ + /*! \fn BString& BString::SetTo(const char *str, int32 maxLength) \brief Re-initialize the object to a copy of the data of a string. @@ -219,18 +240,20 @@ \sa operator=(const char *str) */ + /*! \fn BString& BString::SetTo(const BString &from) \brief Re-initialize the object to a copy of the data of a BString. \param from The string object to copy. - \return The function always returns \c *this . + \return The function always returns \c *this. \sa SetTo(const BString &string, int32 length) \sa Adopt(BString &from) */ + /*! \fn BString& BString::Adopt(BString &from) \brief Adopt the data of the given BString object. @@ -243,11 +266,12 @@ \param from The string object to adopt. - \return The function always returns \c *this . + \return The function always returns \c *this. \sa operator=(const BString &string) */ + /*! \fn BString& BString::SetTo(const BString &string, int32 maxLength) \brief Re-initialize the string to a copy of the given BString object. @@ -255,12 +279,13 @@ \param string The BString object to copy. \param maxLength Amount of characters to copy from the original BString. - \return The function always returns \c *this . + \return The function always returns \c *this. \sa operator=(const BString &string) \sa Adopt(BString &from, int32 maxLength) */ + /*! \fn BString& BString::Adopt(BString &from, int32 maxLength) \brief Adopt the data of the given BString object up to \a maxLength @@ -269,11 +294,12 @@ \param from The string object to adopt. \param maxLength Number of characters to adopt from the original BString. - \return The function always returns \c *this . + \return The function always returns \c *this. \sa SetTo(const BString &string, int32 maxLength) */ + /*! \fn BString& BString::SetTo(char c, int32 count) \brief Re-initialize the object to a string composed of a character you @@ -285,31 +311,36 @@ \param c The character you want to initialize the BString. \param count The length of the string. - \return The function always returns \c *this . + \return The function always returns \c *this. \sa operator=(char c) */ + /*! \fn BString& BString::SetToChars(const char *string, int32 charCount) \brief Undocumented */ + /*! \fn BString& BString::SetToChars(const BString& string, int32 charCount) \brief Undocumented */ + /*! \fn BString& BString::AdoptChars(BString& from, int32 charCount) \brief Undocumented */ + /*! \fn BString& BString::SetToFormat(const char *format, ...) \brief Undocumented */ + //! @} @@ -317,8 +348,10 @@ \name Substring Copying */ + //! @{ + /*! \fn BString &BString::CopyInto(BString &into, int32 fromOffset, int32 length) const @@ -336,6 +369,7 @@ \c into parameter. */ + /*! \fn void BString::CopyInto(char *into, int32 fromOffset, int32 length) const \brief Copy the BString data (or part of it) into the supplied buffer. @@ -351,81 +385,92 @@ \param length The amount of bytes to copy. */ + /*! \fn BString& BString::CopyCharsInto(BString& into, int32 fromOffset, int32 charCount) const \brief Undocumented */ + /*! \fn bool BString::CopyCharsInto(char* into, int32* intoLength, int32 fromCharOffset, int32 charCount) const \brief Undocumented */ + //! @} + /*! \name Appending Methods */ + //! @{ + /*! \fn BString & BString::operator+=(const BString &string) \brief Append the given string to the object \param string The string to append - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Append(const BString &string, int32 length) */ + /*! \fn BString& BString::operator+=(const char *str) \brief Append the given string to the object. \param str A pointer to the NULL-terminated string to append. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Append(const char *str, int32 length) */ + /*! \fn BString& BString::operator+=(char c) \brief Append the given character to the object. \param c The character to append. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Append(char c, int32 count) */ + /*! \fn BString & BString::operator+=(const BString &string) \brief Append the given string to the object \param string The string to append - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Append(const BString &string, int32 length) */ + /*! \fn BString &BString::Append(const BString &string) \brief Append the given string to the object \param string The string to append - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Append(const BString &string, int32 length) */ + /*! \fn BString &BString::Append(const char *str) \brief Append the given string to the object. @@ -435,6 +480,7 @@ \sa Append(const char *str, int32 length) */ + /*! \fn BString& BString::Append(const BString &string, int32 length) \brief Append a part of the given BString to the object. @@ -442,11 +488,12 @@ \param string The BString to append. \param length The maximum number ofbytes to get from the original object. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa operator+=(const BString &string) */ + /*! \fn BString& BString::Append(const char *str, int32 length) \brief Append a part of the given string to the object. @@ -454,11 +501,12 @@ \param str A pointer to the string to append. \param length The maximum bytes to get from the original string. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa operator+=(const char *str) */ + /*! \fn BString& BString::Append(char c, int32 count) \brief Append the given character repeatedly to the object. @@ -466,21 +514,24 @@ \param c The character to append. \param count The number of times this character should be appended. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa operator+=(char c) */ + /*! \fn BString& BString::AppendChars(const BString& string, int32 charCount) \brief undocumented */ + /*! \fn BString& BString::AppendChars(const char *string, int32 charCount) \brief undocumented */ + //! @} @@ -488,30 +539,34 @@ \name Prepending Methods */ + //! @{ + /*! \fn BString& BString::Prepend(const char *str) \brief Prepend the given string to the object. \param str A pointer to the string to prepend. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Prepend(const char *str, int32 length) */ + /*! \fn BString& BString::Prepend(const BString &string) \brief Prepend the given BString to the object. \param string The BString object to prepend. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Prepend(const BString &string, int32 len) */ + /*! \fn BString& BString::Prepend(const char *str, int32 length) \brief Prepend the given string to the object. @@ -519,11 +574,12 @@ \param str A pointer to the string to prepend. \param length The maximum amount of bytes to get from the string. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Prepend(const char *str) */ + /*! \fn BString& BString::Prepend(const BString &string, int32 length) \brief Prepend the given BString to the object. @@ -531,11 +587,12 @@ \param string The BString object to prepend. \param length The maximum amount of bytes to get from the BString. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Prepend(const BString &string) */ + /*! \fn BString& BString::Prepend(char c, int32 count) \brief Prepend the given character repeatedly to the object. @@ -543,19 +600,22 @@ \param c The character to prepend. \param count The number of times this character should be prepended. - \return This method always returns \c *this . + \return This method always returns \c *this. */ + /*! \fn BString& BString::PrependChars(const char *string, int32 charCount) \brief undocumented */ + /*! \fn BString& BString::PrependChars(const BString& string, int32 charCount) \brief undocumented */ + //! @} @@ -563,8 +623,10 @@ \name Inserting Methods */ + //! @{ + /*! \fn BString& BString::Insert(const char *string, int32 position) \brief Insert the given string at the given position into the object's @@ -574,12 +636,13 @@ \param position The offset in bytes into the BString's data where to insert the string. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Insert(const char *string, int32 length, int32 position) \sa Insert(const char *string, int32 fromOffset, int32 length, int32 position) */ + /*! \fn BString& BString::Insert(const char *string, int32 length, int32 position) \brief Inserts the given string at the given position into the object's @@ -590,12 +653,13 @@ \param position The offset in bytes into the BString's data where to insert the string. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Insert(const char *string, int32 position) \sa Insert(const char *string, int32 fromOffset, int32 length, int32 position) */ + /*! \fn BString& BString::Insert(const char *string, int32 fromOffset, int32 length, int32 position) @@ -608,12 +672,13 @@ \param position The offset in bytes into the BString's data where to insert the string. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Insert(const char *string, int32 position) \sa Insert(const char *string, int32 length, int32 position) */ + /*! \fn BString& BString::Insert(const BString &string, int32 position) \brief Insert the given BString at the given position into the object's @@ -622,12 +687,13 @@ \param position The offset in bytes into the BString's data where to insert the string. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Insert(const BString &string, int32 length, int32 position) \sa Insert(const BString &string, int32 fromOffset, int32 length, int32 position) */ + /*! \fn BString& BString::Insert(const BString &string, int32 length, int32 position) \brief Insert the given BString at the given position into the object's @@ -637,12 +703,13 @@ \param position The offset in bytes into the BString's data where to insert the string. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Insert(const BString &string, int32 position) \sa Insert(const BString &string, int32 fromOffset, int32 length, int32 position) */ + /*! \fn BString& BString::Insert(const BString &string, int32 fromOffset, int32 length, int32 position) @@ -655,12 +722,13 @@ \param position The offset in bytes into the BString's data where to insert the string. - \return This method always returns \c *this . + \return This method always returns \c *this. \sa Insert(const BString &string, int32 position) \sa Insert(const BString &string, int32 length, int32 position) */ + /*! \fn BString& BString::Insert(char c, int32 count, int32 pos) \brief Insert the given character repeatedly at the given position @@ -671,43 +739,50 @@ \param pos The offset in bytes into the BString's data where to insert the string. - \return This method always returns \c *this . + \return This method always returns \c *this. */ + /*! \fn BString& BString::InsertChars(const char *string, int32 charPosition) \brief Undocumented */ + /*! \fn BString& BString::InsertChars(const char* string, int32 charCount, int32 charPosition) \brief Undocumented */ + /*! \fn BString& BString::InsertChars(const char* string, int32 fromCharOffset, int32 charCount, int32 charPosition) \brief Undocumented */ + /*! \fn BString& BString::InsertChars(const BString& string, int32 charPosition) \brief Undocumented */ + /*! \fn BString& BString::InsertChars(const BString& string, int32 charCount, int32 charPosition) \brief Undocumented */ + /*! \fn BString& BString::InsertChars(const BString& string, int32 fromCharOffset, int32 charCount, int32 charPosition) \brief Undocumented */ + //! @} @@ -715,8 +790,10 @@ \name Removing Methods */ + //! @{ + /*! \fn BString& BString::Truncate(int32 newLength, bool lazy) \brief Truncate the string to the new length. @@ -724,14 +801,16 @@ \param newLength The new length of the string. \param lazy If true, the memory-optimization is postponed to later - \return This method always returns \c *this . + \return This method always returns \c *this. */ + /*! \fn BString& BString::TruncateChars(int32 newCharCount, bool lazy) \brief Undocumented */ + /*! \fn BString& BString::Remove(int32 from, int32 length) \brief Remove some bytes, starting at the given offset @@ -739,82 +818,92 @@ \param from The offset from which you want to start removing \param length The number of bytes to remove - \return This function always returns \c *this . + \return This function always returns \c *this. */ + /*! \fn BString& BString::RemoveChars(int32 fromCharOffset, int32 charCount) \brief Undocumented */ + /*! \fn BString& BString::RemoveFirst(const BString &string) \brief Remove the first occurrence of the given BString. \param string The BString to remove. - \return This function always returns \c *this . + \return This function always returns \c *this. */ + /*! \fn BString& BString::RemoveLast(const BString &string) \brief Remove the last occurrence of the given BString. \param string The BString to remove. - \return This function always returns \c *this . + \return This function always returns \c *this. */ + /*! \fn BString& BString::RemoveAll(const BString &string) \brief Remove all occurrences of the given BString. \param string The BString to remove. - \return This function always returns \c *this . + \return This function always returns \c *this. */ + /*! \fn BString& BString::RemoveFirst(const char *string) \brief Remove the first occurrence of the given string. \param string A pointer to the string to remove. - \return This function always returns \c *this . + \return This function always returns \c *this. */ + /*! \fn BString& BString::RemoveLast(const char *string) \brief Remove the last occurrence of the given string. \param string A pointer to the string to remove. - \return This function always returns \c *this . + \return This function always returns \c *this. */ + /*! \fn BString& BString::RemoveAll(const char *str) \brief Remove all occurrences of the given string. \param str A pointer to the string to remove. - \return This function always returns \c *this . + \return This function always returns \c *this. */ + /*! \fn BString& BString::RemoveSet(const char *setOfCharsToRemove) \brief Remove all the characters specified. \param setOfCharsToRemove The set of characters to remove. - \return This function always returns \c *this . + \return This function always returns \c *this. */ + /*! \fn BString& BString::RemoveCharsSet(const char*setOfCharsToRemove) \brief Undocumented */ + /*! \fn BString& BString::MoveInto(BString &into, int32 from, int32 length) \brief Move the BString data (or part of it) into another BString. @@ -826,6 +915,7 @@ \return This method always returns \c into . */ + /*! \fn void BString::MoveInto(char *into, int32 from, int32 length) \brief Move the BString data (or part of it) into the given buffer. @@ -835,18 +925,21 @@ \param length The amount of bytes to move. */ + /*! \fn BString& BString::MoveCharsInto(BString &into, int32 fromCharOffset, int32 charCount) \brief Undocumented */ + /*! \fn bool BString::MoveCharsInto(char* into, int32* intoLength, int32 fromCharOffset, int32 charCount) \brief Undocumented */ + //! @} @@ -865,225 +958,250 @@ there are the same as implemented in this class. */ + //! @{ + /*! \fn bool BString::operator<(const BString &string) const - \brief Lexographically compare if this string is less than a given string. + \brief Lexicographically compare if this string is less than a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator<=(const BString &string) const - \brief Lexographically compare if this string is less than or equal to + \brief Lexicographically compare if this string is less than or equal to a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator==(const BString &string) const - \brief Lexographically compare if this string is equal to a given string. + \brief Lexicographically compare if this string is equal to a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator>=(const BString &string) const - \brief Lexographically compare if this string is more than or equal + \brief Lexicographically compare if this string is more than or equal to a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator>(const BString &string) const - \brief Lexographically compare if this string is more than a given string. + \brief Lexicographically compare if this string is more than a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator!=(const BString &string) const - \brief Lexographically compare if this string is not equal to a given + \brief Lexicographically compare if this string is not equal to a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator<(const char *string) const - \brief Lexographically compare if this string is less than a given string. + \brief Lexicographically compare if this string is less than a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator<=(const char *string) const - \brief Lexographically compare if this string is less than or equal to + \brief Lexicographically compare if this string is less than or equal to a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator==(const char *string) const - \brief Lexographically compare if this string is equal to a given string. + \brief Lexicographically compare if this string is equal to a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator>=(const char *string) const - \brief Lexographically compare if this string is more than or equal + \brief Lexicographically compare if this string is more than or equal to a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator>(const char *string) const - \brief Lexographically compare if this string is more than a given string. + \brief Lexicographically compare if this string is more than a given string. \param string The string to compare with. */ + /*! \fn bool BString::operator!=(const char *string) const - \brief Lexographically compare if this string is not equal to a given + \brief Lexicographically compare if this string is not equal to a given string. \param string The string to compare with. */ + /*! \fn BString::operator const char*() const \brief Undocumented */ + /*! \fn int BString::Compare(const BString &string) const - \brief Lexographically compare this string to another. + \brief Lexicographically compare this string to another. \param string The string to compare to. - \retval >0 The object sorts lexographically after \c string. + \retval >0 The object sorts lexicographically after \c string. \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexographically before \c string. + \retval <0 The object sorts lexicographically before \c string. */ + /*! \fn int BString::Compare(const char *string) const - \brief Lexographically compare this string to another. + \brief Lexicographically compare this string to another. \param string The string to compare to. - \retval >0 The object sorts lexographically after \c string. + \retval >0 The object sorts lexicographically after \c string. \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexographically before \c string. + \retval <0 The object sorts lexicographically before \c string. \sa Compare(const BString &string) const */ + /*! \fn int BString::Compare(const BString &string, int32 length) const - \brief Lexographically compare a number of characters of a string to + \brief Lexicographically compare a number of characters of a string to another. \param string The string to compare to. \param length The number of characters to compare - \retval >0 The object sorts lexographically after \c string. + \retval >0 The object sorts lexicographically after \c string. \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexographically before \c string. + \retval <0 The object sorts lexicographically before \c string. */ + /*! \fn int BString::Compare(const char *string, int32 length) const - \brief Lexographically compare a number of characters of a string to + \brief Lexicographically compare a number of characters of a string to another. \param string The string to compare to. \param length The number of characters to compare. - \retval >0 The object sorts lexographically after \c string. + \retval >0 The object sorts lexicographically after \c string. \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexographically before \c string. + \retval <0 The object sorts lexicographically before \c string. \sa Compare(const BString &string, int32 n) const */ + /*! \fn int BString::CompareChars(const BString& string, int32 charCount) const \brief Undocumented */ + /*! \fn int BString::CompareChars(const char *string, int32 charCount) const \brief Undocumented */ + /*! \fn int BString::ICompare(const BString &string) const - \brief Lexographically compare a string to another in a + \brief Lexicographically compare a string to another in a case-insensitive way. \param string The string to compare to. - \retval >0 The object sorts lexographically after \c string. + \retval >0 The object sorts lexicographically after \c string. \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexographically before \c string. + \retval <0 The object sorts lexicographically before \c string. \sa Compare(const BString &string) const */ + /*! \fn int BString::ICompare(const char* string) const - \brief Lexographically compare this string to another in a + \brief Lexicographically compare this string to another in a case-insensitive way. \param string The string to compare to. - \retval >0 The object sorts lexographically after \c string. + \retval >0 The object sorts lexicographically after \c string. \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexographically before \c string. + \retval <0 The object sorts lexicographically before \c string. \sa Compare(const BString &string) const */ + /*! \fn int BString::ICompare(const BString& string, int32 length) const - \brief Lexographically compare a number of characters of this string + \brief Lexicographically compare a number of characters of this string to another. \param string The string to compare to. \param length The number of characters to compare - \retval >0 The object sorts lexographically after \c string. + \retval >0 The object sorts lexicographically after \c string. \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexographically before \c string. + \retval <0 The object sorts lexicographically before \c string. \sa Compare(const BString &string, int32 length) const */ + /*! \fn int BString::ICompare(const char* string, int32 length) const - \brief Lexographically compare a number of characters of this string + \brief Lexicographically compare a number of characters of this string to another. \param string The string to compare to. \param length The number of characters to compare - \retval >0 The object sorts lexographically after \c string. + \retval >0 The object sorts lexicographically after \c string. \retval =0 The object is equal to \c string. - \retval <0 The object sorts lexographically before \c string. + \retval <0 The object sorts lexicographically before \c string. \sa Compare(const BString &string, int32 length) const */ + //! @} @@ -1091,8 +1209,10 @@ \name Searching Methods */ + //! @{ + /*! \fn int32 BString::FindFirst(const BString &string) const \brief Find the first occurrence of the given BString. @@ -1107,6 +1227,7 @@ \sa IFindFirst(const BString &string) const */ + /*! \fn int32 BString::FindFirst(const char *string) const \brief Find the first occurrence of the given string. @@ -1122,6 +1243,7 @@ \sa IFindFirst(const char *string) const */ + /*! \fn int32 BString::FindFirst(const BString &string, int32 fromOffset) const \brief Find the first occurrence of the given BString, starting from @@ -1138,6 +1260,7 @@ \sa IFindFirst(const BString &string, int32 fromOffset) const */ + /*! \fn int32 BString::FindFirst(const char *string, int32 fromOffset) const \brief Find the first occurrence of the given string, @@ -1155,6 +1278,7 @@ \sa IFindFirst(const char *string, int32 fromOffset) const */ + /*! \fn int32 BString::FindFirst(char c) const \brief Find the first occurrence of the given character. @@ -1167,6 +1291,7 @@ \retval B_ERROR Could not find \c c. */ + /*! \fn int32 BString::FindFirst(char c, int32 fromOffset) const \brief Find the first occurrence of the given character, @@ -1181,18 +1306,21 @@ \retval B_ERROR Could not find \c c. */ + /*! \fn int32 BString::FindFirstChars(const BString& string, int32 fromCharOffset) const \brief Undocumented */ + /*! \fn int32 BString::FindFirstChars(const char *string, int32 fromCharOffset) const \brief Undocumented */ + /*! \fn int32 BString::FindLast(const BString &string) const \brief Find the last occurrence of the given BString. @@ -1206,6 +1334,7 @@ \sa IFindLast(const BString &string) const */ + /*! \fn int32 BString::FindLast(const char *string) const \brief Find the last occurrence of the given string. @@ -1221,6 +1350,7 @@ \sa IFindLast(const char *string) const /*! + /*! \fn int32 BString::FindLast(const BString &string, int32 beforeOffset) const \brief Find the last occurrence of the given BString, @@ -1237,6 +1367,7 @@ \sa IFindLast(const BString &string, int32 beforeOffset) const */ + /*! \fn int32 BString::FindLast(const char *string, int32 beforeOffset) const \brief Find the last occurrence of the given string, @@ -1254,6 +1385,7 @@ \sa IFindLast(const char *string, int32 beforeOffset) const */ + /*! \fn int32 BString::FindLast(char c) const \brief Find the last occurrence of the given character. @@ -1265,6 +1397,7 @@ \retval B_ERROR Could not find \c c. */ + /*! \fn int32 BString::FindLast(char c, int32 beforeOffset) const \brief Find the last occurrence of the given character, @@ -1279,18 +1412,21 @@ \retval B_ERROR Could not find \c c. */ + /*! \fn int32 BString::FindLastChars(const BString& string, int32 beforeCharOffset) const \brief Undocumented */ + /*! \fn int32 BString::FindLastChars(const char *string, int32 beforeCharOffset) const \brief Undocumented */ + /*! \fn int32 BString::IFindFirst(const BString &string) const \brief Find the first occurrence of the given BString case-insensitively. @@ -1298,6 +1434,7 @@ \sa FindFirst(const BString &string) const */ + /*! \fn int32 BString::IFindFirst(const char *string) const \brief Find the first occurrence of the given BString case-insensitively. @@ -1305,6 +1442,7 @@ \sa FindFirst(const char *string) const */ + /*! \fn int32 BString::IFindFirst(const BString &string, int32 fromOffset) const \brief Find the first occurrence of the given BString case-insensitively, @@ -1313,6 +1451,7 @@ \sa FindFirst(const BString &string, int32 fromOffset) const */ + /*! \fn int32 BString::IFindFirst(const char *string, int32 fromOffset) const \brief Find the first occurrence of the given string case-insensitively, @@ -1321,6 +1460,7 @@ \sa FindFirst(const char *string, int32 fromOffset) const */ + /*! \fn int32 BString::IFindLast(const BString &string) const \brief Find the last occurrence of the given BString case-insensitively. @@ -1328,13 +1468,15 @@ \sa FindLast(const BString &string) const */ + /*! \fn int32 BString::IFindLast(const char *string) const \brief Find the last occurrence of the given string case-insensitively. - + \sa FindLast(const char *string) const */ + /*! \fn int32 BString::IFindLast(const BString &string, int32 beforeOffset) const \brief Find the last occurrence of the given BString case-insensitively, @@ -1343,6 +1485,7 @@ \sa FindLast(const BString &string, int32 beforeOffset) const */ + /*! \fn int32 BString::IFindLast(const char *string, int32 beforeOffset) const \brief Find the last occurrence of the given string case-insensitively, @@ -1351,6 +1494,7 @@ \sa FindLast(const char *string, int32 beforeOffset) const */ + //! @} @@ -1358,8 +1502,10 @@ \name Replacing Methods */ + //! @{ + /*! \fn BString& BString::ReplaceFirst(char replaceThis, char withThis) \brief Replace the first occurrence of a character with another character. @@ -1372,6 +1518,7 @@ \sa IReplaceFirst(char replaceThis, char withThis) */ + /*! \fn BString& BString::ReplaceLast(char replaceThis, char withThis) \brief Replace the last occurrence of a character with another character. @@ -1384,6 +1531,7 @@ \sa ReplaceLast(char replaceThis, char withThis) */ + /*! \fn BString& BString::ReplaceAll(char replaceThis, char withThis, int32 fromOffset) @@ -1398,6 +1546,7 @@ \sa IReplaceAll(char replaceThis, char withThis, int32 fromOffset) */ + /*! \fn BString& BString::Replace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) @@ -1416,6 +1565,7 @@ int32 fromOffset) */ + /*! \fn BString& BString::ReplaceFirst(const char *replaceThis, const char *withThis) @@ -1429,6 +1579,7 @@ \sa IReplaceFirst(const char *replaceThis, const char *withThis) */ + /*! \fn BString& BString::ReplaceLast(const char *replaceThis, const char *withThis) @@ -1442,6 +1593,7 @@ \sa IReplaceLast(const char *replaceThis, const char *withThis) */ + /*! \fn BString& BString::ReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) @@ -1457,6 +1609,7 @@ int32 fromOffset) */ + /*! \fn BString& BString::Replace(const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset) @@ -1474,18 +1627,21 @@ int32 maxReplaceCount, int32 fromOffset) */ + /*! \fn BString& BString::ReplaceAllChars(const char* replaceThis, const char* withThis, int32 fromCharOffset) \brief Undocumented */ + /*! \fn BString& BString::ReplaceChars(const char* replaceThis, const char* withThis, int32 maxReplceCount, int32 fromCharOffset) \brief Undocumented */ + /*! \fn BString& BString::IReplaceFirst(char replaceThis, char withThis) \brief Replace the first occurrence of a character with another @@ -1497,6 +1653,7 @@ \sa ReplaceFirst(char replaceThis, char withThis) */ + /*! \fn BString& BString::IReplaceLast(char replaceThis, char withThis) \brief Replace the last occurrence of a character with another @@ -1508,6 +1665,7 @@ \sa ReplaceLast(char replaceThis, char withThis) */ + /*! \fn BString& BString::IReplaceAll(char replaceThis, char withThis, int32 fromOffset) @@ -1521,6 +1679,7 @@ \sa ReplaceAll(char replaceThis, char withThis, int32 fromOffset) */ + /*! \fn BString& BString::IReplace(char replaceThis, char withThis, int32 maxReplaceCount, int32 fromOffset) @@ -1550,6 +1709,7 @@ \sa ReplaceFirst(const char *replaceThis, const char *withThis) */ + /*! \fn BString& BString::IReplaceLast(const char *replaceThis, const char *withThis) @@ -1561,6 +1721,7 @@ \sa ReplaceLast(const char *replaceThis, const char *withThis) */ + /*! \fn BString& BString::IReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) @@ -1574,6 +1735,7 @@ \sa ReplaceAll(const char *replaceThis, const char *withThis, int32 fromOffset) */ + /*! \fn BString& BString::IReplace(const char *replaceThis, const char *withThis, int32 maxReplaceCount, int32 fromOffset) @@ -1590,6 +1752,7 @@ int32 maxReplaceCount, int32 fromOffset) */ + /*! \fn BString& BString::ReplaceSet(const char* setOfBytes, char with) \brief Replaces characters that are in a certain set with a chosen @@ -1601,6 +1764,7 @@ \return This method always returns \c *this. */ + /*! \fn BString& BString::ReplaceSet(const char* setOfBytes, const char* with) \brief Replaces characters that are in a certain set with a chosen string. @@ -1611,12 +1775,14 @@ \return This method always returns \c *this. */ + /*! \fn BString& BString::ReplaceCharsSet(const char* setOfChars, const char* with) \brief Undocumented */ + // @} @@ -1624,8 +1790,10 @@ \name Character Access */ + //! @{ + /*! \fn char& BString::operator[](int32 index) \brief Return a reference to the data at the given offset. @@ -1641,6 +1809,7 @@ \sa ByteAt(int32 index) for a safer version. */ + /*! \fn char BString::operator[](int32 index) const \brief Returns the character in the string at the given offset. @@ -1654,6 +1823,7 @@ \return Returns a reference to the specified byte. */ + /*! \fn char BString::ByteAt(int32 index) const \brief Returns the character in the string at the given offset. @@ -1666,17 +1836,20 @@ bounds, it will return 0. */ + /*! \fn const char* BString::CharAt(int32 charIndex, int32* bytes) const \brief Undocumented */ + /*! \fn bool BString::CharAt(int32 charIndex, char* buffer, int32* bytes) const \brief Undocumented */ + //! @} @@ -1684,8 +1857,10 @@ \name Low-Level Manipulation */ + //! @{ + /*! \fn char* BString::LockBuffer(int32 maxLength) \brief Locks the buffer and return the internal string for manipulation. @@ -1705,6 +1880,7 @@ \sa UnlockBuffer() */ + /*! \fn BString& BString::UnlockBuffer(int32 length) \brief Unlocks the buffer after you are done with lowlevel manipulation. @@ -1716,6 +1892,7 @@ \return This method always returns \c *this. */ + //! @} @@ -1723,26 +1900,31 @@ \name Case Manipulation */ + //! @{ + /*! \fn BString& BString::ToLower() \brief Convert the BString to lowercase. - \return This method always returns \c *this . + \return This method always returns \c *this. */ + /*! \fn BString& BString::ToUpper() \brief Convert the BString to uppercase. - \return This method always returns \c *this . + \return This method always returns \c *this. */ + /*! \fn BString& BString::Capitalize() \brief Convert the first character to uppercase, rest to lowercase - \return This method always returns \c *this . + \return This method always returns \c *this. */ + /*! \fn BString& BString::CapitalizeEachWord() \brief Convert the first character of every word to uppercase, rest @@ -1752,14 +1934,15 @@ characters separated by non alphabetical characters) to uppercase, and the rest to lowercase. - \return This method always returns \c *this . + \return This method always returns \c *this. */ + //! @} /*! - \name Escaping and Deescaping Methods + \name Escaping and De-escaping Methods This class contains some methods to help you with escaping and de-escaping certain characters. Note that this is the C-style of @@ -1768,8 +1951,10 @@ are replaced by something else. */ + //! @{ + /*! \fn BString& BString::CharacterEscape(const char* original, const char* setOfCharsToEscape, char escapeWith) @@ -1789,6 +1974,7 @@ \sa CharacterDeescape(const char *original, char escapeChar) */ + /*! \fn BString& BString::CharacterEscape(const char* setOfCharsToEscape, char escapeWith) @@ -1802,6 +1988,7 @@ \sa CharacterDeescape(char escapeChar) */ + /*! \fn BString& BString::CharacterDeescape(const char* original, char escapeChar) @@ -1819,6 +2006,7 @@ char escapeWith) */ + /*! \fn BString& BString::CharacterDeescape(char escapeChar) \brief Remove the character to escape with from this string. @@ -1830,110 +2018,132 @@ \sa CharacterEscape(const char *setOfCharsToEscape, char escapeWith) */ + //! @} + /*! \name Trimming methods */ + //! @{ + /*! \fn BString& BString::Trim() \brief Undocumented */ + //! @} + /*! \name Simple sprintf Replacement Methods These methods may be slower than sprintf(), but they are overflow safe. */ + //! @{ + /*! \fn BString& BString::operator<<(const char *string) \brief Append the string \a string. */ + /*! \fn BString& BString::operator<<(const BString &string) \brief Append the BString \a string. */ + /*! \fn BString& BString::operator<<(char c) \brief Append the \c char \a c. */ + /*! \fn BString& BString::operator<<(bool value) \brief Append the boolean \c value to the string. - + In case the \a value is true, the string \c true is appended to the string. Otherwise, the string \c false is appended. */ + /*! \fn BString& BString::operator<<(int value) \brief Convert the \c int \a value to a string and append it. */ + /*! \fn BString& BString::operator<<(unsigned int value) \brief Convert the \c unsigned \c int \a value to a string and append it. */ + /*! \fn BString& BString::operator<<(unsigned long value) \brief Convert the \c unsigned \c long \a value to a string and append it. */ + /*! \fn BString& BString::operator<<(long value) \brief Convert the \c long \a value to a string and append it. */ + /*! \fn BString& BString::operator<<(unsigned long long value) \brief Convert the \c unsigned \c long \c long \a value to a string and append it. */ + /*! \fn BString& BString::operator<<(long long value) \brief Convert the \c long \c long \a value to a string and append it. */ + /*! \fn BString& BString::operator<<(float value) \brief Convert the \c float \a value to a string and append it. - + Using this operator will append in the \c %.2f style formatting. */ + /*! \fn BString& BString::operator<<(double value) \brief Convert the \c double \a value to a string and append it. - + Using this operator will append in the \c %.2f style formatting. */ + //! @} -/************* end of class BString, start of general operators ************/ +/************* end of BString class, start of general operators ************/ /*! \addtogroup support_globals */ + //! @{ + /*! \fn bool operator<(const char *a, const BString &b) - \brief Lexographically compare if \c a is less than a given BString. + \brief Lexicographically compare if \c a is less than a given BString. From String.h and in libbe.so. @@ -1943,9 +2153,10 @@ \sa BString::operator<(const char *string) const */ + /*! \fn bool operator<=(const char *a, const BString &b) - \brief Lexographically compare if \c a is less than or equal to a + \brief Lexicographically compare if \c a is less than or equal to a given BString. From String.h and in libbe.so. @@ -1956,9 +2167,10 @@ \sa BString::operator<=(const char *string) const */ + /*! \fn bool operator==(const char *a, const BString &b) - \brief Lexographically compare if \c a is equal to a given BString. + \brief Lexicographically compare if \c a is equal to a given BString. From String.h and in libbe.so. @@ -1968,9 +2180,10 @@ \sa BString::operator==(const char *string) const */ + /*! \fn bool operator>(const char *a, const BString &b) - \brief Lexographically compare if \c a is more than a given BString. + \brief Lexicographically compare if \c a is more than a given BString. From String.h and in libbe.so. @@ -1980,9 +2193,10 @@ \sa BString::operator>(const char *string) const */ + /*! \fn bool operator>=(const char *a, const BString &b) - \brief Lexographically compare if \c a is more than or equal to a + \brief Lexicographically compare if \c a is more than or equal to a given BString. From String.h and in libbe.so. @@ -1993,9 +2207,10 @@ \sa BString::operator>=(const char *string) const */ + /*! \fn bool operator!=(const char *a, const BString &b) - \brief Lexographically compare if \c a is not equal to given BString. + \brief Lexicographically compare if \c a is not equal to given BString. From String.h and in libbe.so. @@ -2005,9 +2220,10 @@ \sa BString::operator!=(const char *string) const */ + /*! \fn int Compare(const BString &a, const BString &b) - \brief Lexographically compare two strings. + \brief Lexicographically compare two strings. This function is useful if you need a global compare function to feed to BList::SortItems() for example. @@ -2020,9 +2236,10 @@ \sa BString::Compare(const BString &string) const */ + /*! \fn int ICompare(const BString &a, const BString &b) - \brief Lexographically compare two strings in a case insensitive way. + \brief Lexicographically compare two strings case-insensitively. This function is useful if you need a global compare function to feed to BList::SortItems() for example. @@ -2035,9 +2252,10 @@ \sa BString::Compare(const BString &string) const */ + /*! \fn int Compare(const BString *a, const BString *b) - \brief Lexographically compare two strings. + \brief Lexicographically compare two strings. This function is useful if you need a global compare function to feed to BList::SortItems() for example. @@ -2050,9 +2268,10 @@ \sa BString::Compare(const BString &string) const */ + /*! \fn int ICompare(const BString *a, const BString *b) - \brief Lexographically compare two strings in a case insensitive way. + \brief Lexicographically compare two strings case-insensitively. This function is useful if you need a global compare function to feed to BList::SortItems() for example. @@ -2065,5 +2284,5 @@ \sa BString::Compare(const BString &string) const */ -//! @} +//! @} diff --git a/docs/user/support/SupportDefs.dox b/docs/user/support/SupportDefs.dox index 104e600d9cb..8c29d42a892 100644 --- a/docs/user/support/SupportDefs.dox +++ b/docs/user/support/SupportDefs.dox @@ -1,57 +1,71 @@ /* - * 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 + * Authors: + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * Corresponds to: - * /trunk/headers/os/support/SupportDefs.h rev 35018 + * headers/os/support/SupportDefs.h rev 35018 */ + /*! - \file SupportDefs.h - \ingroup support - \brief Defines basic types and definitions for the Haiku API. + \file SupportDefs.h + \ingroup support + \ingroup libbe + \brief Defines basic types and definitions for the Haiku API. */ + /*! - \name Fixed-Size Integer Types + \name Fixed-Size Integer Types */ + //! @{ + /*! - \typedef typedef __haiku_int8 int8 + \typedef typedef __haiku_int8 int8 */ + /*! - \typedef typedef __haiku_uint8 uint8 + \typedef typedef __haiku_uint8 uint8 */ + /*! - \typedef typedef __haiku_int16 int16 + \typedef typedef __haiku_int16 int16 */ + /*! - \typedef typedef __haiku_uint16 uint16 + \typedef typedef __haiku_uint16 uint16 */ + /*! - \typedef typedef __haiku_int32 int32 + \typedef typedef __haiku_int32 int32 */ + /*! - \typedef typedef __haiku_uint32 uint32 + \typedef typedef __haiku_uint32 uint32 */ + /*! - \typedef typedef __haiku_int64 int64 + \typedef typedef __haiku_int64 int64 */ + /*! - \typedef typedef __haiku_uint64 uint64 + \typedef typedef __haiku_uint64 uint64 */ + //! @} @@ -59,40 +73,50 @@ \name Fixed-size Volatile Types */ + //! @{ - + + /*! - \typedef typedef volatile int8 vint8 + \typedef typedef volatile int8 vint8 */ + /*! - \typedef typedef volatile uint8 vuint8 + \typedef typedef volatile uint8 vuint8 */ + /*! - \typedef typedef volatile int16 vint16 + \typedef typedef volatile int16 vint16 */ + /*! - \typedef typedef volatile uint16 vuint16 + \typedef typedef volatile uint16 vuint16 */ + /*! - \typedef typedef volatile int32 vint32 + \typedef typedef volatile int32 vint32 */ + /*! - \typedef typedef volatile uint32 vuint32 + \typedef typedef volatile uint32 vuint32 */ + /*! - \typedef typedef volatile int64 vint64 + \typedef typedef volatile int64 vint64 */ + /*! - \typedef typedef volatile uint64 vuint64 + \typedef typedef volatile uint64 vuint64 */ + //! @} @@ -100,445 +124,569 @@ \name Short-hand Volatile Type Names */ + //! @{ + /*! - \typedef typedef volatile long vlong + \typedef typedef volatile long vlong */ + /*! - \typedef typedef volatile int vint + \typedef typedef volatile int vint */ + /*! - \typedef typedef volatile short vshort + \typedef typedef volatile short vshort */ + /*! - \typedef typedef volatile char vchar + \typedef typedef volatile char vchar */ + /*! - \typedef typedef volatile unsigned long vulong + \typedef typedef volatile unsigned long vulong */ + /*! - \typedef typedef volatile unsigned int vuint + \typedef typedef volatile unsigned int vuint */ + /*! - \typedef typedef volatile unsigned short vushort + \typedef typedef volatile unsigned short vushort */ + /*! - \typedef typedef volatile unsigned char vuchar + \typedef typedef volatile unsigned char vuchar */ + //! @} -/*! \name Character Type Formats */ +/*! + \name Character Type Formats +*/ + //! @{ + /*! - \typedef typedef unsigned char uchar + \typedef typedef unsigned char uchar */ + /*! - \typedef typedef unsigned short unichar + \typedef typedef unsigned short unichar */ + //! @} -/*! \name Descriptive Type Formats */ + +/*! + \name Descriptive Type Formats +*/ + //! @{ + /*! - \typedef typedef int32 status_t + \typedef typedef int32 status_t \brief Represents one of the status codes defined in Error.h */ + /*! - \typedef typedef int64 bigtime_t + \typedef typedef int64 bigtime_t \brief Represents time. The unit depends on the context of the function. */ + /*! - \typedef typedef int64 nanotime_t + \typedef typedef int64 nanotime_t \brief Represents time in nanoseconds. */ + /*! - \typedef typedef uint32 type_code + \typedef typedef uint32 type_code \brief Represents a certain type of data. See TypeConstants.h for - possible values. + possible values. */ + /*! - \typedef typedef uint32 perform_code - \brief Unused. Defined by Be to support 'hidden' commands or - extensions to classes. The Haiku API has none of these. + \typedef typedef uint32 perform_code + \brief Defined to support 'hidden' commands or extensions to classes. + + The Haiku API has none of these. */ + //! @} -/*! \name Format strings for printf()/scanf() */ +/*! + \name Format strings for printf() and scanf() +*/ + //! @{ + /*! \def B_PRId8 */ + /*! \def B_PRIi8 */ + /*! \def B_PRId16 */ + /*! \def B_PRIi16 */ + /*! \def B_PRId32 */ + /*! \def B_PRIi32 */ + /*! \def B_PRId64 */ + /*! \def B_PRIi64 */ + /*! \def B_PRIu8 */ + /*! \def B_PRIo8 */ + /*! \def B_PRIx8 */ + /*! \def B_PRIX8 */ + /*! \def B_PRIu16 */ + /*! \def B_PRIo16 */ + /*! \def B_PRIx16 */ + /*! \def B_PRIX16 */ + /*! \def B_PRIu32 */ + /*! \def B_PRIo32 */ + /*! \def B_PRIx32 */ + /*! \def B_PRIX32 */ + /*! \def B_PRIu64 */ + /*! \def B_PRIo64 */ + /*! \def B_PRIx64 */ + /*! \def B_PRIX64 */ + /*! \def B_SCNd8 */ + /*! \def B_SCNi8 */ + /*! \def B_SCNd16 */ + /*! \def B_SCNi16 */ + /*! \def B_SCNd32 */ + /*! \def B_SCNi32 */ + /*! \def B_SCNd64 */ + /*! \def B_SCNi64 */ + /*! \def B_SCNu8 */ + /*! \def B_SCNo8 */ + /*! \def B_SCNx8 */ + /*! \def B_SCNu16 */ + /*! \def B_SCNo16 */ + /*! \def B_SCNx16 */ + /*! \def B_SCNu32 */ + /*! \def B_SCNo32 */ + /*! \def B_SCNx32 */ + /*! \def B_SCNu64 */ + /*! \def B_SCNo64 */ + /*! \def B_SCNx64 */ + //! @} -/*! \name Format strings for several standard types */ +/*! + \name Format strings for several standard types +*/ + //! @{ + /*! \def B_PRIuSIZE \brief size_t */ + /*! \def B_PRIoSIZE \brief size_t */ + /*! \def B_PRIxSIZE \brief size_t */ + /*! \def B_PRIXSIZE \brief size_t */ + /*! \def B_PRIdSSIZE \brief ssize_t */ + /*! \def B_PRIiSSIZE \brief ssize_t */ + /*! \def B_PRIuADDR \brief addr_t */ + /*! \def B_PRIoADDR \brief addr_t */ + /*! \def B_PRIxADDR \brief addr_t */ + /*! \def B_PRIXADDR \brief addr_t */ + /*! \def B_PRIdOFF \brief off_t */ + /*! \def B_PRIiOFF \brief off_t */ + /*! \def B_PRIdDEV \brief dev_t */ + /*! \def B_PRIiDEV \brief dev_t */ + /*! \def B_PRIdINO \brief ino_t */ + /*! \def B_PRIiINO \brief ino_t */ + /*! \def B_PRIdTIME \brief time_t */ + /*! \def B_PRIiTIME \brief time_t */ + //! @} + //////////////// Odds and ends + -/*! \var const char *B_EMPTY_STRING +/*! + \var const char *B_EMPTY_STRING \brief Defines an empty string. Currently defined as the string "". */ -/*! \def min_c(a,b) + +/*! + \def min_c(a,b) \brief Returns the minimum of the values a and b. \note When including this header in a C file, use the C equivalent called \c min(a,b). */ -/*! \def max_c(a,b) + +/*! + \def max_c(a,b) \brief Returns the maximum of values a and b. \note When including this header in a C file, use the C equivalent called \c max(a,b). */ -/*! \def NULL - \brief Defines the constant \c NULL if it hasn't been defined - anywhere before. + +/*! + \def NULL + \brief Defines the constant \c NULL if it hasn't already been defined. +*/ + + +/*! + \addtogroup support_globals */ -/*! \addtogroup support_globals */ //! @{ + /*! \fn int32 atomic_set(vint32 *value, int32 newValue) \brief Atomically set the variable \a value to \a newvalue. - + This is a thread-safe way of performing the \c *value \c = \c newValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a mutex in this case. - - \return The original value of \c value. - - \sa atomic_set64() for a version that works on \c long \c long - \sa atomic_test_and_set(), atomic_add(), atomic_and(), atomic_or(), - atomic_get() + + \return The original value of \c value. + + \sa atomic_set64() for a version that works on \c long \c long. + \sa atomic_test_and_set() + \sa atomic_add() + \sa atomic_and() + \sa atomic_or(), + \sa atomic_get() */ + /*! \fn int32 atomic_test_and_set(vint32 *value, int32 newValue, int32 testAgainst) \brief Atomically set the variable \a value to \a newValue if the current - value is \a testAgainst. + value is \a testAgainst. This is a thread-safe way of conditionally performing the \c *value \c += \c newValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a mutex in this case. - + \return The original value of \c value. - \sa atomic_test_and_set64() for a version that works on \c long \c long - \sa atomic_set(), atomic_add(), atomic_and(), atomic_or(), atomic_get() + \sa atomic_test_and_set64() for a version that works on \c long \c long. + \sa atomic_set() + \sa atomic_add() + \sa atomic_and() + \sa atomic_or() + \sa atomic_get() */ -/*! \fn int32 atomic_add(vint32 *value, int32 addValue) + +/*! + \fn int32 atomic_add(vint32 *value, int32 addValue) \brief Atomically add the value of \a addValue to \a value. - + This is a thread-safe way of performing the \c *value \c += \c addValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a mutex in this case. - + \return The original value of \c value. - \sa atomic_add64() for a version that works on \c long \c long - \sa atomic_set(), atomic_test_and_set(), atomic_and(), atomic_or(), - atomic_get() + \sa atomic_add64() for a version that works on \c long \c long. + \sa atomic_set() + \sa atomic_test_and_set() + \sa atomic_and() + \sa atomic_or() + \sa atomic_get() */ + /*! \fn int32 atomic_and(vint32 *value, int32 andValue) \brief Atomically perform a bitwise AND operation of \a andValue to the variable \a andValue. @@ -550,15 +698,20 @@ \return The original value of \c value. - \sa atomic_and64() for a version that works on \c long \c long - \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_or(), - atomic_get() + \sa atomic_and64() for a version that works on \c long \c long. + \sa atomic_set() + \sa atomic_test_and_set() + \sa atomic_add() + \sa atomic_or() + \sa atomic_get() */ -/*! \fn int32 atomic_or(vint32 *value, int32 orValue) + +/*! + \fn int32 atomic_or(vint32 *value, int32 orValue) \brief Atomically perform a bitwise OR operation of \a orValue to the - variable \a andValue. + variable \a andValue. This is a thread-safe way of performing the \c *value \c |= \c orValue operation. You should use these function when two or more threads might @@ -567,12 +720,17 @@ \return The original value of \c value. - \sa atomic_or64() for a version that works on \c long \c long - \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(), - atomic_get() + \sa atomic_or64() for a version that works on \c long \c long. + \sa atomic_set() + \sa atomic_test_and_set() + \sa atomic_add() + \sa atomic_and() + \sa atomic_get() */ -/*! \fn int32 atomic_get(vint32 *value) + +/*! + \fn int32 atomic_get(vint32 *value) \brief Atomically return the value of \c value. This is a thread-safe way of reading the contents of the \c value @@ -582,12 +740,17 @@ \return The original value of \c value. - \sa atomic_get64() for a version that works on \c long \c long - \sa atomic_set(), atomic_test_and_set(), atomic_add(), atomic_and(), - atomic_or() + \sa atomic_get64() for a version that works on \c long \c long. + \sa atomic_set() + \sa atomic_test_and_set() + \sa atomic_add() + \sa atomic_and() + \sa atomic_or() */ -/*! \fn int64 atomic_set64(vint64 *value, int64 newValue) + +/*! + \fn int64 atomic_set64(vint64 *value, int64 newValue) \brief Atomically set the variable \a value to \a newvalue. This is a thread-safe way of performing the \c *value \c = \c newValue @@ -597,16 +760,21 @@ \return The original value of \c value. - \sa atomic_set() for a version that works on an \c int32 - \sa atomic_test_and_set64(), atomic_add64(), atomic_and64(), - atomic_or64(), atomic_get64() + \sa atomic_set() for a version that works on an \c int32. + \sa atomic_test_and_set64() + \sa atomic_add64() + \sa atomic_and64() + \sa atomic_or64() + \sa atomic_get64() */ -/*! \fn int64 atomic_test_and_set64(vint64 *value, int64 newValue, + +/*! + \fn int64 atomic_test_and_set64(vint64 *value, int64 newValue, int64 testAgainst) \brief Atomically set the variable \a value to \a newValue if the current value is \a testAgainst. - + This is a thread-safe way of conditionally performing the \c *value \c += \c newValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't @@ -614,14 +782,19 @@ \return The original value of \c value. - \sa atomic_test_and_set() for a version that works on an \c int32 - \sa atomic_set64(), atomic_add64(), atomic_and64(), - atomic_or64(), atomic_get64() + \sa atomic_test_and_set() for a version that works on an \c int32. + \sa atomic_set64() + \sa atomic_add64() + \sa atomic_and64() + \sa atomic_or64() + \sa atomic_get64() */ -/*! \fn int64 atomic_add64(vint64 *value, int64 addValue) + +/*! + \fn int64 atomic_add64(vint64 *value, int64 addValue) \brief Atomically add the value of \a addValue to \a value. - + This is a thread-safe way of performing the \c *value \c += \c addValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a @@ -629,30 +802,39 @@ \return The original value of \c value. - \sa atomic_add() for a version that works on an \c int32 - \sa atomic_set64(), atomic_test_and_set64(), atomic_and64(), - atomic_or64(), atomic_get64() + \sa atomic_add() for a version that works on an \c int32. + \sa atomic_set64() + \sa atomic_test_and_set64() + \sa atomic_and64() + \sa atomic_or64() + \sa atomic_get64() */ -/*! \fn int64 atomic_and64(vint64 *value, int64 andValue) - \brief Atomically perform a bitwise AND operation of \a andValue to the - variable \a andValue. + +/*! + \fn int64 atomic_and64(vint64 *value, int64 andValue) + \brief Atomically perform a bitwise AND operation of \a andValue to the + variable \a andValue. This is a thread-safe way of performing the \c *value \c &= \c andValue operation. You should use these function when two or more threads might access the variable simultaneously. You don't have to use a semaphore or a - mutex in this case. + mutex in this case. \return The original value of \c value. - \sa atomic_and() for a version that works on an \c int32 - \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), - atomic_or64(), atomic_get64() + \sa atomic_and() for a version that works on an \c int32. + \sa atomic_set64() + \sa atomic_test_and_set64() + \sa atomic_add64() + \sa atomic_or64() + \sa atomic_get64() */ + /*! \fn int64 atomic_or64(vint64 *value, int64 orValue) - \brief Atomically perform a bitwise OR operation of \a orValue to the - variable \a andValue. + \brief Atomically perform a bitwise OR operation of \a orValue to the + variable \a andValue. This is a thread-safe way of performing the \c *value \c |= \c orValue operation. You should use these function when two or more threads might @@ -661,12 +843,17 @@ \return The original value of \c value. - \sa atomic_or() for a version that works on an \c int32 - \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), atomic_and64(), - atomic_get64() + \sa atomic_or() for a version that works on an \c int32. + \sa atomic_set64() + \sa atomic_test_and_set64() + \sa atomic_add64() + \sa atomic_and64() + \sa atomic_get64() */ -/*! \fn int64 atomic_get64(vint64 *value) + +/*! + \fn int64 atomic_get64(vint64 *value) \brief Atomically return the value of \c value. This is a thread-safe way of reading the contents of the \c value @@ -676,29 +863,43 @@ \return The original value of \c value. - \sa atomic_get() for a version that works on an \c int32 - \sa atomic_set64(), atomic_test_and_set64(), atomic_add64(), - atomic_and64(), atomic_or64() + \sa atomic_get() for a version that works on an \c int32. + \sa atomic_set64() + \sa atomic_test_and_set64() + \sa atomic_add64() + \sa atomic_and64() + \sa atomic_or64() */ + //! @} -/*! \fn void* get_stack_frame(void) - \brief Internal function. - \internal + +/*! + \fn void* get_stack_frame(void) + \brief Internal function. + \internal +*/ + + +/*! + \name Deprecated defines */ -/*! \name Deprecated defines */ //! @{ -/*! \def FALSE + +/*! + \def FALSE \brief Obsolete. Use \c false. */ -/*! \def TRUE + +/*! + \def TRUE \brief Obsolete. Use \c true. */ -//! @} +//! @} diff --git a/docs/user/support/TLS.dox b/docs/user/support/TLS.dox index 4378f98048b..6d5d44e0173 100644 --- a/docs/user/support/TLS.dox +++ b/docs/user/support/TLS.dox @@ -3,122 +3,140 @@ * Distributed under the terms of the MIT License. * * Authors: - * Niels Sascha Reedijk + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * Corresponds to: - * /trunk/headers/os/support/TLS.h rev 19972 + * headers/os/support/TLS.h rev 19972 */ - + + /*! - \file TLS.h - \ingroup support - \brief Functions to use Thread Local Storage. - - The Thread Local Storage API provides convenient methods to transform global - variables in to thread-context sensetive variables. Some applications rely on - global variables as a way of intercommunicating between functions and - objects, but one of your demands might be that the contents of that variable - differs between threads. - - The following example demonstrates how an imaginary thread manager that - stores per thread data would function. The constructor of this - \c ThreadManager allocates the TLS variables using tls_allocate(). This only - has to be done once, and not in every spawned thread! Then, every spawned - thread that interacts with this thread manager, should call the - \c InitThread() function. This one associates the supplied thread data with - the TLS index using tls_set(). Each thread can get their associated data with - \c GetCurrentThreadData(), which uses tls_get() to retrieve the associated - thread data at the provided index. - - \code + \file TLS.h + \ingroup support + \ingroup libroot + \brief Functions to use Thread Local Storage. + + The Thread Local Storage API provides convenient methods to transform global + variables in to thread-context sensitive variables. Some applications rely on + global variables as a way of intercommunicating between functions and + objects, but one of your demands might be that the contents of that variable + differs between threads. + + The following example demonstrates how an imaginary thread manager that + stores per thread data would function. The constructor of this + \c ThreadManager allocates the TLS variables using tls_allocate(). This only + has to be done once, and not in every spawned thread! Then, every spawned + thread that interacts with this thread manager, should call the + \c InitThread() function. This one associates the supplied thread data with + the TLS index using tls_set(). Each thread can get their associated data with + \c GetCurrentThreadData(), which uses tls_get() to retrieve the associated + thread data at the provided index. + +\code int32 gThreadName; int32 gThreadData; class ThreadManager { public: - // General initialisation - ThreadManager() { - gThreadName = tls_allocate(); - gThreadStatus = tls_allocate(); - }; - - // Called from the thread entry function - void InitThread(const char *name, void *data) { - tls_set(gThreadName, (void *)name); - tls_set(gThreadData, data); - }; - - // Can be called from any of the threads. The returned data will be that - // which the thread explicitly set in the InitThread() function - void *GetCurrentThreadData() { - printf("Thread %s asked for its data.\n", (const char*)tls_get(gThreadName)); - return tls_get(gThreadData); - }; + // General initialisation + ThreadManager() { + gThreadName = tls_allocate(); + gThreadStatus = tls_allocate(); + }; + + // Called from the thread entry function + void InitThread(const char *name, void *data) { + tls_set(gThreadName, (void *)name); + tls_set(gThreadData, data); + }; + + // Can be called from any of the threads. The returned data will be that + // which the thread explicitly set in the InitThread() function + void *GetCurrentThreadData() { + printf("Thread %s asked for its data.\n", + (const char*)tls_get(gThreadName)); + return tls_get(gThreadData); + }; }; - \endcode - - \note - -# It is impossible to get data other than from your thread. - -# There is a limit to the number of TLS variables you can allocate. This - limit is define by #TLS_MAX_KEYS, but do realize that you share this - limit with all the libraries your application is linked to. - -# The actual global variables, in the example \c gThreadName and - \c gThreadData, are only indexes. You cannot use these variables to - access data without the TLS API. +\endcode + + \note + -# It is impossible to get data other than from your thread. + -# There is a limit to the number of TLS variables you can allocate. This + limit is define by #TLS_MAX_KEYS, but do realize that you share this + limit with all the libraries your application is linked to. + -# The actual global variables, in the example \c gThreadName and + \c gThreadData, are only indexes. You cannot use these variables to + access data without the TLS API. */ + /*! - \def TLS_MAX_KEYS - \brief The maximum number of thread local storage variables. This number is - process wide. + \def TLS_MAX_KEYS + \brief The maximum number of thread local storage variables. This number is + process wide. */ + /*! - \fn int32 tls_allocate(void) - \brief Allocate a unique index to use for storing variables. - - You should only have to do this once to allocate the global index, which you - can reuse in every thread. - - \return A unique index to which you can associate per thread data. If we - overrun the maximum number of keys, as defined by #TLS_MAX_KEYS, the - function will return \c B_NO_MEMORY. - - \see tls_get(), tls_set(), tls_address() + \fn int32 tls_allocate(void) + \brief Allocate a unique index to use for storing variables. + + You should only have to do this once to allocate the global index, which + you can reuse in every thread. + + \return A unique index to which you can associate per thread data. If we + overrun the maximum number of keys, as defined by #TLS_MAX_KEYS, + the function will return \c B_NO_MEMORY. + + \sa tls_get() + \sa tls_set() + \sa tls_address() */ + /*! - \fn void *tls_get(int32 index) - \brief Retrieve the data stored for this thread at the provided \a index. - - \param index The \a index that you retrieved with tls_allocate(). - \return The data you set using tls_set() for this thread, or \c NULL if there - is no data set, or the \a index is invalid. - \see tls_allocate(), tls_set() + \fn void *tls_get(int32 index) + \brief Retrieve the data stored for this thread at the provided \a index. + + \param index The \a index that you retrieved with tls_allocate(). + + \return The data you set using tls_set() for this thread, or \c NULL if there + is no data set, or the \a index is invalid. + + \sa tls_allocate() + \sa tls_set() */ + /*! - \fn void **tls_address(int32 index) - \brief Retrieve the pointer that refers to the data of this thread at the + \fn void **tls_address(int32 index) + \brief Retrieve the pointer that refers to the data of this thread at the provided \a index. - - You can use this pointer to directly manipulate your thread data. - - \param index The \a index that you retrieved with tls_allocate(). - \return The pointer to where your thread's data is, or \c NULL if the index - is invalid. - \see tls_allocate(), tls_set(), tls_get() + + You can use this pointer to directly manipulate your thread data. + + \param index The \a index that you retrieved with tls_allocate(). + \return The pointer to where your thread's data is, or \c NULL if the index + is invalid. + \sa tls_allocate() + \sa tls_set() + \sa tls_get() */ + /*! - \fn void tls_set(int32 index, void *value) - \brief Set the data of this thread at the provided \a index. - - It is up to you to make sure the \a index is valid. Any invalid indeces can - lead to unpredicable results. - - \param index The \a index that you retrieved with tls_allocate(). - \param value The data that should be associated with the index for this - thread. - \see tls_allocate(), tls_get() + \fn void tls_set(int32 index, void *value) + \brief Set the data of this thread at the provided \a index. + + It is up to you to make sure the \a index is valid. Any invalid indices can + lead to unpredictable results. + + \param index The \a index that you retrieved with tls_allocate(). + \param value The data that should be associated with the index for this + thread. + + \sa tls_allocate() + \sa tls_get() */ diff --git a/docs/user/support/Unarchiver.dox b/docs/user/support/Unarchiver.dox index 74d0fb2f65c..983d2dc02c2 100644 --- a/docs/user/support/Unarchiver.dox +++ b/docs/user/support/Unarchiver.dox @@ -1,22 +1,31 @@ /* - * 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, yourpalal2@gmail.com * * 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 libroot + \brief Contains BUnarchiver class used to simplify the unarchiving of + complicated BArchivable hierarchies. +*/ + + /*! \class BUnarchiver \ingroup support \ingroup libbe \brief A class that simplifies the unarchiving of complicated BArchivable - hierarchies. + hierarchies. The BUnarchiver class is a small class used to recover BArchivable objects that have been archived with the BArchiver class. It also provides ownership @@ -71,6 +80,8 @@ instantiated. \param token the object \a token + + \returns A status code. */ @@ -82,6 +93,8 @@ \param name The archive \a name. \param index The archive \a index. + + \returns A status code. */ @@ -90,7 +103,9 @@ \brief Checks whether the object represented by \c token has been instantiated in this session. - \param token The object \a token + \param token The object \a token. + + \returns \c true if instantiated, \c false otherwise */ @@ -101,7 +116,9 @@ \param name The archive \a name. \param index The arcive \a token. - */ + + \returns \c true if instantiated, \c false otherwise. +*/ /*! @@ -123,6 +140,7 @@ retrieved object. \param object Return parameter for the retrieved object of type T. + \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. */ @@ -141,6 +159,7 @@ BArchiver::GetTokenForArchivable() during archival. \param object The return parameter for the retrieved object of type T. + \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. */ @@ -170,6 +189,7 @@ retrieved object. \param object Return parameter for the retrieved object of type T. + \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. */ @@ -189,6 +209,7 @@ like #BMessage::FindData(). \param object Return parameter for the retrieved object of type T. + \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. */ @@ -210,6 +231,7 @@ retrieved object. \param object Return parameter for the retrieved object of type T. + \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. */ @@ -230,6 +252,7 @@ adding this object. \param object Return parameter for the retrieved \a object of type T. + \returns A status code. \retval B_OK The \a object retrieved was of type T. \retval B_BAD_TYPE The \a object retrieved was not of type T. */ @@ -282,21 +305,22 @@ Here is an example of how you might use this method. Note that you must still call PrepareArchive(archive) either way. - \code +\code MyArchivableClas::MyArchivableClass(BMessage* archive) - : - BArchivable(BUnarchiver::PrepareArchive(archive)) + : + BArchivable(BUnarchiver::PrepareArchive(archive)) { - BUnarchiver unarchiver(archive); + BUnarchiver unarchiver(archive); - if (BUnarchiver::IsArchiveManaged(archive)) { - // ... calls to FindObject() or GetObject() here ... - } else { - // ... calls to BMessage::FindMessage() here ... - } + if (BUnarchiver::IsArchiveManaged(archive)) { + // ... calls to FindObject() or GetObject() here ... + } else { + // ... calls to BMessage::FindMessage() here ... + } } - \endcode +\endcode + \returns Whether \a archive was managed by a BArchiver object. \retval true if \a archive was managed by a BArchiver object. \retval false otherwise. */ @@ -314,14 +338,14 @@ MyArchivableClas::MyArchivableClass(BMessage* archive) archive constructor of your parent class. Notice the use of this method in the example provided below. - \code +\code MyArchivableClas::MyArchivableClas(BMessage* archive) - : - BArchivable(BUnarchiver::PrepareArchive(archive)) + : + BArchivable(BUnarchiver::PrepareArchive(archive)) { - // ... + // ... } - \endcode +\endcode \param archive The archive you wish to have prepared. @@ -364,6 +388,7 @@ MyArchivableClas::MyArchivableClas(BMessage* archive) \param from The #BMessage to instantiate from. \param object Return parameter for the retrieved object of type T. + \returns A status code. \retval B_OK The object retrieved was of type T. \retval B_BAD_TYPE The object retrieved was not of type T. */ diff --git a/docs/user/support/parsedate.dox b/docs/user/support/parsedate.dox index a78b2309087..5ec8a538ffa 100644 --- a/docs/user/support/parsedate.dox +++ b/docs/user/support/parsedate.dox @@ -1,188 +1,199 @@ /* - * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Copyright 2007 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * - * Documentation by: - * Axel Dörfler + * Authors: + * Axel Dörfler + * * Corresponds to: - * /trunk/headers/os/support/parsedate.h rev 19972 + * headers/os/support/parsedate.h rev 19972 */ + /*! - \file parsedate.h - \ingroup support - \ingroup libroot - \brief Date parsing functions - - This is a set a functions for parsing date strings in various formats. - It's mostly tailored for parsing user given data, although originally, - it was developed to parse the date strings found in usenet messages. - - The given date will be parsed relative to the specified time, and using - a predefined set of time/date formats. - - \par Valid Input Strings - - The internal formats allow parsedate() to understand a wide range of - input strings. The format list is ought to be compiled from the Date: - line of 80.000 usenet messages. - - But since this function is also used in end-user applications like the - Tracker's find panel, it's helpful to know what this function accepts - and what not. - - Here are some examples of input strings that parsedate() will be able - to convert along with some notes: - - "last friday", "this wednesday", "next July" - "last", "next", and "this" refer to the week or year (depending - on the context). So "last friday" means last week's friday. - "This wednesday" is referring to this week's wednesday, no matter - if it has already passed or not. - "Next July" refers to next year's July. All of these dates are - parsed relative to the specified time (usually "now"), and will - be set to the first moment of that time span: "next monday" is - monday, 0:00:00, midnight. - - "now" just returns the time all calculations are relative to. - - "next 5 minutes", "5 minutes", "+5 mins" all mean the same thing, - that is, current time plus exactly 5 minutes. - - "5 weeks" means in 5 weeks from now on. - - "8/5/2003", "5.8.2003", "2003-08-05" are all referring to August - 5th, 2003, again at 0:00 midnight. - - "Thursday 3:00" means this week's thursday, at 3 o'clock. - - \anchor parsedateFormats - \par Format Specifier - - While the get_dateformats() function allow you to retrieve the built-in - formats, you can also define your own and use set_dateformats() to let - parsedate() use them in all subsequent calls. - - The following is a list valid format specifiers and their meanings. - - - \b a/A weekday (Sunday, Monday, ...) - - \b d day of month (1-31) - - \b b/B month name (January, February, ...) - - \b month (1-12) - - \b y/Y year - - \b H/I hours (1-24) - - \b M minutes (0-60) - - \b S seconds (0-60) - - \b p meridian (am/pm) - - \b z/Z time zone (i.e. GMT) - - \b T time unit, like "last friday", "next 5 minutes", "-15 hours", etc. - - \b - dash or slash - - Any of ",.:" is allowed and will be expected in the input string as is. - You can enclose a \b single field with "[]" to mark it as being optional. - A blank stands for white space. No other character is allowed. - An invalid format string won't do any harm, but of course, no input string - will ever match that format. - - For example, "H:M [p]" will match against "21:33", "4:12 am", but not - "30:30 pm" (hours out of range), "15:16 GMT" (this time zone is certainly - not a valid meridian specifier), or "4:66" (minutes out of range). - - \par Note: - At the time of this writing, the parsedate() functions are not localized and - will only recognize English time specifications following the examples above. + \file parsedate.h + \ingroup support + \ingroup libroot + \brief Date parsing functions + + This is a set a functions for parsing date strings in various formats. + It's mostly tailored for parsing user given data, although originally, + it was developed to parse the date strings found in usenet messages. + + The given date will be parsed relative to the specified time, and using + a predefined set of time/date formats. + + \par Valid Input Strings + + The internal formats allow parsedate() to understand a wide range of + input strings. The format list is ought to be compiled from the Date: + line of 80.000 usenet messages. + + But since this function is also used in end-user applications like the + Tracker's find panel, it's helpful to know what this function accepts + and what not. + + Here are some examples of input strings that parsedate() will be able + to convert along with some notes: + - "last friday", "this wednesday", "next July" + "last", "next", and "this" refer to the week or year (depending + on the context). So "last friday" means last week's friday. + "This wednesday" is referring to this week's wednesday, no matter + if it has already passed or not. + "Next July" refers to next year's July. All of these dates are + parsed relative to the specified time (usually "now"), and will + be set to the first moment of that time span: "next monday" is + monday, 0:00:00, midnight. + - "now" just returns the time all calculations are relative to. + - "next 5 minutes", "5 minutes", "+5 mins" all mean the same thing, + that is, current time plus exactly 5 minutes. + - "5 weeks" means in 5 weeks from now on. + - "8/5/2003", "5.8.2003", "2003-08-05" are all referring to August + 5th, 2003, again at 0:00 midnight. + - "Thursday 3:00" means this week's thursday, at 3 o'clock. + + \anchor parsedateFormats + \par Format Specifier + + While the get_dateformats() function allow you to retrieve the built-in + formats, you can also define your own and use set_dateformats() to let + parsedate() use them in all subsequent calls. + + The following is a list valid format specifiers and their meanings: + - \b a/A weekday (Sunday, Monday, ...) + - \b d day of month (1-31) + - \b b/B month name (January, February, ...) + - \b month (1-12) + - \b y/Y year + - \b H/I hours (1-24) + - \b M minutes (0-60) + - \b S seconds (0-60) + - \b p meridian (am/pm) + - \b z/Z time zone (i.e. GMT) + - \b T time unit, like "last friday", "next 5 minutes", "-15 hours", etc. + - \b - dash or slash + + Any of ",.:" is allowed and will be expected in the input string as is. + You can enclose a \b single field with "[]" to mark it as being optional. + A blank stands for white space. No other character is allowed. + An invalid format string won't do any harm, but of course, no input string + will ever match that format. + + For example, "H:M [p]" will match against "21:33", "4:12 am", but not + "30:30 pm" (hours out of range), "15:16 GMT" (this time zone is certainly + not a valid meridian specifier), or "4:66" (minutes out of range). + + \note At the time of this writing, the parsedate() functions are not + localized and will only recognize English time specifications + following the examples above. */ + /*! - \def PARSEDATE_RELATIVE_TIME - \brief relative time + \def PARSEDATE_RELATIVE_TIME + \brief relative time - The time value was computed relative to the specified time. + The time value was computed relative to the specified time. */ + /*! - \def PARSEDATE_DAY_RELATIVE_TIME - \brief day relative time + \def PARSEDATE_DAY_RELATIVE_TIME + \brief day relative time - The time value was computed relative to the specified time, and it would vary - with every day passed in the specified time. + The time value was computed relative to the specified time, and it would vary + with every day passed in the specified time. */ + /*! - \def PARSEDATE_MINUTE_RELATIVE_TIME - \brief minute relative time + \def PARSEDATE_MINUTE_RELATIVE_TIME + \brief minute relative time - The time value was computed relative to the specified time, and it would - vary with every minute passed in the specified time. + The time value was computed relative to the specified time, and it would + vary with every minute passed in the specified time. */ + /*! - \def PARSEDATE_INVALID_DATE - \brief invalid date string + \def PARSEDATE_INVALID_DATE + \brief invalid date string - This flag will be set if the specified date string could not be parsed - correctly. For example, this may happen if there are some unknown words in - that string. + This flag will be set if the specified date string could not be parsed + correctly. For example, this may happen if there are some unknown words in + that string. */ + /*! - \fn time_t parsedate(const char *dateString, time_t relativeTo) - \brief Parses \a dateString relative to \a relativeTo + \fn time_t parsedate(const char *dateString, time_t relativeTo) + \brief Parses \a dateString relative to \a relativeTo - Parses the given \a dateString relative to the time - specified by \a relativeTo using the internal formats - table. + Parses the given \a dateString relative to the time + specified by \a relativeTo using the internal formats + table. - \param dateString the date that should be parsed, i.e. "next thursday". - \param relativeTo all relative dates will be relative to this time, if -1 + \param dateString the date that should be parsed, i.e. "next thursday". + \param relativeTo all relative dates will be relative to this time, if -1 is passed, the current time will be used. - \return the parsed time value or -1 if the \a dateString + \return the parsed time value or -1 if the \a dateString could not be parsed. */ + /*! - \fn time_t parsedate_etc(const char *dateString, time_t relativeTo, int *_storedFlags) - \brief Parses dateString relative to relativeTo - - This does basically the same as parsedate(), but will set the following - flags in _storedFlags: - \htmlonly - - - - - - - - - - - -
ConstantMeaning
PARSEDATE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly -
PARSEDATE_DAY_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly -
PARSEDATE_MINUTE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly -
PARSEDATE_INVALID_DATE - \endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly - This flag will only be set if the function returns -1. -
- \endhtmlonly + \fn time_t parsedate_etc(const char *dateString, time_t relativeTo, + int *_storedFlags) + \brief Parses dateString relative to + relativeTo + + This does basically the same as parsedate(), but will set the following + flags in _storedFlags: + \htmlonly + + + + + + + + + + + +
ConstantMeaning
PARSEDATE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_RELATIVE_TIME \htmlonly +
PARSEDATE_DAY_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_DAY_RELATIVE_TIME \htmlonly +
PARSEDATE_MINUTE_RELATIVE_TIME\endhtmlonly \copydoc PARSEDATE_MINUTE_RELATIVE_TIME \htmlonly +
PARSEDATE_INVALID_DATE + \endhtmlonly \copydoc PARSEDATE_INVALID_DATE \htmlonly + This flag will only be set if the function returns -1. +
+ \endhtmlonly */ + /*! - \fn void set_dateformats(const char *formatTable[]) - \brief sets the internal format table for parsedate() + \fn void set_dateformats(const char *formatTable[]) + \brief sets the internal format table for parsedate() - This function let you set the format table which is used by parsedate(). - When formatTable is NULL, the standard built-in format table will be set again. - \param formatTable the NULL terminated formats list. This list must stay + This function let you set the format table which is used by parsedate(). + When formatTable is NULL, the standard built-in format table will be set again. + \param formatTable the NULL terminated formats list. This list must stay valid when using parsedate() - it is not copied, but directly used. - \see - \ref parsedateFormats Format! + + \see + \ref parsedateFormats Format! */ + /*! - \fn const char **get_dateformats(void) - \brief returns the internal format table currently used by parsedate() + \fn const char **get_dateformats(void) + \brief returns the internal format table currently used by parsedate() - Returns the internal format table currently used by parsedate() - this is - either a pointer to the built-in one, or one that you have previously - set using set_dateformats(). + Returns the internal format table currently used by parsedate() - this is + either a pointer to the built-in one, or one that you have previously + set using set_dateformats(). - \see - \ref set_dateformats() + \see + \ref set_dateformats() */ - diff --git a/docs/user/support/stopwatch.dox b/docs/user/support/stopwatch.dox index d7e9e1ee64c..2977cd52797 100644 --- a/docs/user/support/stopwatch.dox +++ b/docs/user/support/stopwatch.dox @@ -1,100 +1,114 @@ /* - * 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 + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * Corresponds to: - * /trunk/headers/os/support/StopWatch.h rev 19972 - * /trunk/src/kits/support/StopWatch.cpp rev 14204 + * headers/os/support/StopWatch.h rev 19972 + * src/kits/support/StopWatch.cpp rev 14204 */ - - /*! - \file StopWatch.h - \brief Provides the BStopWatch class. + + +/*! + \file StopWatch.h + \ingroup support + \ingroup libroot + \brief Provides the BStopWatch class. */ + /*! - \class BStopWatch - \ingroup support - \ingroup libbe - \brief A timer class. - - This class provides method to time events. The interface is designed to - behave like a physical stopwatch. It is especially useful for debugging - certain parts of your code, since it can behave like a 'cheap' profiler. + \class BStopWatch + \ingroup support + \ingroup libbe + \brief A timer class. + + This class provides method to time events. The interface is designed to + behave like a physical stopwatch. It is especially useful for debugging + certain parts of your code, since it can behave like a 'cheap' profiler. */ + /*! - \fn BStopWatch::BStopWatch(const char *name, bool silent) - \brief Construct a BStopWatch object and starts the timer. - - The constructor creates a clean BStopWatch object. This object - can be given a name. As soon as the object is created, the time - will start ticking away. This class is designed to be usuable as a primitive - profiling tool. - - If you are profiling your code with this class, pass true as the - silentparameter. Whenever the object is destroyed, information on - the elapsed time will be streamed to standard output. - - \param name The name you want to give this object. You may pass NULL. - \param silent Pass true if you want to use this object as a simple profiler. + \fn BStopWatch::BStopWatch(const char *name, bool silent) + \brief Construct a BStopWatch object and starts the timer. + + The constructor creates a clean BStopWatch object. This object + can be given a name. As soon as the object is created, the time + will start ticking away. This class is designed to be usuable as a primitive + profiling tool. + + If you are profiling your code with this class, pass true as the + \a silent parameter. Whenever the object is destroyed, information on + the elapsed time will be streamed to standard output. + + \param name The name you want to give this object. You may pass \c NULL. + \param silent Pass \c true if you want to use this object as a simple + profiler. */ + /*! - \fn BStopWatch::~BStopWatch() - \brief Destructor. - - Destroys the object. If the object was constructed with the parameter - silent set t to false, this destructor will print information on the elapsed - time to standard output. + \fn BStopWatch::~BStopWatch() + \brief Destructor. + + Destroys the object. If the object was constructed with the parameter + silent set t to false, this destructor will print information on the elapsed + time to standard output. */ + /*! - \fn void BStopWatch::Resume() - \brief Resume the timer when it is in a suspended state. - \see Suspend() + \fn void BStopWatch::Resume() + \brief Resume the timer when it is in a suspended state. + \see Suspend() */ + /*! - \fn void BStopWatch::Suspend() - \brief Suspend the timer. - \see Resume() + \fn void BStopWatch::Suspend() + \brief Suspend the timer. + \see Resume() */ + /*! - \fn bigtime_t BStopWatch::Lap() - \brief Start a new lap. - - This method sets a lap. With the current implementation you are unable to - actually retrieve the timings of the laps. This is only printed to the - standard output when the object is destroyed. Thus making this tool only - usuable for use when doing some profiling. - - \attention Please note that the current implementation is limited to 10 laps. - The value returned is the time that has passed since the timer was started - (and not the time that has passed since the last lap). Any lap call beyond - the 10th lap will overwrite the last value. Note that if the timer is - suspended, nothing happens and the method will return 0. + \fn bigtime_t BStopWatch::Lap() + \brief Start a new lap. + + This method sets a lap. With the current implementation you are unable to + actually retrieve the timings of the laps. This is only printed to the + standard output when the object is destroyed. Thus making this tool only + usuable for use when doing some profiling. + + \attention Please note that the current implementation is limited to 10 laps. + The value returned is the time that has passed since the timer was started + (and not the time that has passed since the last lap). Any lap call beyond + the 10th lap will overwrite the last value. Note that if the timer is + suspended, nothing happens and the method will return 0. */ + /*! - \fn bigtime_t BStopWatch::ElapsedTime() const - \brief Get the elapsed time the object has counted. - \return The elapsed time in microseconds. + \fn bigtime_t BStopWatch::ElapsedTime() const + \brief Get the elapsed time the object has counted. + \return The elapsed time in microseconds. */ + /*! - \fn void BStopWatch::Reset() - \brief Restart the timer. + \fn void BStopWatch::Reset() + \brief Restart the timer. - Resets the object: it clears the start time, it clears the stored laps and it - restarts the timer. + Resets the object: it clears the start time, it clears the stored laps and it + restarts the timer. */ + /*! - \fn const char *BStopWatch::Name() const - \brief Get the name. - \return the name given to the object at creation time. -*/ \ No newline at end of file + \fn const char *BStopWatch::Name() const + \brief Get the name. + \return the name given to the object at creation time. +*/ diff --git a/docs/user/support/support_intro.dox b/docs/user/support/support_intro.dox index 402033fab07..1004e1049d3 100644 --- a/docs/user/support/support_intro.dox +++ b/docs/user/support/support_intro.dox @@ -1,90 +1,91 @@ /* - * Copyright 2007-2010, Haiku, Inc. All Rights Reserved. + * Copyright 2007-2010 Haiku, Inc. All rights reserved. * Distributed under the terms of the MIT License. * - * Documentation by: - * Niels Sascha Reedijk - * Nicolas de Leon + * Authors: + * Nicolas de Leon, insdel@haqr.net + * Niels Sascha Reedijk, niels.reedijk@gmail.com */ + /*! - \page support_intro Introduction to the Support Kit + \page support_intro Introduction to the Support Kit + + The Support Kit provides a handy set of classes that you can use in your + applications. These classes provide: + - \b Thread \b Safety. Haiku can execute multiple threads of an application + in parallel, letting certain parts of an application continue when one part + is stalled, as well as letting an application process multiple pieces of + data at the same time on multicore or multiprocessor systems. However, + there are times when multiple threads desire to work on the same piece of + data at the same time, potentially causing a conflict where variables or + pointers are changed by one thread causing another to execute incorrectly. + To prevent this, Haiku implements a \"locking\" mechanism, allowing one + thread to \"lock out\" other threads from executing code that might modify + the same data. + - \b Archiving \b and \b IO. These classes allow a programmer to convert + objects into a form that can more easily be transferred to other + applications or stored to disk, as well as performing basic input and + output operations. + - \b Memory \b Allocation. This class allows a programmer to hand off some of + the duties of memory accounting and management. + - \b Common \b Datatypes. To avoid unnecessary duplication of code and to + make life easier for programmers, Haiku includes classes that handle + management of ordered lists and strings. - The Support Kit provides a handy set of classes that you can use in your - applications. These classes provide: - - - \b Thread \b Safety. Haiku can execute multiple threads of an application - in parallel, letting certain parts of an application continue when one part - is stalled, as well as letting an application process multiple pieces of - data at the same time on multicore or multiprocessor systems. However, - there are times when multiple threads desire to work on the same piece of - data at the same time, potentially causing a conflict where variables or - pointers are changed by one thread causing another to execute incorrectly. - To prevent this, Haiku implements a \"locking\" mechanism, allowing one - thread to \"lock out\" other threads from executing code that might modify - the same data. - - \b Archiving \b and \b IO. These classes allow a programmer to convert - objects into a form that can more easily be transferred to other - applications or stored to disk, as well as performing basic input and - output operations. - - \b Memory \b Allocation. This class allows a programmer to hand off some of - the duties of memory accounting and management. - - \b Common \b Datatypes. To avoid unnecessary duplication of code and to - make life easier for programmers, Haiku includes classes that handle - management of ordered lists and strings. - - There are also a number of utility functions to time actions, play system - alert sounds, compare strings, and atomically manipulate integers. Have a - look at the overview, or go straight to the complete - \link support list of components \endlink of this kit. + There are also a number of utility functions to time actions, play system + alert sounds, compare strings, and atomically manipulate integers. Have a + look at the overview, or go straight to the complete + \link support list of components \endlink of this kit. - \section Overview - - Thread Safety: - - BLocker provides a semaphore-like locking mechanism allowing for - recursive locks. - - BAutolock provides a simple method of automatically removing a lock - when a function ends. - - \ref TLS.h "Thread Local Storage" allows a global variable\'s content to - be sensitive to thread context. - - Archiving and IO: - - BArchivable provides an interface for \"archiving\" objects so that they - may be sent to other applications where an identical copy will be - recreated. - - BArchiver simplifies archiving of BArchivable hierarchies. - - BUnarchiver simplifies unarchiving hierarchies that have been archived - using BArchiver. - - BFlattenable provides an interface for \"flattening\" objects so that - they may be easily stored to disk. - - BDataIO provides an interface for generalized read/write streams. - - BPositionIO extends BDataIO to allow seeking within the data. - - BBufferIO creates a buffer and attaches it to a BPositionIO stream, - allowing for reduced load on the underlying stream. - - BMemoryIO allows operation on an already-existing buffer. - - BMallocIO creates and allows operation on a buffer. - - Memory Allocation: - - BBlockCache allows an application to allocate a \"pool\" of memory blocks - that the application can fetch and dispose of as it pleases, letting the - application make only a few large memory allocations, instead of many - expensive small allocations. - - Common Datatypes: - - BList allows simple ordered lists and provides common access, - modification, and comparison functions. - - BString allows strings and provides common access, modification, and - comparison functions. - - BStopWatch allows an application to measure the time an action takes. - - \ref support_globals "Global functions" - - \ref TypeConstants.h "Common types and constants" - - Error codes for all kits + \section Overview + - Thread Safety: + - BLocker provides a semaphore-like locking mechanism allowing for + recursive locks. + - BAutolock provides a simple method of automatically removing a lock + when a function ends. + - \ref TLS.h "Thread Local Storage" allows a global variable\'s content to + be sensitive to thread context. + - Archiving and IO: + - BArchivable provides an interface for \"archiving\" objects so that they + may be sent to other applications where an identical copy will be + recreated. + - BArchiver simplifies archiving of BArchivable hierarchies. + - BUnarchiver simplifies unarchiving hierarchies that have been archived + using BArchiver. + - BFlattenable provides an interface for \"flattening\" objects so that + they may be easily stored to disk. + - BDataIO provides an interface for generalized read/write streams. + - BPositionIO extends BDataIO to allow seeking within the data. + - BBufferIO creates a buffer and attaches it to a BPositionIO stream, + allowing for reduced load on the underlying stream. + - BMemoryIO allows operation on an already-existing buffer. + - BMallocIO creates and allows operation on a buffer. + - Memory Allocation: + - BBlockCache allows an application to allocate a \"pool\" of memory blocks + that the application can fetch and dispose of as it pleases, letting the + application make only a few large memory allocations, instead of many + expensive small allocations. + - Common Datatypes: + - BList allows simple ordered lists and provides common access, + modification, and comparison functions. + - BString allows strings and provides common access, modification, and + comparison functions. + - BStopWatch allows an application to measure the time an action takes. + - \ref support_globals "Global functions" + - \ref TypeConstants.h "Common types and constants" + - Error codes for all kits */ + // Short listing of documents that belong to this module so that people can // find these from the module overview. // This should become standardized in Doxygen though. There is an item on // the todo list on this. + /*! - \addtogroup support + \addtogroup support - For a better overview, have a look at \ref support_intro . + For a better overview, have a look at \ref support_intro . */ - diff --git a/docs/user/support/syslog.dox b/docs/user/support/syslog.dox index 82cc2133e02..f76f9d08e85 100644 --- a/docs/user/support/syslog.dox +++ b/docs/user/support/syslog.dox @@ -1,293 +1,350 @@ /* - * 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: - * Axel Dörfler - * Niels Sascha Reedijk + * Authors: + * Axel Dörfler + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * Corresponds to: - * /trunk/headers/posix/syslog.h rev 6684 + * headers/posix/syslog.h rev 6684 */ + /*! - \file syslog.h - \ingroup support - \ingroup libroot - \brief System logging capabilities + \file syslog.h + \ingroup support + \ingroup libroot + \brief System logging capabilities - The functions described here are interacting with the syslog_daemon, a server - that provides the system logging capabilities. - The log can be found in /var/log/syslog. + The functions described here are interacting with the syslog_daemon, a server + that provides the system logging capabilities. + The log can be found in /var/log/syslog. */ -/*! - \fn void closelog(void) - \brief Closes the current log session + +/*! + \fn void closelog(void) + \brief Closes the current log session */ -/*! - \fn void openlog(const char *ident, int options, int facility) - \brief Starts a log session, and sets some output options - Like openlog_thread() this function defines the log session in thread context; the - global options set by openlog_team() are not affected by this function. +/*! + \fn void openlog(const char *ident, int options, int facility) + \brief Starts a log session, and sets some output options + + Like openlog_thread() this function defines the log session in thread context; the + global options set by openlog_team() are not affected by this function. */ -/*! - \fn int setlogmask(int priorityMask) - \brief sets the logging priority mask + +/*! + \fn int setlogmask(int priorityMask) + \brief sets the logging priority mask */ -/*! - \fn void syslog(int priority, const char *message, ...) - \brief sends a message to the system log + +/*! + \fn void syslog(int priority, const char *message, ...) + \brief sends a message to the system log */ -/*! - \fn void closelog_team(void) - \brief Closes the log + +/*! + \fn void closelog_team(void) + \brief Closes the log */ -/*! - \fn void openlog_team(const char *ident, int logopt, int facility) - \brief Starts a log session, and sets some output options - This function defines the team-wide logging options. Thread local sessions - started with openlog() or openlog_thread() will inherit the options of the - global session. +/*! + \fn void openlog_team(const char *ident, int logopt, int facility) + \brief Starts a log session, and sets some output options + + This function defines the team-wide logging options. Thread local sessions + started with openlog() or openlog_thread() will inherit the options of the + global session. */ -/*! - \fn void log_team(int priority, const char *message, ...) - \brief sends a message to the system log + +/*! + \fn void log_team(int priority, const char *message, ...) + \brief sends a message to the system log */ -/*! - \fn int setlogmask_team(int priorityMask) - \brief sets the logging priority mask + +/*! + \fn int setlogmask_team(int priorityMask) + \brief sets the logging priority mask */ -/*! - \fn void closelog_thread(void) - \brief Closes the log + +/*! + \fn void closelog_thread(void) + \brief Closes the log */ -/*! - \fn void openlog_thread(const char *ident, int logopt, int facility) - \brief Starts a log session, and sets some output options + +/*! + \fn void openlog_thread(const char *ident, int logopt, int facility) + \brief Starts a log session, and sets some output options */ -/*! - \fn void log_thread(int priority, const char *message, ...) - \brief sends a message to the system log + +/*! + \fn void log_thread(int priority, const char *message, ...) + \brief sends a message to the system log */ -/*! - \fn int setlogmask_thread(int priorityMask) - \brief sets the logging priority mask + +/*! + \fn int setlogmask_thread(int priorityMask) + \brief sets the logging priority mask */ + /*! - \name Options for openlog() + \name Options for openlog() */ + //! @{ -/*! - \def LOG_PID - \brief Log the process (thread/team) ID with each message + +/*! + \def LOG_PID + \brief Log the process (thread/team) ID with each message */ -/*! - \def LOG_CONS - \brief Log to the system console on error + +/*! + \def LOG_CONS + \brief Log to the system console on error */ -/*! - \def LOG_ODELAY - \brief Delay open until syslog() is called + +/*! + \def LOG_ODELAY + \brief Delay open until syslog() is called */ -/*! - \def LOG_NDELAY - \brief Connect to the syslog daemon immediately + +/*! + \def LOG_NDELAY + \brief Connect to the syslog daemon immediately */ -/*! - \def LOG_SERIAL - \brief Dump to serial output as well. - \attention This is not yet implemented + +/*! + \def LOG_SERIAL + \brief Dump to serial output as well. + \attention This is not yet implemented */ -/*! - \def LOG_PERROR - \brief Dump to stderr as well + +/*! + \def LOG_PERROR + \brief Dump to stderr as well */ -/*! - \def LOG_NOWAIT - \brief Do not wait for child processes + +/*! + \def LOG_NOWAIT + \brief Do not wait for child processes */ + //! @} -/*! -\name Facilities for openlog() + +/*! \name Facilities for openlog() */ + //! @{ -/*! - \def LOG_KERN - \brief Reserved for messages generated by the kernel. + +/*! + \def LOG_KERN + \brief Reserved for messages generated by the kernel. */ -/*! - \def LOG_USER - \brief Reserved for messages generated by user processes. + +/*! + \def LOG_USER + \brief Reserved for messages generated by user processes. */ + /*! - \def LOG_MAIL - \brief Standard (?) POSIX facility for messages by the mailing daemon. + \def LOG_MAIL + \brief Standard (?) POSIX facility for messages by the mailing daemon. */ -/*! - \def LOG_DAEMON - \brief Standard POSIX (?) facility for messages by daemons (and Haiku servers). + +/*! + \def LOG_DAEMON + \brief Standard POSIX (?) facility for messages by daemons (and Haiku servers). */ -/*! - \def LOG_AUTH - \brief Standard POSIX facility(?) for messages by the authentication services. + +/*! + \def LOG_AUTH + \brief Standard POSIX facility(?) for messages by the authentication services. */ -/*! - \def LOG_SYSLOG - \brief Reserved for messages generated by the syslog daemon. + +/*! + \def LOG_SYSLOG + \brief Reserved for messages generated by the syslog daemon. */ + /*! - \def LOG_LPR - \brief Reserved for messages generated by the UNIX lpr printing tool. + \def LOG_LPR + \brief Reserved for messages generated by the UNIX lpr printing tool. */ -/*! - \def LOG_NEWS - \brief Reserved for messages generated by something UNIXy that does something with NEWS. + +/*! + \def LOG_NEWS + \brief Reserved for messages generated by something UNIXy that does something with NEWS. */ + /*! - \def LOG_UUCP - \brief Reserved for messages generated by UUCP + \def LOG_UUCP + \brief Reserved for messages generated by UUCP */ + /*! - \def LOG_CRON - \brief Reserved for messages generated by the CRON daemon. + \def LOG_CRON + \brief Reserved for messages generated by the CRON daemon. */ -/*! - \def LOG_AUTHPRIV - \brief Reserved for private (?) messages that relate to authentication. + +/*! + \def LOG_AUTHPRIV + \brief Reserved for private (?) messages that relate to authentication. */ + /*! - \def LOG_LOCAL0 - \brief Use this for local use. + \def LOG_LOCAL0 + \brief For local use. */ + /*! - \def LOG_LOCAL1 - \brief Use this for local use. + \def LOG_LOCAL1 + \brief For local use. */ -/*! - \def LOG_LOCAL2 - \brief Use this for local use. + +/*! + \def LOG_LOCAL2 + \brief For local use. */ -/*! - \def LOG_LOCAL3 - \brief Use this for local use. + +/*! + \def LOG_LOCAL3 + \brief For local use. */ -/*! - \def LOG_LOCAL4 - \brief Use this for local use. + +/*! + \def LOG_LOCAL4 + \brief For local use. */ -/*! - \def LOG_LOCAL5 - \brief Use this for local use. + +/*! + \def LOG_LOCAL5 + \brief For local use. */ + /*! - \def LOG_LOCAL6 - \brief Use this for local use. + \def LOG_LOCAL6 + \brief For local use. */ + /*! - \def LOG_LOCAL7 - \brief Use this for local use. + \def LOG_LOCAL7 + \brief For local use. */ + //! @} -/*! -\name Priorities for syslog(), log_team() and log_thread() + +/*! \name Priorities for syslog(), log_team() and log_thread() */ + //! @{ -/*! - \def LOG_EMERG - \brief A panic condition + +/*! + \def LOG_EMERG + \brief A panic condition */ -/*! - \def LOG_PANIC - \brief An alias for LOG_EMERG + +/*! + \def LOG_PANIC + \brief An alias for LOG_EMERG */ -/*! - \def LOG_ALERT - \brief A condition to that should be corrected immediately + +/*! + \def LOG_ALERT + \brief A condition to that should be corrected immediately */ -/*! - \def LOG_CRIT - \brief Critical conditions like hard drive errors + +/*! + \def LOG_CRIT + \brief Critical conditions like hard drive errors */ + /*! - \def LOG_ERR - \brief Errors + \def LOG_ERR + \brief Errors */ -/*! - \def LOG_WARNING - \brief Warnings + +/*! + \def LOG_WARNING + \brief Warnings */ -/*! - \def LOG_NOTICE - \brief Notices, instructions on how to use certain configuration options. + +/*! + \def LOG_NOTICE + \brief Notices, instructions on how to use certain configuration options. */ -/*! - \def LOG_INFO - \brief Information, like versions and so. + +/*! + \def LOG_INFO + \brief Information, like versions and so. +*/ + + +/*! + \def LOG_DEBUG + \brief Debug information. */ -/*! - \def LOG_DEBUG - \brief Debug information. -*/\ //! @} -/*! - \def LOG_MASK - \brief Converts a priority definition for use in setlogmask() -*/ \ No newline at end of file + +/*! + \def LOG_MASK + \brief Converts a priority definition for use in setlogmask() +*/ diff --git a/docs/user/support/typeconstants.dox b/docs/user/support/typeconstants.dox index bf859662088..f007b23c08c 100644 --- a/docs/user/support/typeconstants.dox +++ b/docs/user/support/typeconstants.dox @@ -1,185 +1,227 @@ /* - * 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 + * Authors: + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * * Corresponds to: - * /trunk/headers/os/support/TypeConstants.h rev 20212 + * headers/os/support/TypeConstants.h rev 20212 */ + /*! - \file TypeConstants.h - \ingroup support - \brief Represents typecodes that are used in various part of the Haiku API. + \file TypeConstants.h + \ingroup support + \ingroup libroot + \brief Represents typecodes that are used in various part of the Haiku API. - The type codes all refer to a specified type, except one. B_ANY_TYPE can - refer to literaly any type. This type could be used in case you send or receive - data of which you don't know the type, but you want to send or receive it - anyway. + The type codes all refer to a specified type, except one. B_ANY_TYPE can + refer to literaly any type. This type could be used in case you send or receive + data of which you don't know the type, but you want to send or receive it + anyway. */ + /*! - \var B_ANY_TYPE - \brief General type when the exact contents is not yet known. + \var B_ANY_TYPE + \brief General type when the exact contents is not yet known. */ + /*! - \var B_ATOM_TYPE - \brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. + \var B_ATOM_TYPE + \brief Reference to a BAtomic class that was going to be in BeOS R6. + + Unused in Haiku. */ + /*! - \var B_ATOMREF_TYPE - \brief Reference to a BAtomic class that was going to be in BeOS R6. Unused in Haiku. + \var B_ATOMREF_TYPE + \brief Reference to a BAtomic class that was going to be in BeOS R6. + + Unused in Haiku. */ + /*! - \var B_BOOL_TYPE - \brief Boolean value. + \var B_BOOL_TYPE + \brief Boolean value. */ + /*! - \var B_CHAR_TYPE - \brief Represents the \c char type. + \var B_CHAR_TYPE + \brief Represents the \c char type. */ + /*! - \var B_COLOR_8_BIT_TYPE - \brief Represents a one-byte colour. + \var B_COLOR_8_BIT_TYPE + \brief Represents a one-byte color. */ + /*! - \var B_DOUBLE_TYPE - \brief Represents the \c double type. + \var B_DOUBLE_TYPE + \brief Represents the \c double type. */ + /*! - \var B_FLOAT_TYPE - \brief Represents the \c float type. + \var B_FLOAT_TYPE + \brief Represents the \c float type. */ + /*! - \var B_GRAYSCALE_8_BIT_TYPE - \brief Represents a byte-long grayscale value. + \var B_GRAYSCALE_8_BIT_TYPE + \brief Represents a byte-long grayscale value. */ + /*! - \var B_INT16_TYPE - \brief Represents a \c short type. + \var B_INT16_TYPE + \brief Represents a \c short type. */ + /*! - \var B_INT32_TYPE - \brief Represents a \c long type. + \var B_INT32_TYPE + \brief Represents a \c long type. */ + /*! - \var B_INT64_TYPE - \brief Represents a \c long \c long type. + \var B_INT64_TYPE + \brief Represents a \c long \c long type. */ + /*! - \var B_INT8_TYPE - \brief Represents a \c char type used for integer storage. + \var B_INT8_TYPE + \brief Represents a \c char type used for integer storage. */ + /*! - \var B_LARGE_ICON_TYPE - \brief Represents a large icon. + \var B_LARGE_ICON_TYPE + \brief Represents a large icon. */ + /*! - \var B_MEDIA_PARAMETER_GROUP_TYPE - \brief Represents the BParameterGroup type from the media kit. + \var B_MEDIA_PARAMETER_GROUP_TYPE + \brief Represents the BParameterGroup type from the media kit. */ + /*! - \var B_MEDIA_PARAMETER_TYPE - \brief Represents the BParameter type from the media kit. + \var B_MEDIA_PARAMETER_TYPE + \brief Represents the BParameter type from the media kit. */ + /*! - \var B_MEDIA_PARAMETER_WEB_TYPE - \brief Represents the BParameterWeb type from the media kit. + \var B_MEDIA_PARAMETER_WEB_TYPE + \brief Represents the BParameterWeb type from the media kit. */ + /*! - \var B_MESSAGE_TYPE - \brief Represents a BMessage type. + \var B_MESSAGE_TYPE + \brief Represents a BMessage type. */ + /*! - \var B_MESSENGER_TYPE - \brief Represents a BMessenger type. + \var B_MESSENGER_TYPE + \brief Represents a BMessenger type. */ + // Todo: the rest of the types -/*! -\name System-wide MIME types for handling URLs + +/*! + \name System-wide MIME types for handling URLs */ + //! @{ + /*! - \var B_URL_HTTP - \brief application/x-vnd.Be.URL.http + \var B_URL_HTTP + \brief application/x-vnd.Be.URL.http */ + /*! - \var B_URL_HTTPS - \brief application/x-vnd.Be.URL.https + \var B_URL_HTTPS + \brief application/x-vnd.Be.URL.https */ + /*! - \var B_URL_FTP - \brief application/x-vnd.Be.URL.ftp + \var B_URL_FTP + \brief application/x-vnd.Be.URL.ftp */ + /*! - \var B_URL_GOPHER - \brief application/x-vnd.Be.URL.gopher + \var B_URL_GOPHER + \brief application/x-vnd.Be.URL.gopher */ + /*! - \var B_URL_MAILTO - \brief application/x-vnd.Be.URL.mailto + \var B_URL_MAILTO + \brief application/x-vnd.Be.URL.mailto */ + /*! - \var B_URL_NEWS - \brief application/x-vnd.Be.URL.news + \var B_URL_NEWS + \brief application/x-vnd.Be.URL.news */ + /*! - \var B_URL_NNTP - \brief application/x-vnd.Be.URL.nntp + \var B_URL_NNTP + \brief application/x-vnd.Be.URL.nntp */ + /*! - \var B_URL_TELNET - \brief application/x-vnd.Be.URL.telnet + \var B_URL_TELNET + \brief application/x-vnd.Be.URL.telnet */ + /*! - \var B_URL_RLOGIN - \brief application/x-vnd.Be.URL.rlogin + \var B_URL_RLOGIN + \brief application/x-vnd.Be.URL.rlogin */ + /*! - \var B_URL_TN3270 - \brief application/x-vnd.Be.URL.tn3270 + \var B_URL_TN3270 + \brief application/x-vnd.Be.URL.tn3270 */ + /*! - \var B_URL_WAIS - \brief application/x-vnd.Be.URL.wais + \var B_URL_WAIS + \brief application/x-vnd.Be.URL.wais */ + /*! - \var B_URL_FILE - \brief application/x-vnd.Be.URL.file + \var B_URL_FILE + \brief application/x-vnd.Be.URL.file */ + //! @} diff --git a/docs/user/translation/BitmapStream.dox b/docs/user/translation/BitmapStream.dox index 26eaa93414c..80fb8b868b1 100644 --- a/docs/user/translation/BitmapStream.dox +++ b/docs/user/translation/BitmapStream.dox @@ -1,19 +1,22 @@ /* - * Copyright 2002-2013 Haiku Inc. + * Copyright 2002-2013 Haiku Inc. All rights reserved. * Distributed under the terms of the MIT License. * - * Documentation by: - * John Scipione + * Authors: + * John Scipione, jscipione@gmail.com * Travis Smith * Michael Wilber + * * Corresponds to: - * /trunk/headers/os/translation/BitmapStream.h hrev45181 - * /trunk/src/kits/translation/BitmapStream.cpp hrev45181 + * headers/os/translation/BitmapStream.h hrev45181 + * src/kits/translation/BitmapStream.cpp hrev45181 */ /*! \file BitmapStream.h + \ingroup translation + \ingroup libbe \brief BBitmapStream class definition. */ diff --git a/src/kits/support/String.cpp b/src/kits/support/String.cpp index d5b2c038382..78f49a812b7 100644 --- a/src/kits/support/String.cpp +++ b/src/kits/support/String.cpp @@ -398,6 +398,7 @@ BString::SetTo(char c, int32 count) if (_MakeWritable(count, false) == B_OK) memset(fPrivateData, c, count); + return *this; }