_ Git - ldk-java/blob - src/main/java/org/ldk/structs/SocketDescriptor.java

   1 package org.ldk.structs;
   2
   3 import org.ldk.impl.bindings;
   4 import org.ldk.enums.*;
   5 import org.ldk.util.*;
   6 import java.util.Arrays;
   7 import javax.annotation.Nullable;
   8
   9 /**
  10  * Provides an object which can be used to send data to and which uniquely identifies a connection
  11  * to a remote host. You will need to be able to generate multiple of these which meet Eq and
  12  * implement Hash to meet the PeerManager API.
  13  *
  14  * For efficiency, Clone should be relatively cheap for this type.
  15  *
  16  * Two descriptors may compare equal (by [`cmp::Eq`] and [`hash::Hash`]) as long as the original
  17  * has been disconnected, the [`PeerManager`] has been informed of the disconnection (either by it
  18  * having triggered the disconnection or a call to [`PeerManager::socket_disconnected`]), and no
  19  * further calls to the [`PeerManager`] related to the original socket occur. This allows you to
  20  * use a file descriptor for your SocketDescriptor directly, however for simplicity you may wish
  21  * to simply use another value which is guaranteed to be globally unique instead.
  22  */
  23 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  24 public class SocketDescriptor extends CommonBase {
  25         final bindings.LDKSocketDescriptor bindings_instance;
  26         SocketDescriptor(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
  27         private SocketDescriptor(bindings.LDKSocketDescriptor arg) {
  28                 super(bindings.LDKSocketDescriptor_new(arg));
  29                 this.ptrs_to.add(arg);
  30                 this.bindings_instance = arg;
  31         }
  32         @Override @SuppressWarnings("deprecation")
  33         protected void finalize() throws Throwable {
  34                 if (ptr != 0) { bindings.SocketDescriptor_free(ptr); } super.finalize();
  35         }
  36
  37         public static interface SocketDescriptorInterface {
  38                 /**
  39                  * Attempts to send some data from the given slice to the peer.
  40                  *
  41                  * Returns the amount of data which was sent, possibly 0 if the socket has since disconnected.
  42                  * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be
  43                  * called and further write attempts may occur until that time.
  44                  *
  45                  * If the returned size is smaller than `data.len()`, a
  46                  * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be
  47                  * written. Additionally, until a `send_data` event completes fully, no further
  48                  * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to
  49                  * prevent denial-of-service issues, you should not read or buffer any data from the socket
  50                  * until then.
  51                  *
  52                  * If a [`PeerManager::read_event`] call on this descriptor had previously returned true
  53                  * (indicating that read events should be paused to prevent DoS in the send buffer),
  54                  * `resume_read` may be set indicating that read events on this descriptor should resume. A
  55                  * `resume_read` of false carries no meaning, and should not cause any action.
  56                  */
  57                 long send_data(byte[] data, boolean resume_read);
  58                 /**
  59                  * Disconnect the socket pointed to by this SocketDescriptor.
  60                  *
  61                  * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
  62                  * call (doing so is a noop).
  63                  */
  64                 void disconnect_socket();
  65                 /**
  66                  * Checks if two objects are equal given this object's this_arg pointer and another object.
  67                  */
  68                 boolean eq(SocketDescriptor other_arg);
  69                 /**
  70                  * Calculate a succinct non-cryptographic hash for an object given its this_arg pointer.
  71                  * This is used, for example, for inclusion of this object in a hash map.
  72                  */
  73                 long hash();
  74         }
  75         private static class LDKSocketDescriptorHolder { SocketDescriptor held; }
  76         public static SocketDescriptor new_impl(SocketDescriptorInterface arg) {
  77                 final LDKSocketDescriptorHolder impl_holder = new LDKSocketDescriptorHolder();
  78                 impl_holder.held = new SocketDescriptor(new bindings.LDKSocketDescriptor() {
  79                         @Override public long send_data(byte[] data, boolean resume_read) {
  80                                 long ret = arg.send_data(data, resume_read);
  81                                 return ret;
  82                         }
  83                         @Override public void disconnect_socket() {
  84                                 arg.disconnect_socket();
  85                         }
  86                         @Override public boolean eq(long other_arg) {
  87                                 SocketDescriptor ret_hu_conv = new SocketDescriptor(null, other_arg);
  88                                 ret_hu_conv.ptrs_to.add(this);
  89                                 boolean ret = arg.eq(ret_hu_conv);
  90                                 return ret;
  91                         }
  92                         @Override public long hash() {
  93                                 long ret = arg.hash();
  94                                 return ret;
  95                         }
  96                 });
  97                 return impl_holder.held;
  98         }
  99         /**
 100          * Attempts to send some data from the given slice to the peer.
 101          *
 102          * Returns the amount of data which was sent, possibly 0 if the socket has since disconnected.
 103          * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be
 104          * called and further write attempts may occur until that time.
 105          *
 106          * If the returned size is smaller than `data.len()`, a
 107          * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be
 108          * written. Additionally, until a `send_data` event completes fully, no further
 109          * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to
 110          * prevent denial-of-service issues, you should not read or buffer any data from the socket
 111          * until then.
 112          *
 113          * If a [`PeerManager::read_event`] call on this descriptor had previously returned true
 114          * (indicating that read events should be paused to prevent DoS in the send buffer),
 115          * `resume_read` may be set indicating that read events on this descriptor should resume. A
 116          * `resume_read` of false carries no meaning, and should not cause any action.
 117          */
 118         public long send_data(byte[] data, boolean resume_read) {
 119                 long ret = bindings.SocketDescriptor_send_data(this.ptr, data, resume_read);
 120                 return ret;
 121         }
 122
 123         /**
 124          * Disconnect the socket pointed to by this SocketDescriptor.
 125          *
 126          * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
 127          * call (doing so is a noop).
 128          */
 129         public void disconnect_socket() {
 130                 bindings.SocketDescriptor_disconnect_socket(this.ptr);
 131         }
 132
 133         /**
 134          * Calculate a succinct non-cryptographic hash for an object given its this_arg pointer.
 135          * This is used, for example, for inclusion of this object in a hash map.
 136          */
 137         public long hash() {
 138                 long ret = bindings.SocketDescriptor_hash(this.ptr);
 139                 return ret;
 140         }
 141
 142         /**
 143          * Creates a copy of a SocketDescriptor
 144          */
 145         public SocketDescriptor clone() {
 146                 long ret = bindings.SocketDescriptor_clone(this.ptr);
 147                 if (ret >= 0 && ret <= 4096) { return null; }
 148                 SocketDescriptor ret_hu_conv = new SocketDescriptor(null, ret);
 149                 ret_hu_conv.ptrs_to.add(this);
 150                 return ret_hu_conv;
 151         }
 152
 153 }