diff --git a/docs/user/app/Message.dox b/docs/user/app/Message.dox new file mode 100644 index 0000000000..1899b70ce6 --- /dev/null +++ b/docs/user/app/Message.dox @@ -0,0 +1,2190 @@ +/* + * 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 + important elements: 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 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()). + + 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: + + + + +
Type of dataType codeMethod
BRectB_RECT_TYPEFindRect()
+*/ + + +//! @{ + + +/*! + \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(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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindRect(const char *, BRect *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindPoint(const char *, BPoint *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindString(const char *, const char **) const + \see FindString(const char *, int32, BString *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindString(const char *, BString *) const + \see FindString(const char *, int32, const char **) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindInt8(const char *, int8 *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindInt16(const char *, int16 *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindInt32(const char *, int32 *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindInt64(const char *, int64 *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindBool(const char *, bool *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindFloat(const char *, float *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindDouble(const char *, double *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindPointer(const char *, double *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindMessenger(const char *, BMessenger *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindRef(const char *, entry_ref *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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 \a 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindMessage(const char *, BMessage *) const +*/ + + +/*! + \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 zero. +*/ + + +/*! + \fn status_t BMessage::FindFlat(const char *name, int32 index, + 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. + \retval B_OK The object now contains the requested data. + \retval B_BAD_INDEX The \a index does not exist. + \retval B_NAME_NOT_FOUND There is no field with this \a name. + \see FindFlat(const char *, BFlattenable *) const +*/ + + +//! @} + + +/*! + \name Replacing Data + + Look at ReplaceData() for a general introduction to replacing data. +*/ + + +//! @{ + + +/*! + \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 + zero. See ReplaceData(const char *, type_code, int32, const void *, ssize_t). +*/ + + +/*! + \fn status_t BMessage::ReplaceData(const char *name, type_code type, + 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, + check that \a numBytes is the same as the specified fixed size. + \retval B_BAD_INDEX The \a index is out of range. +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param index The index in the array to replace. + \param aRect The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceRect(const char*, BRect) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param index The index in the array to replace. + \param aPoint The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplacePoint(const char*, aPoint) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param index The index in the array to replace. + \param aString The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceString(const char*, const char *) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param index The index in the array to replace. + \param aString The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceString(const char*, BString &) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param index The index in the array to replace. + \param value The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceInt8(const char*, int8) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param index The index in the array to replace. + \param value The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceInt16(const char*, int16) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param index The index in the array to replace. + \param value The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceInt32(const char*, int32) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param index The index in the array to replace. + \param value The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceInt64(const char*, int64) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param name The name associated with the data to replace. + \param index The index in the array to replace. + \param aBoolean The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceBool(const char*, bool) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param name The name associated with the data to replace. + \param index The index in the array to replace. + \param aFloat The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceFloat(const char*, float) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param name The name associated with the data to replace. + \param index The index in the array to replace. + \param aDouble The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceDouble(const char*, double) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param name The name associated with the data to replace. + \param index The index in the array to replace. + \param pointer The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplacePointer(const char*, const void *) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param name The name associated with the data to replace. + \param index The index in the array to replace. + \param messenger The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceMessenger(const char*, BMessenger) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param name The name associated with the data to replace. + \param index The index in the array to replace. + \param ref The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceRef(const char*, entry_ref *) +*/ + + +/*! + \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 zero. +*/ + + +/*! + \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. + \param name The name associated with the data to replace. + \param index The index in the array to replace. + \param message The object to store in the message. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceMessage(const char*, BMessage *) +*/ + + +/*! + \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 *). + It replaces the data at \a index zero. +*/ + + +/*! + \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. + \retval B_OK The operation succeeded. + \retval B_BAD_INDEX The index was out of range. + \see ReplaceFlat(const char*, BFlattenable *) +*/ + + +//! @} + + +/*! + \name Deprecated methods + + These methods are 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. +*/ + + +//! @{ + + +/*! + \fn void *BMessage::operator new(size_t size) + \brief Internal operator. +*/ + + +/*! + \fn void *BMessage::operator new(size_t, void *pointer) + \brief Internal operator. +*/ + + +/*! + \fn void BMessage::operator delete(void *pointer, size_t size) + \brief Internal operator. +*/ + + +/*! + \fn bool BMessage::HasRect(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasPoint(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasString(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasInt8(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasInt16(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasInt32(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasInt64(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasBool(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasFloat(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasDouble(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasPointer(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasMessenger(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasRef(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasMessage(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasFlat(const char *, const BFlattenable *) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasFlat(const char *, int32, const BFlattenable *) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::HasData(const char *, type_code , int32) const + \brief Deprecated. +*/ + + +/*! + \fn BRect BMessage::FindRect(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn BPoint BMessage::FindPoint(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn const char *BMessage::FindString(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn int8 BMessage::FindInt8(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn int16 BMessage::FindInt16(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn int32 BMessage::FindInt32(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn int64 BMessage::FindInt64(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn bool BMessage::FindBool(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn float BMessage::FindFloat(const char *, int32) const + \brief Deprecated. +*/ + + +/*! + \fn double BMessage::FindDouble(const char *, int32) const + \brief Deprecated. +*/ + + +//! @} diff --git a/docs/user/app/MessageFilter.dox b/docs/user/app/MessageFilter.dox index a915ee7908..29b9bbe5f0 100644 --- a/docs/user/app/MessageFilter.dox +++ b/docs/user/app/MessageFilter.dox @@ -136,6 +136,7 @@ /*! \class BMessageFilter + \ingroup app \brief Describes a message filter for BLooper and BHandler. Objects of this class serve as a description of properties that incoming