Regenerate auto-generated bindings with license info and new upstream
[ldk-c-bindings] / lightning-c-bindings / src / ln / peer_handler.rs
index 9e7422a6eac6f4b5606201e80ebb53968ea762ff..9f3f8409cfc9484da166c1abb6ae0b45487621a7 100644 (file)
@@ -1,3 +1,11 @@
+// This file is Copyright its original authors, visible in version control
+// history and in the source files from which this was generated.
+//
+// This file is licensed under the license available in the LICENSE or LICENSE.md
+// file in the root of this repository or, if no such file exists, the same
+// license as that which applies to the original source files from which this
+// source was automatically generated.
+
 //! Top level peer message handling and socket handling logic lives here.
 //!
 //! Instead of actually servicing sockets ourselves we require that you implement the
@@ -19,9 +27,15 @@ type nativeIgnoringMessageHandler = nativeIgnoringMessageHandlerImport;
 #[must_use]
 #[repr(C)]
 pub struct IgnoringMessageHandler {
+       /// A pointer to the opaque Rust object.
+
        /// Nearly everywhere, inner must be non-null, however in places where
        /// the Rust equivalent takes an Option, it may be set to null to indicate None.
        pub inner: *mut nativeIgnoringMessageHandler,
+       /// Indicates that this is the only struct which contains the same pointer.
+
+       /// Rust functions which take ownership of an object provided via an argument require
+       /// this to be true and invalidate the object pointed to by inner.
        pub is_owned: bool,
 }
 
@@ -32,8 +46,9 @@ impl Drop for IgnoringMessageHandler {
                }
        }
 }
+/// Frees any resources used by the IgnoringMessageHandler, if is_owned is set and inner is non-NULL.
 #[no_mangle]
-pub extern "C" fn IgnoringMessageHandler_free(this_ptr: IgnoringMessageHandler) { }
+pub extern "C" fn IgnoringMessageHandler_free(this_obj: IgnoringMessageHandler) { }
 #[allow(unused)]
 /// Used only if an object of this type is returned as a trait impl by a method
 extern "C" fn IgnoringMessageHandler_free_void(this_ptr: *mut c_void) {
@@ -49,6 +64,7 @@ impl IgnoringMessageHandler {
                ret
        }
 }
+/// Constructs a new IgnoringMessageHandler given each field
 #[must_use]
 #[no_mangle]
 pub extern "C" fn IgnoringMessageHandler_new() -> IgnoringMessageHandler {
@@ -65,6 +81,8 @@ impl From<nativeIgnoringMessageHandler> for crate::util::events::MessageSendEven
                ret
        }
 }
+/// Constructs a new MessageSendEventsProvider which calls the relevant methods on this_arg.
+/// This copies the `inner` pointer in this_arg and thus the returned MessageSendEventsProvider must be freed before this_arg is
 #[no_mangle]
 pub extern "C" fn IgnoringMessageHandler_as_MessageSendEventsProvider(this_arg: &IgnoringMessageHandler) -> crate::util::events::MessageSendEventsProvider {
        crate::util::events::MessageSendEventsProvider {
@@ -91,6 +109,8 @@ impl From<nativeIgnoringMessageHandler> for crate::ln::msgs::RoutingMessageHandl
                ret
        }
 }
+/// Constructs a new RoutingMessageHandler which calls the relevant methods on this_arg.
+/// This copies the `inner` pointer in this_arg and thus the returned RoutingMessageHandler must be freed before this_arg is
 #[no_mangle]
 pub extern "C" fn IgnoringMessageHandler_as_RoutingMessageHandler(this_arg: &IgnoringMessageHandler) -> crate::ln::msgs::RoutingMessageHandler {
        crate::ln::msgs::RoutingMessageHandler {
@@ -192,9 +212,15 @@ type nativeErroringMessageHandler = nativeErroringMessageHandlerImport;
 #[must_use]
 #[repr(C)]
 pub struct ErroringMessageHandler {
+       /// A pointer to the opaque Rust object.
+
        /// Nearly everywhere, inner must be non-null, however in places where
        /// the Rust equivalent takes an Option, it may be set to null to indicate None.
        pub inner: *mut nativeErroringMessageHandler,
+       /// Indicates that this is the only struct which contains the same pointer.
+
+       /// Rust functions which take ownership of an object provided via an argument require
+       /// this to be true and invalidate the object pointed to by inner.
        pub is_owned: bool,
 }
 
@@ -205,8 +231,9 @@ impl Drop for ErroringMessageHandler {
                }
        }
 }
