X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FCustomMessageHandler.java;h=7425c2ebe65c4c4dfeb30a6c9ffd016fc7dfce3b;hb=5cdb34f643d09f21c147c9d0b2f8888609e43429;hp=5d1586b623dd7d2d8f35c13c465652806f99210b;hpb=8aa8a96fc6d8fcdd3fbb419b4b4c12482af14938;p=ldk-java

diff --git a/src/main/java/org/ldk/structs/CustomMessageHandler.java b/src/main/java/org/ldk/structs/CustomMessageHandler.java
index 5d1586b6..7425c2eb 100644
--- a/src/main/java/org/ldk/structs/CustomMessageHandler.java
+++ b/src/main/java/org/ldk/structs/CustomMessageHandler.java
@@ -8,7 +8,14 @@ import java.lang.ref.Reference;
 import javax.annotation.Nullable;
 
 /**
- * Handler for BOLT1-compliant messages.
+ * A handler provided to [`PeerManager`] for reading and handling custom messages.
+ * 
+ * [BOLT 1] specifies a custom message type range for use with experimental or application-specific
+ * messages. `CustomMessageHandler` allows for user-defined handling of such types. See the
+ * [`lightning_custom_message`] crate for tools useful in composing more than one custom handler.
+ * 
+ * [BOLT 1]: https://github.com/lightning/bolts/blob/master/01-messaging.md
+ * [`lightning_custom_message`]: https://docs.rs/lightning_custom_message/latest/lightning_custom_message
  */
 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
 public class CustomMessageHandler extends CommonBase {
@@ -24,18 +31,30 @@ public class CustomMessageHandler extends CommonBase {
 	protected void finalize() throws Throwable {
 		if (ptr != 0) { bindings.CustomMessageHandler_free(ptr); } super.finalize();
 	}
-
+	/**
+	 * Destroys the object, freeing associated resources. After this call, any access
+	 * to this object may result in a SEGFAULT or worse.
+	 *
+	 * You should generally NEVER call this method. You should let the garbage collector
+	 * do this for you when it finalizes objects. However, it may be useful for types
+	 * which represent locks and should be closed immediately to avoid holding locks
+	 * until the GC runs.
+	 */
+	public void destroy() {
+		if (ptr != 0) { bindings.CustomMessageHandler_free(ptr); }
+		ptr = 0;
+	}
 	public static interface CustomMessageHandlerInterface {
 		/**
-		 * Called with the message type that was received and the buffer to be read.
-		 * Can return a `MessageHandlingError` if the message could not be handled.
+		 * Handles the given message sent from `sender_node_id`, possibly producing messages for
+		 * [`CustomMessageHandler::get_and_clear_pending_msg`] to return and thus for [`PeerManager`]
+		 * to send.
 		 */
 		Result_NoneLightningErrorZ handle_custom_message(Type msg, byte[] sender_node_id);
 		/**
-		 * Gets the list of pending messages which were generated by the custom message
-		 * handler, clearing the list in the process. The first tuple element must
-		 * correspond to the intended recipients node ids. If no connection to one of the
-		 * specified node does not exist, the message is simply not sent to it.
+		 * Returns the list of pending messages that were generated by the handler, clearing the list
+		 * in the process. Each message is paired with the node id of the intended recipient. If no
+		 * connection to the node exists, then the message is simply not sent.
 		 */
 		TwoTuple_PublicKeyTypeZ[] get_and_clear_pending_msg();
 	}
@@ -66,13 +85,14 @@ public class CustomMessageHandler extends CommonBase {
 	 */
 	public CustomMessageReader get_custom_message_reader() {
 		CustomMessageReader res = new CustomMessageReader(null, bindings.LDKCustomMessageHandler_get_CustomMessageReader(this.ptr));
-		this.ptrs_to.add(res);
+		res.ptrs_to.add(this);
 		return res;
 	}
 
 	/**
-	 * Called with the message type that was received and the buffer to be read.
-	 * Can return a `MessageHandlingError` if the message could not be handled.
+	 * Handles the given message sent from `sender_node_id`, possibly producing messages for
+	 * [`CustomMessageHandler::get_and_clear_pending_msg`] to return and thus for [`PeerManager`]
+	 * to send.
 	 */
 	public Result_NoneLightningErrorZ handle_custom_message(org.ldk.structs.Type msg, byte[] sender_node_id) {
 		long ret = bindings.CustomMessageHandler_handle_custom_message(this.ptr, msg == null ? 0 : msg.ptr, InternalUtils.check_arr_len(sender_node_id, 33));
@@ -86,10 +106,9 @@ public class CustomMessageHandler extends CommonBase {
 	}
 
 	/**
-	 * Gets the list of pending messages which were generated by the custom message
-	 * handler, clearing the list in the process. The first tuple element must
-	 * correspond to the intended recipients node ids. If no connection to one of the
-	 * specified node does not exist, the message is simply not sent to it.
+	 * Returns the list of pending messages that were generated by the handler, clearing the list
+	 * in the process. Each message is paired with the node id of the intended recipient. If no
+	 * connection to the node exists, then the message is simply not sent.
 	 */
 	public TwoTuple_PublicKeyTypeZ[] get_and_clear_pending_msg() {
 		long[] ret = bindings.CustomMessageHandler_get_and_clear_pending_msg(this.ptr);