X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning-c-bindings%2Fsrc%2Flightning%2Futil%2Fevents.rs;h=7961f623bbc456c5ab50b8398cc3ddd0feca46fa;hb=033f4f3b2750dcd5afc8b158d7474242b29b24f3;hp=4dcbd81fee8ce51b96aeb9be6aa1f55076b91474;hpb=5eebd45b471833805e81ad4c23ec93d7711e0a23;p=ldk-c-bindings diff --git a/lightning-c-bindings/src/lightning/util/events.rs b/lightning-c-bindings/src/lightning/util/events.rs index 4dcbd81..7961f62 100644 --- a/lightning-c-bindings/src/lightning/util/events.rs +++ b/lightning-c-bindings/src/lightning/util/events.rs @@ -90,8 +90,6 @@ pub enum Event { }, /// Indicates an outbound payment we made succeeded (ie it made it all the way to its target /// and we got back the payment preimage for it). - /// Note that duplicative PaymentSent Events may be generated - it is your responsibility to - /// deduplicate them by payment_preimage (which MUST be unique)! PaymentSent { /// The preimage to the hash given to ChannelManager::send_payment. /// Note that this serves as a payment receipt, if you wish to have such a thing, you must @@ -100,8 +98,6 @@ pub enum Event { }, /// Indicates an outbound payment we made failed. Probably some intermediary node dropped /// something. You may wish to retry with a different route. - /// Note that duplicative PaymentFailed Events may be generated - it is your responsibility to - /// deduplicate them by payment_hash (which MUST be unique)! PaymentFailed { /// The hash which was given to ChannelManager::send_payment. payment_hash: crate::c_types::ThirtyTwoBytes, @@ -119,7 +115,8 @@ pub enum Event { /// now + 5*time_forwardable). time_forwardable: u64, }, - /// Used to indicate that an output was generated on-chain which you should know how to spend. + /// Used to indicate that an output which you should know how to spend was confirmed on chain + /// and is now spendable. /// Such an output will *not* ever be spent by rust-lightning, and are not at risk of your /// counterparty spending them due to some kind of timeout. Thus, you need to store them /// somewhere and spend them when you create on-chain transactions. @@ -148,14 +145,14 @@ impl Event { Event::PaymentReceived {ref payment_hash, ref payment_preimage, ref payment_secret, ref amt, ref user_payment_id, } => { let mut payment_hash_nonref = (*payment_hash).clone(); let mut payment_preimage_nonref = (*payment_preimage).clone(); - let mut local_payment_preimage_nonref = if payment_preimage_nonref.data == [0; 32] { None } else { Some( { ::lightning::ln::channelmanager::PaymentPreimage(payment_preimage_nonref.data) }) }; + let mut local_payment_preimage_nonref = if payment_preimage_nonref.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentPreimage(payment_preimage_nonref.data) }) }; let mut payment_secret_nonref = (*payment_secret).clone(); let mut amt_nonref = (*amt).clone(); let mut user_payment_id_nonref = (*user_payment_id).clone(); nativeEvent::PaymentReceived { - payment_hash: ::lightning::ln::channelmanager::PaymentHash(payment_hash_nonref.data), + payment_hash: ::lightning::ln::PaymentHash(payment_hash_nonref.data), payment_preimage: local_payment_preimage_nonref, - payment_secret: ::lightning::ln::channelmanager::PaymentSecret(payment_secret_nonref.data), + payment_secret: ::lightning::ln::PaymentSecret(payment_secret_nonref.data), amt: amt_nonref, user_payment_id: user_payment_id_nonref, } @@ -163,14 +160,14 @@ impl Event { Event::PaymentSent {ref payment_preimage, } => { let mut payment_preimage_nonref = (*payment_preimage).clone(); nativeEvent::PaymentSent { - payment_preimage: ::lightning::ln::channelmanager::PaymentPreimage(payment_preimage_nonref.data), + payment_preimage: ::lightning::ln::PaymentPreimage(payment_preimage_nonref.data), } }, Event::PaymentFailed {ref payment_hash, ref rejected_by_dest, } => { let mut payment_hash_nonref = (*payment_hash).clone(); let mut rejected_by_dest_nonref = (*rejected_by_dest).clone(); nativeEvent::PaymentFailed { - payment_hash: ::lightning::ln::channelmanager::PaymentHash(payment_hash_nonref.data), + payment_hash: ::lightning::ln::PaymentHash(payment_hash_nonref.data), rejected_by_dest: rejected_by_dest_nonref, } }, @@ -201,23 +198,23 @@ impl Event { } }, Event::PaymentReceived {mut payment_hash, mut payment_preimage, mut payment_secret, mut amt, mut user_payment_id, } => { - let mut local_payment_preimage = if payment_preimage.data == [0; 32] { None } else { Some( { ::lightning::ln::channelmanager::PaymentPreimage(payment_preimage.data) }) }; + let mut local_payment_preimage = if payment_preimage.data == [0; 32] { None } else { Some( { ::lightning::ln::PaymentPreimage(payment_preimage.data) }) }; nativeEvent::PaymentReceived { - payment_hash: ::lightning::ln::channelmanager::PaymentHash(payment_hash.data), + payment_hash: ::lightning::ln::PaymentHash(payment_hash.data), payment_preimage: local_payment_preimage, - payment_secret: ::lightning::ln::channelmanager::PaymentSecret(payment_secret.data), + payment_secret: ::lightning::ln::PaymentSecret(payment_secret.data), amt: amt, user_payment_id: user_payment_id, } }, Event::PaymentSent {mut payment_preimage, } => { nativeEvent::PaymentSent { - payment_preimage: ::lightning::ln::channelmanager::PaymentPreimage(payment_preimage.data), + payment_preimage: ::lightning::ln::PaymentPreimage(payment_preimage.data), } }, Event::PaymentFailed {mut payment_hash, mut rejected_by_dest, } => { nativeEvent::PaymentFailed { - payment_hash: ::lightning::ln::channelmanager::PaymentHash(payment_hash.data), + payment_hash: ::lightning::ln::PaymentHash(payment_hash.data), rejected_by_dest: rejected_by_dest, } }, @@ -463,6 +460,15 @@ pub enum MessageSendEvent { /// The channel_update which should be sent. msg: crate::lightning::ln::msgs::ChannelUpdate, }, + /// Used to indicate that a channel_update should be sent to a single peer. + /// In contrast to [`Self::BroadcastChannelUpdate`], this is used when the channel is a + /// private channel and we shouldn't be informing all of our peers of channel parameters. + SendChannelUpdate { + /// The node_id of the node which should receive this message + node_id: crate::c_types::PublicKey, + /// The channel_update which should be sent. + msg: crate::lightning::ln::msgs::ChannelUpdate, + }, /// Broadcast an error downstream to be handled HandleError { /// The node_id of the node which should receive this message @@ -613,6 +619,14 @@ impl MessageSendEvent { msg: *unsafe { Box::from_raw(msg_nonref.take_inner()) }, } }, + MessageSendEvent::SendChannelUpdate {ref node_id, ref msg, } => { + let mut node_id_nonref = (*node_id).clone(); + let mut msg_nonref = (*msg).clone(); + nativeMessageSendEvent::SendChannelUpdate { + node_id: node_id_nonref.into_rust(), + msg: *unsafe { Box::from_raw(msg_nonref.take_inner()) }, + } + }, MessageSendEvent::HandleError {ref node_id, ref action, } => { let mut node_id_nonref = (*node_id).clone(); let mut action_nonref = (*action).clone(); @@ -738,6 +752,12 @@ impl MessageSendEvent { msg: *unsafe { Box::from_raw(msg.take_inner()) }, } }, + MessageSendEvent::SendChannelUpdate {mut node_id, mut msg, } => { + nativeMessageSendEvent::SendChannelUpdate { + node_id: node_id.into_rust(), + msg: *unsafe { Box::from_raw(msg.take_inner()) }, + } + }, MessageSendEvent::HandleError {mut node_id, mut action, } => { nativeMessageSendEvent::HandleError { node_id: node_id.into_rust(), @@ -880,6 +900,14 @@ impl MessageSendEvent { msg: crate::lightning::ln::msgs::ChannelUpdate { inner: Box::into_raw(Box::new(msg_nonref)), is_owned: true }, } }, + nativeMessageSendEvent::SendChannelUpdate {ref node_id, ref msg, } => { + let mut node_id_nonref = (*node_id).clone(); + let mut msg_nonref = (*msg).clone(); + MessageSendEvent::SendChannelUpdate { + node_id: crate::c_types::PublicKey::from_rust(&node_id_nonref), + msg: crate::lightning::ln::msgs::ChannelUpdate { inner: Box::into_raw(Box::new(msg_nonref)), is_owned: true }, + } + }, nativeMessageSendEvent::HandleError {ref node_id, ref action, } => { let mut node_id_nonref = (*node_id).clone(); let mut action_nonref = (*action).clone(); @@ -1005,6 +1033,12 @@ impl MessageSendEvent { msg: crate::lightning::ln::msgs::ChannelUpdate { inner: Box::into_raw(Box::new(msg)), is_owned: true }, } }, + nativeMessageSendEvent::SendChannelUpdate {mut node_id, mut msg, } => { + MessageSendEvent::SendChannelUpdate { + node_id: crate::c_types::PublicKey::from_rust(&node_id), + msg: crate::lightning::ln::msgs::ChannelUpdate { inner: Box::into_raw(Box::new(msg)), is_owned: true }, + } + }, nativeMessageSendEvent::HandleError {mut node_id, mut action, } => { MessageSendEvent::HandleError { node_id: crate::c_types::PublicKey::from_rust(&node_id), @@ -1059,6 +1093,8 @@ pub struct MessageSendEventsProvider { /// 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, } +unsafe impl Send for MessageSendEventsProvider {} +unsafe impl Sync for MessageSendEventsProvider {} use lightning::util::events::MessageSendEventsProvider as rustMessageSendEventsProvider; impl rustMessageSendEventsProvider for MessageSendEventsProvider { @@ -1087,33 +1123,86 @@ impl Drop for MessageSendEventsProvider { } } } -/// A trait indicating an object may generate events +/// A trait indicating an object may generate events. +/// +/// Events are processed by passing an [`EventHandler`] to [`process_pending_events`]. +/// +/// # Requirements +/// +/// See [`process_pending_events`] for requirements around event processing. +/// +/// When using this trait, [`process_pending_events`] will call [`handle_event`] for each pending +/// event since the last invocation. The handler must either act upon the event immediately +/// or preserve it for later handling. +/// +/// Note, handlers may call back into the provider and thus deadlocking must be avoided. Be sure to +/// consult the provider's documentation on the implication of processing events and how a handler +/// may safely use the provider (e.g., see [`ChannelManager::process_pending_events`] and +/// [`ChainMonitor::process_pending_events`]). +/// +/// (C-not implementable) As there is likely no reason for a user to implement this trait on their +/// own type(s). +/// +/// [`process_pending_events`]: Self::process_pending_events +/// [`handle_event`]: EventHandler::handle_event +/// [`ChannelManager::process_pending_events`]: crate::ln::channelmanager::ChannelManager#method.process_pending_events +/// [`ChainMonitor::process_pending_events`]: crate::chain::chainmonitor::ChainMonitor#method.process_pending_events #[repr(C)] pub struct EventsProvider { /// 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, - /// Gets the list of pending events which were generated by previous actions, clearing the list - /// in the process. - #[must_use] - pub get_and_clear_pending_events: extern "C" fn (this_arg: *const c_void) -> crate::c_types::derived::CVec_EventZ, + /// Processes any events generated since the last call using the given event handler. + /// + /// Subsequent calls must only process new events. However, handlers must be capable of handling + /// duplicate events across process restarts. This may occur if the provider was recovered from + /// an old state (i.e., it hadn't been successfully persisted after processing pending events). + pub process_pending_events: extern "C" fn (this_arg: *const c_void, handler: crate::lightning::util::events::EventHandler), /// 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, } +unsafe impl Send for EventsProvider {} +unsafe impl Sync for EventsProvider {} use lightning::util::events::EventsProvider as rustEventsProvider; -impl rustEventsProvider for EventsProvider { - fn get_and_clear_pending_events(&self) -> Vec { - let mut ret = (self.get_and_clear_pending_events)(self.this_arg); - let mut local_ret = Vec::new(); for mut item in ret.into_rust().drain(..) { local_ret.push( { item.into_native() }); }; - local_ret +/// Calls the free function if one is set +#[no_mangle] +pub extern "C" fn EventsProvider_free(this_ptr: EventsProvider) { } +impl Drop for EventsProvider { + fn drop(&mut self) { + if let Some(f) = self.free { + f(self.this_arg); + } + } +} +/// A trait implemented for objects handling events from [`EventsProvider`]. +#[repr(C)] +pub struct EventHandler { + /// 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, + /// Handles the given [`Event`]. + /// + /// See [`EventsProvider`] for details that must be considered when implementing this method. + pub handle_event: extern "C" fn (this_arg: *const c_void, event: crate::lightning::util::events::Event), + /// 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, +} +unsafe impl Send for EventHandler {} +unsafe impl Sync for EventHandler {} + +use lightning::util::events::EventHandler as rustEventHandler; +impl rustEventHandler for EventHandler { + fn handle_event(&self, mut event: lightning::util::events::Event) { + (self.handle_event)(self.this_arg, crate::lightning::util::events::Event::native_into(event)) } } // We're essentially a pointer already, or at least a set of pointers, so allow us to be used // directly as a Deref trait in higher-level structs: -impl std::ops::Deref for EventsProvider { +impl std::ops::Deref for EventHandler { type Target = Self; fn deref(&self) -> &Self { self @@ -1121,8 +1210,8 @@ impl std::ops::Deref for EventsProvider { } /// Calls the free function if one is set #[no_mangle] -pub extern "C" fn EventsProvider_free(this_ptr: EventsProvider) { } -impl Drop for EventsProvider { +pub extern "C" fn EventHandler_free(this_ptr: EventHandler) { } +impl Drop for EventHandler { fn drop(&mut self) { if let Some(f) = self.free { f(self.this_arg);