+/// Frees any resources used by the ErroringMessageHandler, if is_owned is set and inner is non-NULL.
 #[no_mangle]
-pub extern "C" fn ErroringMessageHandler_free(this_ptr: ErroringMessageHandler) { }
+pub extern "C" fn ErroringMessageHandler_free(this_obj: ErroringMessageHandler) { }
 #[allow(unused)]
 /// Used only if an object of this type is returned as a trait impl by a method
 extern "C" fn ErroringMessageHandler_free_void(this_ptr: *mut c_void) {
@@ -240,6 +267,8 @@ impl From<nativeErroringMessageHandler> for crate::util::events::MessageSendEven
                ret
        }
 }
+/// Constructs a new MessageSendEventsProvider which calls the relevant methods on this_arg.
+/// This copies the `inner` pointer in this_arg and thus the returned MessageSendEventsProvider must be freed before this_arg is
 #[no_mangle]
 pub extern "C" fn ErroringMessageHandler_as_MessageSendEventsProvider(this_arg: &ErroringMessageHandler) -> crate::util::events::MessageSendEventsProvider {
        crate::util::events::MessageSendEventsProvider {
@@ -266,6 +295,8 @@ impl From<nativeErroringMessageHandler> for crate::ln::msgs::ChannelMessageHandl
                ret
        }
 }
