X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Forg%2Fldk%2Fstructs%2FSocketDescriptor.java;h=3edbde56f6b9f0801b05c48e7c4ab7bc0c7bf327;hb=f3e670e9341decac613d33fc52febf19cea32f20;hp=40dfc014bb13beedced50a6332ff72060e3a7b0d;hpb=a9b82019e7ffa7d32d44943133bb64e1197bd2f1;p=ldk-java diff --git a/src/main/java/org/ldk/structs/SocketDescriptor.java b/src/main/java/org/ldk/structs/SocketDescriptor.java index 40dfc014..3edbde56 100644 --- a/src/main/java/org/ldk/structs/SocketDescriptor.java +++ b/src/main/java/org/ldk/structs/SocketDescriptor.java @@ -4,7 +4,22 @@ import org.ldk.impl.bindings; import org.ldk.enums.*; import org.ldk.util.*; import java.util.Arrays; +import javax.annotation.Nullable; +/** + * Provides an object which can be used to send data to and which uniquely identifies a connection + * to a remote host. You will need to be able to generate multiple of these which meet Eq and + * implement Hash to meet the PeerManager API. + * + * For efficiency, Clone should be relatively cheap for this type. + * + * Two descriptors may compare equal (by [`cmp::Eq`] and [`hash::Hash`]) as long as the original + * has been disconnected, the [`PeerManager`] has been informed of the disconnection (either by it + * having triggered the disconnection or a call to [`PeerManager::socket_disconnected`]), and no + * further calls to the [`PeerManager`] related to the original socket occur. This allows you to + * use a file descriptor for your SocketDescriptor directly, however for simplicity you may wish + * to simply use another value which is guaranteed to be globally unique instead. + */ @SuppressWarnings("unchecked") // We correctly assign various generic arrays public class SocketDescriptor extends CommonBase { final bindings.LDKSocketDescriptor bindings_instance; @@ -20,9 +35,41 @@ public class SocketDescriptor extends CommonBase { } public static interface SocketDescriptorInterface { + /** + * Attempts to send some data from the given slice to the peer. + * + * Returns the amount of data which was sent, possibly 0 if the socket has since disconnected. + * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be + * called and further write attempts may occur until that time. + * + * If the returned size is smaller than `data.len()`, a + * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be + * written. Additionally, until a `send_data` event completes fully, no further + * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to + * prevent denial-of-service issues, you should not read or buffer any data from the socket + * until then. + * + * If a [`PeerManager::read_event`] call on this descriptor had previously returned true + * (indicating that read events should be paused to prevent DoS in the send buffer), + * `resume_read` may be set indicating that read events on this descriptor should resume. A + * `resume_read` of false carries no meaning, and should not cause any action. + */ long send_data(byte[] data, boolean resume_read); + /** + * Disconnect the socket pointed to by this SocketDescriptor. + * + * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this + * call (doing so is a noop). + */ void disconnect_socket(); + /** + * Checks if two objects are equal given this object's this_arg pointer and another object. + */ boolean eq(SocketDescriptor other_arg); + /** + * Calculate a succinct non-cryptographic hash for an object given its this_arg pointer. + * This is used, for example, for inclusion of this object in a hash map. + */ long hash(); } private static class LDKSocketDescriptorHolder { SocketDescriptor held; } @@ -49,22 +96,60 @@ public class SocketDescriptor extends CommonBase { }); return impl_holder.held; } + /** + * Attempts to send some data from the given slice to the peer. + * + * Returns the amount of data which was sent, possibly 0 if the socket has since disconnected. + * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be + * called and further write attempts may occur until that time. + * + * If the returned size is smaller than `data.len()`, a + * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be + * written. Additionally, until a `send_data` event completes fully, no further + * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to + * prevent denial-of-service issues, you should not read or buffer any data from the socket + * until then. + * + * If a [`PeerManager::read_event`] call on this descriptor had previously returned true + * (indicating that read events should be paused to prevent DoS in the send buffer), + * `resume_read` may be set indicating that read events on this descriptor should resume. A + * `resume_read` of false carries no meaning, and should not cause any action. + */ public long send_data(byte[] data, boolean resume_read) { long ret = bindings.SocketDescriptor_send_data(this.ptr, data, resume_read); return ret; } + /** + * Disconnect the socket pointed to by this SocketDescriptor. + * + * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this + * call (doing so is a noop). + */ public void disconnect_socket() { bindings.SocketDescriptor_disconnect_socket(this.ptr); } + /** + * Calculate a succinct non-cryptographic hash for an object given its this_arg pointer. + * This is used, for example, for inclusion of this object in a hash map. + */ public long hash() { long ret = bindings.SocketDescriptor_hash(this.ptr); return ret; } + long clone_ptr() { + long ret = bindings.SocketDescriptor_clone_ptr(this.ptr); + return ret; + } + + /** + * Creates a copy of a SocketDescriptor + */ public SocketDescriptor clone() { long ret = bindings.SocketDescriptor_clone(this.ptr); + if (ret >= 0 && ret <= 4096) { return null; } SocketDescriptor ret_hu_conv = new SocketDescriptor(null, ret); ret_hu_conv.ptrs_to.add(this); return ret_hu_conv;