X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning-c-bindings%2Fsrc%2Fchain%2Fkeysinterface.rs;h=c5b0324f6995f7a4e542f5082c3787dc30d1cb00;hb=a132c4d7f8648278537854ae08a83d704853ed42;hp=abd779693d19fc365f56246acb084f6639c3fbcd;hpb=1495575b517c90da925698da14f627bf0d5b313f;p=ldk-c-bindings diff --git a/lightning-c-bindings/src/chain/keysinterface.rs b/lightning-c-bindings/src/chain/keysinterface.rs index abd7796..c5b0324 100644 --- a/lightning-c-bindings/src/chain/keysinterface.rs +++ b/lightning-c-bindings/src/chain/keysinterface.rs @@ -15,9 +15,15 @@ type nativeDelayedPaymentOutputDescriptor = nativeDelayedPaymentOutputDescriptor #[must_use] #[repr(C)] pub struct DelayedPaymentOutputDescriptor { + /// 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 nativeDelayedPaymentOutputDescriptor, + /// 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, } @@ -28,8 +34,9 @@ impl Drop for DelayedPaymentOutputDescriptor { } } } +/// Frees any resources used by the DelayedPaymentOutputDescriptor, if is_owned is set and inner is non-NULL. #[no_mangle] -pub extern "C" fn DelayedPaymentOutputDescriptor_free(this_ptr: DelayedPaymentOutputDescriptor) { } +pub extern "C" fn DelayedPaymentOutputDescriptor_free(this_obj: DelayedPaymentOutputDescriptor) { } #[allow(unused)] /// Used only if an object of this type is returned as a trait impl by a method extern "C" fn DelayedPaymentOutputDescriptor_free_void(this_ptr: *mut c_void) { @@ -124,6 +131,7 @@ pub extern "C" fn DelayedPaymentOutputDescriptor_get_channel_value_satoshis(this pub extern "C" fn DelayedPaymentOutputDescriptor_set_channel_value_satoshis(this_ptr: &mut DelayedPaymentOutputDescriptor, mut val: u64) { unsafe { &mut *this_ptr.inner }.channel_value_satoshis = val; } +/// Constructs a new DelayedPaymentOutputDescriptor given each field #[must_use] #[no_mangle] pub extern "C" fn DelayedPaymentOutputDescriptor_new(mut outpoint_arg: crate::chain::transaction::OutPoint, mut per_commitment_point_arg: crate::c_types::PublicKey, mut to_self_delay_arg: u16, mut output_arg: crate::c_types::TxOut, mut revocation_pubkey_arg: crate::c_types::PublicKey, mut channel_keys_id_arg: crate::c_types::ThirtyTwoBytes, mut channel_value_satoshis_arg: u64) -> DelayedPaymentOutputDescriptor { @@ -152,6 +160,7 @@ pub(crate) extern "C" fn DelayedPaymentOutputDescriptor_clone_void(this_ptr: *co Box::into_raw(Box::new(unsafe { (*(this_ptr as *mut nativeDelayedPaymentOutputDescriptor)).clone() })) as *mut c_void } #[no_mangle] +/// Creates a copy of the DelayedPaymentOutputDescriptor pub extern "C" fn DelayedPaymentOutputDescriptor_clone(orig: &DelayedPaymentOutputDescriptor) -> DelayedPaymentOutputDescriptor { orig.clone() } @@ -164,9 +173,15 @@ type nativeStaticPaymentOutputDescriptor = nativeStaticPaymentOutputDescriptorIm #[must_use] #[repr(C)] pub struct StaticPaymentOutputDescriptor { + /// 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 nativeStaticPaymentOutputDescriptor, + /// 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, } @@ -177,8 +192,9 @@ impl Drop for StaticPaymentOutputDescriptor { } } } +/// Frees any resources used by the StaticPaymentOutputDescriptor, if is_owned is set and inner is non-NULL. #[no_mangle] -pub extern "C" fn StaticPaymentOutputDescriptor_free(this_ptr: StaticPaymentOutputDescriptor) { } +pub extern "C" fn StaticPaymentOutputDescriptor_free(this_obj: StaticPaymentOutputDescriptor) { } #[allow(unused)] /// Used only if an object of this type is returned as a trait impl by a method extern "C" fn StaticPaymentOutputDescriptor_free_void(this_ptr: *mut c_void) { @@ -236,6 +252,7 @@ pub extern "C" fn StaticPaymentOutputDescriptor_get_channel_value_satoshis(this_ pub extern "C" fn StaticPaymentOutputDescriptor_set_channel_value_satoshis(this_ptr: &mut StaticPaymentOutputDescriptor, mut val: u64) { unsafe { &mut *this_ptr.inner }.channel_value_satoshis = val; } +/// Constructs a new StaticPaymentOutputDescriptor given each field #[must_use] #[no_mangle] pub extern "C" fn StaticPaymentOutputDescriptor_new(mut outpoint_arg: crate::chain::transaction::OutPoint, mut output_arg: crate::c_types::TxOut, mut channel_keys_id_arg: crate::c_types::ThirtyTwoBytes, mut channel_value_satoshis_arg: u64) -> StaticPaymentOutputDescriptor { @@ -261,6 +278,7 @@ pub(crate) extern "C" fn StaticPaymentOutputDescriptor_clone_void(this_ptr: *con Box::into_raw(Box::new(unsafe { (*(this_ptr as *mut nativeStaticPaymentOutputDescriptor)).clone() })) as *mut c_void } #[no_mangle] +/// Creates a copy of the StaticPaymentOutputDescriptor pub extern "C" fn StaticPaymentOutputDescriptor_clone(orig: &StaticPaymentOutputDescriptor) -> StaticPaymentOutputDescriptor { orig.clone() } @@ -279,7 +297,9 @@ pub enum SpendableOutputDescriptor { /// These may include outputs from a transaction punishing our counterparty or claiming an HTLC /// on-chain using the payment preimage or after it has timed out. StaticOutput { + /// The outpoint which is spendable outpoint: crate::chain::transaction::OutPoint, + /// The output which is referenced by the given outpoint. output: crate::c_types::TxOut, }, /// An output to a P2WSH script which can be spent with a single signature after a CSV delay. @@ -415,17 +435,21 @@ impl SpendableOutputDescriptor { } } } +/// Frees any resources used by the SpendableOutputDescriptor #[no_mangle] pub extern "C" fn SpendableOutputDescriptor_free(this_ptr: SpendableOutputDescriptor) { } +/// Creates a copy of the SpendableOutputDescriptor #[no_mangle] pub extern "C" fn SpendableOutputDescriptor_clone(orig: &SpendableOutputDescriptor) -> SpendableOutputDescriptor { orig.clone() } #[no_mangle] +/// Serialize the SpendableOutputDescriptor object into a byte array which can be read by SpendableOutputDescriptor_read pub extern "C" fn SpendableOutputDescriptor_write(obj: &SpendableOutputDescriptor) -> crate::c_types::derived::CVec_u8Z { crate::c_types::serialize_obj(&unsafe { &*obj }.to_native()) } #[no_mangle] +/// Read a SpendableOutputDescriptor from a byte array, created by SpendableOutputDescriptor_write pub extern "C" fn SpendableOutputDescriptor_read(ser: crate::c_types::u8slice) -> crate::c_types::derived::CResult_SpendableOutputDescriptorDecodeErrorZ { let res = crate::c_types::deserialize_obj(ser); let mut local_res = match res { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::chain::keysinterface::SpendableOutputDescriptor::native_into(o) }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::ln::msgs::DecodeError { inner: Box::into_raw(Box::new(e)), is_owned: true } }).into() }; @@ -450,6 +474,8 @@ pub extern "C" fn SpendableOutputDescriptor_read(ser: crate::c_types::u8slice) - /// of LN security model, orthogonal of key management issues. #[repr(C)] pub struct Sign { + /// 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 per-commitment point for a specific commitment number /// @@ -559,12 +585,19 @@ pub struct Sign { /// /// Will be called before any signatures are applied. pub ready_channel: extern "C" fn (this_arg: *mut c_void, channel_parameters: &crate::ln::chan_utils::ChannelTransactionParameters), + /// Creates a copy of the object pointed to by this_arg, for a copy of this Sign. + /// Note that the ultimate copy of the Sign 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 Sign. pub clone: Option *mut c_void>, + /// Serialize the object into a byte array pub write: extern "C" fn (this_arg: *const c_void) -> crate::c_types::derived::CVec_u8Z, +/// 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 Sign {} #[no_mangle] +/// Creates a copy of a Sign pub extern "C" fn Sign_clone(orig: &Sign) -> Sign { Sign { this_arg: if let Some(f) = orig.clone { (f)(orig.this_arg) } else { orig.this_arg }, @@ -677,6 +710,8 @@ impl Drop for Sign { /// A trait to describe an object which can get user secrets and key material. #[repr(C)] pub struct KeysInterface { + /// 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, /// Get node secret key (aka node_id or network_key). /// @@ -717,6 +752,8 @@ pub struct KeysInterface { /// you've read all of the provided bytes to ensure no corruption occurred. #[must_use] pub read_chan_signer: extern "C" fn (this_arg: *const c_void, reader: crate::c_types::u8slice) -> crate::c_types::derived::CResult_SignDecodeErrorZ, +/// 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 KeysInterface {} @@ -782,9 +819,15 @@ type nativeInMemorySigner = nativeInMemorySignerImport; #[must_use] #[repr(C)] pub struct InMemorySigner { + /// 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 nativeInMemorySigner, + /// 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, } @@ -795,8 +838,9 @@ impl Drop for InMemorySigner { } } } +/// Frees any resources used by the InMemorySigner, if is_owned is set and inner is non-NULL. #[no_mangle] -pub extern "C" fn InMemorySigner_free(this_ptr: InMemorySigner) { } +pub extern "C" fn InMemorySigner_free(this_obj: InMemorySigner) { } #[allow(unused)] /// Used only if an object of this type is returned as a trait impl by a method extern "C" fn InMemorySigner_free_void(this_ptr: *mut c_void) { @@ -893,6 +937,7 @@ pub(crate) extern "C" fn InMemorySigner_clone_void(this_ptr: *const c_void) -> * Box::into_raw(Box::new(unsafe { (*(this_ptr as *mut nativeInMemorySigner)).clone() })) as *mut c_void } #[no_mangle] +/// Creates a copy of the InMemorySigner pub extern "C" fn InMemorySigner_clone(orig: &InMemorySigner) -> InMemorySigner { orig.clone() } @@ -1001,6 +1046,8 @@ impl From for crate::chain::keysinterface::Sign { ret } } +/// Constructs a new Sign which calls the relevant methods on this_arg. +/// This copies the `inner` pointer in this_arg and thus the returned Sign must be freed before this_arg is #[no_mangle] pub extern "C" fn InMemorySigner_as_Sign(this_arg: &InMemorySigner) -> crate::chain::keysinterface::Sign { crate::chain::keysinterface::Sign { @@ -1093,6 +1140,7 @@ extern "C" fn InMemorySigner_Sign_ready_channel(this_arg: *mut c_void, channel_p } #[no_mangle] +/// Serialize the InMemorySigner object into a byte array which can be read by InMemorySigner_read pub extern "C" fn InMemorySigner_write(obj: &InMemorySigner) -> crate::c_types::derived::CVec_u8Z { crate::c_types::serialize_obj(unsafe { &*unsafe { &*obj }.inner }) } @@ -1101,6 +1149,7 @@ pub(crate) extern "C" fn InMemorySigner_write_void(obj: *const c_void) -> crate: crate::c_types::serialize_obj(unsafe { &*(obj as *const nativeInMemorySigner) }) } #[no_mangle] +/// Read a InMemorySigner from a byte array, created by InMemorySigner_write pub extern "C" fn InMemorySigner_read(ser: crate::c_types::u8slice) -> crate::c_types::derived::CResult_InMemorySignerDecodeErrorZ { let res = crate::c_types::deserialize_obj(ser); let mut local_res = match res { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::chain::keysinterface::InMemorySigner { inner: Box::into_raw(Box::new(o)), is_owned: true } }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::ln::msgs::DecodeError { inner: Box::into_raw(Box::new(e)), is_owned: true } }).into() }; @@ -1120,9 +1169,15 @@ type nativeKeysManager = nativeKeysManagerImport; #[must_use] #[repr(C)] pub struct KeysManager { + /// 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 nativeKeysManager, + /// 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, } @@ -1133,8 +1188,9 @@ impl Drop for KeysManager { } } } +/// Frees any resources used by the KeysManager, if is_owned is set and inner is non-NULL. #[no_mangle] -pub extern "C" fn KeysManager_free(this_ptr: KeysManager) { } +pub extern "C" fn KeysManager_free(this_obj: KeysManager) { } #[allow(unused)] /// Used only if an object of this type is returned as a trait impl by a method extern "C" fn KeysManager_free_void(this_ptr: *mut c_void) { @@ -1219,6 +1275,8 @@ impl From for crate::chain::keysinterface::KeysInterface { ret } } +/// Constructs a new KeysInterface which calls the relevant methods on this_arg. +/// This copies the `inner` pointer in this_arg and thus the returned KeysInterface must be freed before this_arg is #[no_mangle] pub extern "C" fn KeysManager_as_KeysInterface(this_arg: &KeysManager) -> crate::chain::keysinterface::KeysInterface { crate::chain::keysinterface::KeysInterface {