root/haiku/trunk/docs/user/app/Message.dox

/*
 * 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
 */


/*!
        \file Message.h
        \brief Provides the BMessage class.
*/

///// Name lengths and Scripting specifiers /////

/*!
        \def B_FIELD_NAME_LENGTH
        \brief Undocumented...
*/


/*!
        \def B_PROPERTY_NAME_LENGTH
        \brief Undocumented...
*/


/*!
        \var B_NO_SPECIFIER
        \brief Undocumented...
*/


/*!
        \var B_DIRECT_SPECIFIER
        \brief Undocumented...
*/


/*!
        \var B_INDEX_SPECIFIER
        \brief Undocumented...
*/


/*!
        \var B_REVERSE_INDEX_SPECIFIER,
        \brief Undocumented...
*/


/*!
        \var B_RANGE_SPECIFIER
        \brief Undocumented...
*/


/*!
        \var B_REVERSE_RANGE_SPECIFIER
        \brief Undocumented...
*/


/*!
        \var B_NAME_SPECIFIER
        \brief Undocumented...
*/


/*!     
        \var B_ID_SPECIFIER
        \brief Undocumented...
*/


/*!
        \var B_SPECIFIERS_END
        \brief Undocumented...
*/


///// Class BMessage /////


/*!
        \class BMessage
        \ingroup app
        \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
        <b>important elements</b>: the #what identifer, and the data members. The
        first can be directly manipulated, the latter can be manipulated through
        AddData(), FindData() and ReplaceData() and their deratives. Neither of
        these elements are mandatory.
        
        The second important role of BMessage is that it stores <b>meta data</b>:
        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 <b>data storage purposes</b>. 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 Miscelanous 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".
*/


/*!
        \var BMessage::what
        \brief A 4-byte constant that determines the type of message.
        
        You can directly manipulate this data member.
*/


/*!
        \fn BMessage::BMessage()
        \brief Construct an empty message, without any data members and with a 
                \c what constant set to zero (0).
        
        \see BMessage(uint32 what)
        \see BMessage(const BMessage &other)
*/


/*!
        \fn BMessage::BMessage(uint32 what)
        \brief Construct an empty message with the \c what member set tot the
                specified value.
        
        \see BMessage::BMessage()
        \see BMessage::BMessage(const BMessage &other)
*/


/*!
        \fn BMessage::BMessage(const BMessage &other)
        \brief Construct a new message that is a copy of another message.
        
        The \c 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 behaviour. Please use the Haiku implementation of message copying as
        the default behavior. This will keep your applications backwards
        compatible.

        \see BMessage::BMessage()
        \see BMessage(uint32 what)
*/ 


/*!
        \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.
*/


/*!
        \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.
*/


/*!
        \name Statistics and Miscelanous Information
*/


//! @{
 

/*!
        \fn status_t BMessage::GetInfo(type_code typeRequested, int32 index,
                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.
        \param[in] index The index of the data you want to investigate.
        \param[out] nameFound The name of the item if it is found. Haiku will fill
                in a pointer to the internal name buffer in the message. This means
                that you should not manipulate this name. If you are not interested in
                the name, you can safely pass \c NULL.
        \param[out] typeFound The type of the item at \a index. If you are not
                interested in the type (because you specifically asked for a type), you
                can safely pass NULL.
        \param[out] countFound The number of items at \a index. If data items have
                the same name, they will be placed under the same index.
                
        \return If the \a index is found, and matches the requested type, 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.
        \retval B_BAD_TYPE The data field at \a index does not have the requested
                type.
*/


/*!
        \fn status_t BMessage::GetInfo(const char *name, type_code *typeFound,
                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
                \c NULL.
        \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.
*/


/*!
        \fn status_t BMessage::GetInfo(const char *name, type_code *typeFound,
                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 in the variable you passed as \a fixedSize parameter.
*/


/*!
        \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 zero in case no items match the type.
*/


/*!
        \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()
*/


/*!
        \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.
*/


/*!
        \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.
*/


/*!
        \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,
        especially the handling of those that are sent by external applications, to
        see if you understand the semantics correctly.
*/


/*!
        \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.
        \retval B_NAME_NOT_FOUND There is no data associated with the label
                \a oldEntry.
*/


//! @}

/*!
        \name Delivery Info
*/

//! @{


/*!
        \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.
*/


/*!
        \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.
*/


/*!
        \fn bool BMessage::IsSourceRemote() const
        \brief Check if the message is sent by another application.
*/


/*!
        \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.
*/


/*!
        \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
                another message, this method will return \c NULL.
*/


/*!
        \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
                been delivered at all.
        \see DropPoint()
*/


/*!
        \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()
*/


//! @}


/*!
        \name Replying
*/


//! @{


/*!
        \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.
*/


/*!
        \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).
*/      


