AppKit: BMessage Add/Find/Get/Has/ReplaceNodeRef

This allows you to pass node_ref's around like you can entry_ref's.

Added node_ref_flatten(), node_ref_unflatten() and node_ref_swap() to
MessageUtils. These are close cousins to entry_ref_flatten(),
entry_ref_unflatten(), and entry_ref_swap() but for node_ref's.

Added B_NODE_REF_TYPE to TypeConstants.h in the Support Kit.

Added B_NODE_REF_TYPE to Debugger and ByteOrder in Support Kit,
B_NODE_REF_TYPE is treated the same as a B_REF_TYPE (entry_ref).

Add documentation for new NodeRef methods and B_NODE_REF_TYPE.

Change-Id: I32c6ed276bf1a7894a835b9fc9de5a882c35883c
Reviewed-on: https://review.haiku-os.org/c/haiku/+/3182
Reviewed-by: Adrien Destugues <[email protected]>

docs/user/app/Message.dox

@@ -1362,6 +1362,25 @@
 */
 
 
+/*!
+	\fn status_t BMessage::AddNodeRef(const char* name, const node_ref* ref)
+	\brief Convenience method to add a \c node_ref with the label \a name.
+
+	This method calls AddData() with the \c B_NODE_REF_TYPE \a type.
+
+	\param name The label to associate the data with.
+	\param ref The node reference to store in the message.
+
+	\returns A status code, \c B_OK on success or an error code.
+
+	\see AddData() for a more detailed overview of the inner workings.
+	\see FindNodeRef()
+	\see ReplaceNodeRef()
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\fn status_t BMessage::AddMessage(const char* name,
 		const BMessage* message)
@@ -2433,6 +2452,49 @@
 */
 
 
+/*!
+	\fn status_t BMessage::FindNodeRef(const char* name, node_ref* ref) const
+	\brief Find a reference to a node at the label \a name.
+
+	This is an overloaded version of
+	FindNodeRef(const char*, int32, node_ref*) const
+	where the data is sought at \a index \c 0.
+
+	\param name The label to which the data is associated.
+	\param ref The object into which the data should be copied.
+
+	\returns A status code, \c B_OK on success or an error code.
+	\retval B_OK The object now contains the requested data.
+	\retval B_NAME_NOT_FOUND There is no field with this \a name.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn status_t BMessage::FindNodeRef(const char* name, int32 index,
+		node_ref* ref) const
+	\brief Find a reference to a node at the label \a name at an
+	       \a index.
+
+	This method looks for the data with the \c B_NODE_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.
+
+	\returns A status code, \c B_OK on success or an error code.
+	\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 FindNodeRef(const char*, node_ref*) const
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\fn status_t BMessage::FindMessage(const char* name,
 		BMessage* message) const
@@ -3493,6 +3555,50 @@
 */
 
 
+/*!
+	\fn status_t BMessage::ReplaceNodeRef(const char* name,
+		const node_ref* ref)
+	\brief Replace a reference to a node at the label \a name.
+
+	This method is an overloaded method of
+	ReplaceNodeRef(const char*, int32, node_ref*).
+	It replaces the data at \a index \c 0.
+
+	\param name The name associated with the data to replace.
+	\param ref The object to store in the message.
+
+	\returns A status code, \c B_OK on success or an error code.
+	\retval B_OK The operation succeeded.
+	\retval B_NAME_NOT_FOUND There is no field with this \a name.
+
+	\since Haiku R1
+*/
+
+
+/*!
+	\fn status_t BMessage::ReplaceNodeRef(const char* name, int32 index,
+		const node_ref* ref)
+	\brief Replace a reference to a node 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_NODE_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.
+
+	\returns A status code, \c B_OK on success or an error code.
+	\retval B_OK The operation succeeded.
+	\retval B_BAD_INDEX The index was out of range.
+	\retval B_NAME_NOT_FOUND There is no field with this \a name.
+
+	\see ReplaceNodeRef(const char*, node_ref*)
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\fn status_t BMessage::ReplaceMessage(const char* name,
 		const BMessage* message)
@@ -3843,6 +3949,16 @@
 */
 
 
+/*!
+	\fn bool BMessage::HasNodeRef(const char*, int32) const
+	\brief Deprecated.
+
+	\warning This method is deprecated, do not use.
+
+	\since Haiku R1.
+*/
+
+
 /*!
 	\fn bool BMessage::HasMessage(const char*, int32) const
 	\brief Deprecated.

docs/user/support/TypeConstants.dox

@@ -220,6 +220,14 @@
 */
 
 
+/*!
+	\var B_NODE_REF_TYPE
+	\brief Represents a \c node_ref structure.
+
+	\since Haiku R1
+*/
+
+
 /*!
 	\var B_RGB_COLOR_TYPE
 	\brief Represents an \c rgb_color structure.