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