/*!
        \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.
        \param timeout The maximum time in microseconds this delivery may take. The
                \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).
        \retval B_WOULD_BLOCK The delivery \a timeout was \c B_INFINITE_TIMEOUT
                (zero) and the target port was full when trying to deliver the message.
        \retval B_TIMED_OUT The timeout expired while trying to deliver the
          message.
        \see SendReply(uint32 command, BHandler *replyTo)
*/


/*!
        \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.
*/


/*!
        \fn status_t BMessage::SendReply(BMessage *reply, BMessage *replyToReply,
                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 \a replyToReply argument.
        If the message was delivered properly, but the receiver did not reply
        within the specified \a replyTimeout, the \c 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.
                The \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.
        \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 \c NULL.
        \retval B_BAD_PORT_ID The reply address is not valid (anymore).
        \retval B_WOULD_BLOCK The delivery \a timeout was \c B_INFINITE_TIMEOUT
                (zero) and the target port was full when trying to deliver the message.
        \retval B_TIMED_OUT The timeout expired while trying to deliver the
          message.
        \retval B_NO_MORE_PORTS All reply ports are in use.
        \see SendReply(uint32 command, BMessage *replyToReply)
*/


//! @}


/*!
        \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
        use messages in methods that handle BFlattenable objects.
*/


//! @{
        

/*!
        \fn ssize_t BMessage::FlattenedSize() const
        \brief Return the size in bytes required when you want to flatten this
                message to a stream of bytes.
*/


/*!
        \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()
        \see Flatten(BDataIO *stream, ssize_t *size) const
*/


/*!
        \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.
        \see FlattenedSize()
        \see Flatten(char *buffer, ssize_t size) const
*/


/*!
        \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
                members.
        \see Flatten(char *buffer, ssize_t size) const
        \see Unflatten(BDataIO *stream)
*/


/*!
        \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
                members.
        \see Flatten(BDataIO *stream, ssize_t *size) const
        \see Unflatten(const char *flatBuffer)
*/


//! @}

/*!
        \name Specifiers (Scripting)
*/
        
//! @{
        

/*!
        \fn status_t BMessage::AddSpecifier(const char *property)
        \brief Undocumented.
*/


/*!
        \fn status_t BMessage::AddSpecifier(const char *property, int32 index)
        \brief Undocumented.
*/


/*!
        \fn status_t BMessage::AddSpecifier(const char *property, int32 index,
                int32 range)
        \brief Undocumented.
*/


/*!
        \fn status_t BMessage::AddSpecifier(const char *property, const char *name)
        \brief Undocumented.
*/


/*!
        \fn status_t BMessage::AddSpecifier(const BMessage *specifier)
        \brief Undocumented.
*/


/*!
        \fn status_t BMessage::SetCurrentSpecifier(int32 index)
        \brief Undocumented.
*/


/*!
        \fn status_t BMessage::GetCurrentSpecifier(int32 *index,
                BMessage *specifier, int32 *what, const char **property) const
        \brief Undocumented.
*/


/*!
        \fn bool BMessage::HasSpecifiers() const
        \brief Undocumented.
*/


/*!
        \fn status_t BMessage::PopSpecifier()
        \brief Undocumented.
*/


//! @}


/*!
        \name Adding Data
*/


//! @{
        

/*!
        \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
        B_FLOAT_TYPE or 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 fix the size
        of each data entry, and you can also instruct BMessage to allocate a
        \a count of items. The latter does not mean that the number of items is
        fixed; the array will grow nonetheless. Also, note that every \a name can
        only be associated with one \a type of data. 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.
        \param type The type of data. If you are adding data to the same \a name,
                make sure it is the same type.
        \param data The data buffer to copy the bytes from.
        \param numBytes The number of bytes to be copied. If this is the first call
                to this method for this type of data, and you set \a isFixedSize to
                \c true, this will specify the size of all consecutive calls to this
                method.
        \param isFixedSize If this is the first call to this method with this
                \a name, you can specify the whether or not all items in this array
                should have the same fixed size.
        \param count If this is the first call to this method with this
                \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 zero (0), or
                the size of this item is larger than the \a name allows, since it has
                been specified to have a fixed size.
        \retval B_ERROR There was an error whilst creating the label with your 
                \a name.
        \retval B_BAD_TYPE The \a type you specified is different than the one
                already associated with \a name.
*/


/*!
        \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.
        \see FindRect()
        \see ReplaceRect()
*/


/*!
        \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.
        \see FindPoint()
        \see ReplacePoint()
*/


/*!
        \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.
        \see FindString()
        \see ReplaceString()
*/


/*!
        \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.
        \see FindString()
        \see ReplaceString()
*/


/*!
        \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.
        \see FindInt16()
        \see ReplaceInt16()
*/


/*!     
        \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.
        \see FindInt32()
        \see ReplaceInt32()
*/


/*!
        \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.
        \see FindInt64()
        \see ReplaceInt64()
*/


/*!
        \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.
        \see FindBool()
        \see ReplaceBool()
*/