+/// Constructs a new ChannelMessageHandler which calls the relevant methods on this_arg.
+/// This copies the `inner` pointer in this_arg and thus the returned ChannelMessageHandler must be freed before this_arg is
 #[no_mangle]
 pub extern "C" fn ErroringMessageHandler_as_ChannelMessageHandler(this_arg: &ErroringMessageHandler) -> crate::ln::msgs::ChannelMessageHandler {
        crate::ln::msgs::ChannelMessageHandler {
@@ -289,6 +320,7 @@ pub extern "C" fn ErroringMessageHandler_as_ChannelMessageHandler(this_arg: &Err
                peer_disconnected: ErroringMessageHandler_ChannelMessageHandler_peer_disconnected,
                peer_connected: ErroringMessageHandler_ChannelMessageHandler_peer_connected,
                handle_channel_reestablish: ErroringMessageHandler_ChannelMessageHandler_handle_channel_reestablish,
+               handle_channel_update: ErroringMessageHandler_ChannelMessageHandler_handle_channel_update,
                handle_error: ErroringMessageHandler_ChannelMessageHandler_handle_error,
                MessageSendEventsProvider: crate::util::events::MessageSendEventsProvider {
                        this_arg: unsafe { (*this_arg).inner as *mut c_void },
@@ -346,6 +378,9 @@ extern "C" fn ErroringMessageHandler_ChannelMessageHandler_handle_announcement_s
 extern "C" fn ErroringMessageHandler_ChannelMessageHandler_handle_channel_reestablish(this_arg: *const c_void, mut their_node_id: crate::c_types::PublicKey, msg: &crate::ln::msgs::ChannelReestablish) {
        <nativeErroringMessageHandler as lightning::ln::msgs::ChannelMessageHandler<>>::handle_channel_reestablish(unsafe { &mut *(this_arg as *mut nativeErroringMessageHandler) }, &their_node_id.into_rust(), unsafe { &*msg.inner })
 }
+extern "C" fn ErroringMessageHandler_ChannelMessageHandler_handle_channel_update(this_arg: *const c_void, mut _their_node_id: crate::c_types::PublicKey, _msg: &crate::ln::msgs::ChannelUpdate) {
+       <nativeErroringMessageHandler as lightning::ln::msgs::ChannelMessageHandler<>>::handle_channel_update(unsafe { &mut *(this_arg as *mut nativeErroringMessageHandler) }, &_their_node_id.into_rust(), unsafe { &*_msg.inner })
+}
 extern "C" fn ErroringMessageHandler_ChannelMessageHandler_peer_disconnected(this_arg: *const c_void, mut _their_node_id: crate::c_types::PublicKey, mut _no_connection_possible: bool) {
        <nativeErroringMessageHandler as lightning::ln::msgs::ChannelMessageHandler<>>::peer_disconnected(unsafe { &mut *(this_arg as *mut nativeErroringMessageHandler) }, &_their_node_id.into_rust(), _no_connection_possible)
 }
@@ -370,9 +405,15 @@ type nativeMessageHandler = nativeMessageHandlerImport<crate::ln::msgs::ChannelM
 #[must_use]
 #[repr(C)]
 pub struct MessageHandler {
+       /// A pointer to the opaque Rust object.
+
        /// Nearly everywhere, inner must be non-null, however in places where
        /// the Rust equivalent takes an Option, it may be set to null to indicate None.
        pub inner: *mut nativeMessageHandler,
+       /// Indicates that this is the only struct which contains the same pointer.
+
+       /// Rust functions which take ownership of an object provided via an argument require
+       /// this to be true and invalidate the object pointed to by inner.
        pub is_owned: bool,
 }
 
@@ -383,8 +424,9 @@ impl Drop for MessageHandler {
                }
        }
 }
+/// Frees any resources used by the MessageHandler, if is_owned is set and inner is non-NULL.
 #[no_mangle]
-pub extern "C" fn MessageHandler_free(this_ptr: MessageHandler) { }
+pub extern "C" fn MessageHandler_free(this_obj: MessageHandler) { }
 #[allow(unused)]
 /// Used only if an object of this type is returned as a trait impl by a method
 extern "C" fn MessageHandler_free_void(this_ptr: *mut c_void) {
@@ -426,6 +468,7 @@ pub extern "C" fn MessageHandler_get_route_handler(this_ptr: &MessageHandler) ->
 pub extern "C" fn MessageHandler_set_route_handler(this_ptr: &mut MessageHandler, mut val: crate::ln::msgs::RoutingMessageHandler) {
        unsafe { &mut *this_ptr.inner }.route_handler = val;
 }
+/// Constructs a new MessageHandler given each field
 #[must_use]
 #[no_mangle]
 pub extern "C" fn MessageHandler_new(mut chan_handler_arg: crate::ln::msgs::ChannelMessageHandler, mut route_handler_arg: crate::ln::msgs::RoutingMessageHandler) -> MessageHandler {
@@ -447,6 +490,8 @@ pub extern "C" fn MessageHandler_new(mut chan_handler_arg: crate::ln::msgs::Chan
 /// PeerManager::socket_disconnected().
 #[repr(C)]
 pub struct SocketDescriptor {
+       /// An opaque pointer which is passed to your function implementations as an argument.
+       /// This has no meaning in the LDK, and can be NULL or any other value.
        pub this_arg: *mut c_void,
        /// Attempts to send some data from the given slice to the peer.
        ///
@@ -470,9 +515,17 @@ pub struct SocketDescriptor {
        /// though races may occur whereby disconnect_socket is called after a call to
        /// socket_disconnected but prior to socket_disconnected returning.
        pub disconnect_socket: extern "C" fn (this_arg: *mut c_void),
+       /// Checks if two objects are equal given this object's this_arg pointer and another object.
        pub eq: extern "C" fn (this_arg: *const c_void, other_arg: &SocketDescriptor) -> bool,
+       /// 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.
        pub hash: extern "C" fn (this_arg: *const c_void) -> u64,
+       /// Creates a copy of the object pointed to by this_arg, for a copy of this SocketDescriptor.
+       /// Note that the ultimate copy of the SocketDescriptor will have all function pointers the same as the original.
+       /// May be NULL if no action needs to be taken, the this_arg pointer will be copied into the new SocketDescriptor.
        pub clone: Option<extern "C" fn (this_arg: *const c_void) -> *mut c_void>,
+       /// Frees any resources associated with this object given its this_arg pointer.
+       /// Does not need to free the outer struct containing function pointers and may be NULL is no resources need to be freed.
        pub free: Option<extern "C" fn(this_arg: *mut c_void)>,
 }
 impl std::cmp::Eq for SocketDescriptor {}
@@ -483,6 +536,7 @@ impl std::hash::Hash for SocketDescriptor {
        fn hash<H: std::hash::Hasher>(&self, hasher: &mut H) { hasher.write_u64((self.hash)(self.this_arg)) }
 }
 #[no_mangle]
+/// Creates a copy of a SocketDescriptor
 pub extern "C" fn SocketDescriptor_clone(orig: &SocketDescriptor) -> SocketDescriptor {
        SocketDescriptor {
                this_arg: if let Some(f) = orig.clone { (f)(orig.this_arg) } else { orig.this_arg },
@@ -540,9 +594,15 @@ type nativePeerHandleError = nativePeerHandleErrorImport;
 #[must_use]
 #[repr(C)]
 pub struct PeerHandleError {
+       /// A pointer to the opaque Rust object.
+
        /// Nearly everywhere, inner must be non-null, however in places where
        /// the Rust equivalent takes an Option, it may be set to null to indicate None.
        pub inner: *mut nativePeerHandleError,
+       /// Indicates that this is the only struct which contains the same pointer.
+
+       /// Rust functions which take ownership of an object provided via an argument require
+       /// this to be true and invalidate the object pointed to by inner.
        pub is_owned: bool,
 }
 
@@ -553,8 +613,9 @@ impl Drop for PeerHandleError {
                }
        }
 }
+/// Frees any resources used by the PeerHandleError, if is_owned is set and inner is non-NULL.
 #[no_mangle]
-pub extern "C" fn PeerHandleError_free(this_ptr: PeerHandleError) { }
+pub extern "C" fn PeerHandleError_free(this_obj: PeerHandleError) { }
 #[allow(unused)]
 /// Used only if an object of this type is returned as a trait impl by a method
 extern "C" fn PeerHandleError_free_void(this_ptr: *mut c_void) {
@@ -583,6 +644,7 @@ pub extern "C" fn PeerHandleError_get_no_connection_possible(this_ptr: &PeerHand
 pub extern "C" fn PeerHandleError_set_no_connection_possible(this_ptr: &mut PeerHandleError, mut val: bool) {
        unsafe { &mut *this_ptr.inner }.no_connection_possible = val;
 }
+/// Constructs a new PeerHandleError given each field
 #[must_use]
 #[no_mangle]
 pub extern "C" fn PeerHandleError_new(mut no_connection_possible_arg: bool) -> PeerHandleError {
@@ -605,6 +667,7 @@ pub(crate) extern "C" fn PeerHandleError_clone_void(this_ptr: *const c_void) ->
        Box::into_raw(Box::new(unsafe { (*(this_ptr as *mut nativePeerHandleError)).clone() })) as *mut c_void
 }
 #[no_mangle]
+/// Creates a copy of the PeerHandleError
 pub extern "C" fn PeerHandleError_clone(orig: &PeerHandleError) -> PeerHandleError {
        orig.clone()
 }
@@ -623,9 +686,15 @@ type nativePeerManager = nativePeerManagerImport<crate::ln::peer_handler::Socket
 #[must_use]
 #[repr(C)]
 pub struct PeerManager {
+       /// A pointer to the opaque Rust object.
+
        /// Nearly everywhere, inner must be non-null, however in places where
        /// the Rust equivalent takes an Option, it may be set to null to indicate None.
        pub inner: *mut nativePeerManager,
+       /// Indicates that this is the only struct which contains the same pointer.
+
+       /// Rust functions which take ownership of an object provided via an argument require
+       /// this to be true and invalidate the object pointed to by inner.
        pub is_owned: bool,
 }
 
@@ -636,8 +705,9 @@ impl Drop for PeerManager {
                }
        }
 }
+/// Frees any resources used by the PeerManager, if is_owned is set and inner is non-NULL.
 #[no_mangle]
-pub extern "C" fn PeerManager_free(this_ptr: PeerManager) { }
+pub extern "C" fn PeerManager_free(this_obj: PeerManager) { }
 #[allow(unused)]
 /// Used only if an object of this type is returned as a trait impl by a method
 extern "C" fn PeerManager_free_void(this_ptr: *mut c_void) {