X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=ldk-java;a=blobdiff_plain;f=ts%2Fstructs%2FSocketDescriptor.mts;h=01775920a9224147e0cdc70b03c7c14045da5bdb;hp=59a47458124cc22e349611c0c1587d2f6563cc8d;hb=c629a01650402c8e2f9b9db8ced9ed63ce687727;hpb=d1d0121c000b713c10fd0bedd249eb8dda2e4db7 diff --git a/ts/structs/SocketDescriptor.mts b/ts/structs/SocketDescriptor.mts index 59a47458..01775920 100644 --- a/ts/structs/SocketDescriptor.mts +++ b/ts/structs/SocketDescriptor.mts @@ -283,10 +283,39 @@ import * as bindings from '../bindings.mjs' +/** An implementation of SocketDescriptor */ export 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. + */ send_data(data: Uint8Array, resume_read: boolean): number; + /**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). + */ disconnect_socket(): void; + /**Checks if two objects are equal given this object's this_arg pointer and another object. + */ eq(other_arg: SocketDescriptor): boolean; + /**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. + */ hash(): bigint; } @@ -294,6 +323,20 @@ class LDKSocketDescriptorHolder { held: SocketDescriptor; } +/** + * 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. + */ export class SocketDescriptor extends CommonBase { /* @internal */ public bindings_instance?: bindings.LDKSocketDescriptor; @@ -304,7 +347,8 @@ export class SocketDescriptor extends CommonBase { this.bindings_instance = null; } - static new_impl(arg: SocketDescriptorInterface): SocketDescriptor { + /** Creates a new instance of SocketDescriptor from a given implementation */ + public static new_impl(arg: SocketDescriptorInterface): SocketDescriptor { const impl_holder: LDKSocketDescriptorHolder = new LDKSocketDescriptorHolder(); let structImplementation = { send_data (data: number, resume_read: boolean): number { @@ -332,15 +376,45 @@ export class SocketDescriptor extends CommonBase { impl_holder.held.bindings_instance = structImplementation; 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 send_data(data: Uint8Array, resume_read: boolean): number { const ret: number = bindings.SocketDescriptor_send_data(this.ptr, bindings.encodeUint8Array(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 disconnect_socket(): void { 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 hash(): bigint { const ret: bigint = bindings.SocketDescriptor_hash(this.ptr); return ret; @@ -351,6 +425,9 @@ export class SocketDescriptor extends CommonBase { return ret; } + /** + * Creates a copy of a SocketDescriptor + */ public clone(): SocketDescriptor { const ret: number = bindings.SocketDescriptor_clone(this.ptr); const ret_hu_conv: SocketDescriptor = new SocketDescriptor(null, ret);