/*!
        \fn status_t BMessage::AddFloat(const char *name, float aFloat)
        \brief Convenience method to add a \c float to the label \a name.

        This method calls AddData() with the \c B_FLOAT_TYPE \a type.

        \param name The label to associate the data with.
        \param aFloat The value to store in the message.
        \see AddData() for a more detailed overview of the inner workings.
        \see FindFloat()
        \see ReplaceFloat()
*/


/*!
        \fn status_t BMessage::AddDouble(const char *name, double aDouble)
        \brief Convenience method to add a \c double to the label \a name.

        This method calls AddData() with the \c B_DOUBLE_TYPE \a type.

        \param name The label to associate the data with.
        \param aDouble The value to store in the message.
        \see AddData() for a more detailed overview of the inner workings.
        \see FindDouble()
        \see ReplaceDouble()
*/


/*!
        \fn status_t BMessage::AddPointer(const char *name, const void *aPointer)
        \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
                messages. You should think about copying the entire object in the
                message, or you should consider using shared memory.

        \param name The label to associate the data with.
        \param aPointer The value to store in the message.
        \see AddData() for a more detailed overview of the inner workings.
        \see FindPointer()
        \see ReplacePointer()
*/


/*!
        \fn status_t BMessage::AddMessenger(const char *name, BMessenger messenger)
        \brief Convenience method to add a messenger to the label \a name.

        This method calls AddData() with the \c B_MESSENGER_TYPE \a type.

        \param name The label to associate the data with.
        \param messenger The messenger to store in the message.
        \see AddData() for a more detailed overview of the inner workings.
        \see FindMessenger()
        \see ReplaceMessenger()
*/


/*!
        \fn status_t BMessage::AddRef(const char *name, const entry_ref *ref)
        \brief Convenience method to add an \c entry_ref to the label \a name.

        This method calls AddData() with the \c B_REF_TYPE \a type.

        \param name The label to associate the data with.
        \param ref The reference to store in the message.
        \see AddData() for a more detailed overview of the inner workings.
        \see FindRef()
        \see ReplaceRef()
*/


/*!
        \fn status_t BMessage::AddMessage(const char *name, const BMessage *message)
        \brief Convenience method to add a message to the label \a name.

        This method calls AddData() with the \c B_MESSAGE_TYPE \a type.

        \param name The label to associate the data with.
        \param message The message to store in this message.
        \see AddData() for a more detailed overview of the inner workings.
        \see FindMessage()
        \see ReplaceMessage()
*/


/*!
        \fn status_t BMessage::AddFlat(const char *name, BFlattenable *object,
                int32 count = 1)
        \brief Convenience method to add a flattenable to the label \a name.

        This method uses BFlattenable::TypeCode() to determine the type. It also
        uses BFlattenable::IsFixedSize() to determine whether or not the size of
        the object is supposedly always the same. You can specify a \a count, to
        pre-allocate more entries if you are going to add more than one of this
        type.

        \param name The label to associate the data with.
        \param object The object to flatten into the message.
        \param count The number of items to pre-allocate associated with this
                \a name.
        \see AddData() for a more detailed overview of the inner workings.
        \see FindFlat()
        \see ReplaceFlat()
*/


//! @}


/*!
        \name Removing Data
*/


//! @{


/*!
        \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.
        \retval B_BAD_VALUE The \a index is less than zero (0).
        \retval B_BAD_INDEX The \a index is out of bounds.
        \retval B_NAME_NOT_FOUND The \a name does not hava any data associated with
                it.
        \see RemoveName()
        \see MakeEmpty()
*/


/*!
        \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.
        \retval B_BAD_VALUE The \a name pointer points to \c NULL.
        \retval B_NAME_NOT_FOUND The \a name does not exist in this message.
        \see RemoveData()
        \see MakeEmpty()
*/


/*!
        \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 B_OK.
        \see RemoveData()
        \see RemoveName()
*/


//! @}


/*!
        \name Finding Data
        
        Look at FindData() for a general introduction to finding data.
*/

/* TODO:        
        Quick overview:
        
        <table>
                <tr><th>Type of data</th><th>Type code</th><th>Method</td></tr>
                <tr><td>BRect</td><td>B_RECT_TYPE</td><td>FindRect()</td></tr>
        </table>
*/


//! @{


/*!
        \fn status_t BMessage::FindData(const char *name, type_code type,
                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.
        \param index The index in the array of the data that you want to retrieve.
                Note that the array is zero-based.
        \param[out] data A pointer to a pointer where the data can point to.
        \param[out] numBytes The size of the data will be put in this parameter.
        \retval B_OK The \a name was found, matches the type, and the data at
                \a index has been put in \a data.
        \retval B_BAD_VALUE One of the output arguments were \c NULL.
        \retval B_BAD_INDEX The \a index does not exist.
        \retval B_NAME_NOT_FOUND There is no field with this \a name.
        \see status_t FindData(const char *, type_code, int32,
                const void **, ssize_t *) const
*/


/*!
        \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 0.
*/


/*!
        \fn status_t BMessage::FindRect(con