_ Git - ldk-c-bindings/blob - lightning-c-bindings/src/lightning/offers/invoice_request.rs

   1 // This file is Copyright its original authors, visible in version control
   2 // history and in the source files from which this was generated.
   3 //
   4 // This file is licensed under the license available in the LICENSE or LICENSE.md
   5 // file in the root of this repository or, if no such file exists, the same
   6 // license as that which applies to the original source files from which this
   7 // source was automatically generated.
   8
   9 //! Data structures and encoding for `invoice_request` messages.
  10 //!
  11 //! An [`InvoiceRequest`] can be built from a parsed [`Offer`] as an \"offer to be paid\". It is
  12 //! typically constructed by a customer and sent to the merchant who had published the corresponding
  13 //! offer. The recipient of the request responds with an [`Invoice`].
  14 //!
  15 //! For an \"offer for money\" (e.g., refund, ATM withdrawal), where an offer doesn't exist as a
  16 //! precursor, see [`Refund`].
  17 //!
  18 //! [`Invoice`]: crate::offers::invoice::Invoice
  19 //! [`Refund`]: crate::offers::refund::Refund
  20 //!
  21 //! ```
  22 //! extern crate bitcoin;
  23 //! extern crate lightning;
  24 //!
  25 //! use bitcoin::network::constants::Network;
  26 //! use bitcoin::secp256k1::{KeyPair, PublicKey, Secp256k1, SecretKey};
  27 //! use core::convert::Infallible;
  28 //! use lightning::ln::features::OfferFeatures;
  29 //! use lightning::offers::offer::Offer;
  30 //! use lightning::util::ser::Writeable;
  31 //!
  32 //! # fn parse() -> Result<(), lightning::offers::parse::ParseError> {
  33 //! let secp_ctx = Secp256k1::new();
  34 //! let keys = KeyPair::from_secret_key(&secp_ctx, &SecretKey::from_slice(&[42; 32])?);
  35 //! let pubkey = PublicKey::from(keys);
  36 //! let mut buffer = Vec::new();
  37 //!
  38 //! \"lno1qcp4256ypq\"
  39 //!     .parse::<Offer>()?
  40 //!     .request_invoice(vec![42; 64], pubkey)?
  41 //!     .chain(Network::Testnet)?
  42 //!     .amount_msats(1000)?
  43 //!     .quantity(5)?
  44 //!     .payer_note(\"foo\".to_string())
  45 //!     .build()?
  46 //!     .sign::<_, Infallible>(|digest| Ok(secp_ctx.sign_schnorr_no_aux_rand(digest, &keys)))
  47 //!     .expect(\"failed verifying signature\")
  48 //!     .write(&mut buffer)
  49 //!     .unwrap();
  50 //! # Ok(())
  51 //! # }
  52 //! ```
  53
  54 use alloc::str::FromStr;
  55 use core::ffi::c_void;
  56 use core::convert::Infallible;
  57 use bitcoin::hashes::Hash;
  58 use crate::c_types::*;
  59 #[cfg(feature="no-std")]
  60 use alloc::{vec::Vec, boxed::Box};
  61
  62
  63 use lightning::offers::invoice_request::UnsignedInvoiceRequest as nativeUnsignedInvoiceRequestImport;
  64 pub(crate) type nativeUnsignedInvoiceRequest = nativeUnsignedInvoiceRequestImport<'static>;
  65
  66 /// A semantically valid [`InvoiceRequest`] that hasn't been signed.
  67 #[must_use]
  68 #[repr(C)]
  69 pub struct UnsignedInvoiceRequest {
  70         /// A pointer to the opaque Rust object.
  71
  72         /// Nearly everywhere, inner must be non-null, however in places where
  73         /// the Rust equivalent takes an Option, it may be set to null to indicate None.
  74         pub inner: *mut nativeUnsignedInvoiceRequest,
  75         /// Indicates that this is the only struct which contains the same pointer.
  76
  77         /// Rust functions which take ownership of an object provided via an argument require
  78         /// this to be true and invalidate the object pointed to by inner.
  79         pub is_owned: bool,
  80 }
  81
  82 impl Drop for UnsignedInvoiceRequest {
  83         fn drop(&mut self) {
  84                 if self.is_owned && !<*mut nativeUnsignedInvoiceRequest>::is_null(self.inner) {
  85                         let _ = unsafe { Box::from_raw(ObjOps::untweak_ptr(self.inner)) };
  86                 }
  87         }
  88 }
  89 /// Frees any resources used by the UnsignedInvoiceRequest, if is_owned is set and inner is non-NULL.
  90 #[no_mangle]
  91 pub extern "C" fn UnsignedInvoiceRequest_free(this_obj: UnsignedInvoiceRequest) { }
  92 #[allow(unused)]
  93 /// Used only if an object of this type is returned as a trait impl by a method
  94 pub(crate) extern "C" fn UnsignedInvoiceRequest_free_void(this_ptr: *mut c_void) {
  95         let _ = unsafe { Box::from_raw(this_ptr as *mut nativeUnsignedInvoiceRequest) };
  96 }
  97 #[allow(unused)]
  98 impl UnsignedInvoiceRequest {
  99         pub(crate) fn get_native_ref(&self) -> &'static nativeUnsignedInvoiceRequest {
 100                 unsafe { &*ObjOps::untweak_ptr(self.inner) }
 101         }
 102         pub(crate) fn get_native_mut_ref(&self) -> &'static mut nativeUnsignedInvoiceRequest {
 103                 unsafe { &mut *ObjOps::untweak_ptr(self.inner) }
 104         }
 105         /// When moving out of the pointer, we have to ensure we aren't a reference, this makes that easy
 106         pub(crate) fn take_inner(mut self) -> *mut nativeUnsignedInvoiceRequest {
 107                 assert!(self.is_owned);
 108                 let ret = ObjOps::untweak_ptr(self.inner);
 109                 self.inner = core::ptr::null_mut();
 110                 ret
 111         }
 112 }
 113
 114 use lightning::offers::invoice_request::InvoiceRequest as nativeInvoiceRequestImport;
 115 pub(crate) type nativeInvoiceRequest = nativeInvoiceRequestImport;
 116
 117 /// An `InvoiceRequest` is a request for an [`Invoice`] formulated from an [`Offer`].
 118 ///
 119 /// An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request
 120 /// specifies these such that its recipient can send an invoice for payment.
 121 ///
 122 /// [`Invoice`]: crate::offers::invoice::Invoice
 123 /// [`Offer`]: crate::offers::offer::Offer
 124 #[must_use]
 125 #[repr(C)]
 126 pub struct InvoiceRequest {
 127         /// A pointer to the opaque Rust object.
 128
 129         /// Nearly everywhere, inner must be non-null, however in places where
 130         /// the Rust equivalent takes an Option, it may be set to null to indicate None.
 131         pub inner: *mut nativeInvoiceRequest,
 132         /// Indicates that this is the only struct which contains the same pointer.
 133
 134         /// Rust functions which take ownership of an object provided via an argument require
 135         /// this to be true and invalidate the object pointed to by inner.
 136         pub is_owned: bool,
 137 }
 138
 139 impl Drop for InvoiceRequest {
 140         fn drop(&mut self) {
 141                 if self.is_owned && !<*mut nativeInvoiceRequest>::is_null(self.inner) {
 142                         let _ = unsafe { Box::from_raw(ObjOps::untweak_ptr(self.inner)) };
 143                 }
 144         }
 145 }
 146 /// Frees any resources used by the InvoiceRequest, if is_owned is set and inner is non-NULL.
 147 #[no_mangle]
 148 pub extern "C" fn InvoiceRequest_free(this_obj: InvoiceRequest) { }
 149 #[allow(unused)]
 150 /// Used only if an object of this type is returned as a trait impl by a method
 151 pub(crate) extern "C" fn InvoiceRequest_free_void(this_ptr: *mut c_void) {
 152         let _ = unsafe { Box::from_raw(this_ptr as *mut nativeInvoiceRequest) };
 153 }
 154 #[allow(unused)]
 155 impl InvoiceRequest {
 156         pub(crate) fn get_native_ref(&self) -> &'static nativeInvoiceRequest {
 157                 unsafe { &*ObjOps::untweak_ptr(self.inner) }
 158         }
 159         pub(crate) fn get_native_mut_ref(&self) -> &'static mut nativeInvoiceRequest {
 160                 unsafe { &mut *ObjOps::untweak_ptr(self.inner) }
 161         }
 162         /// When moving out of the pointer, we have to ensure we aren't a reference, this makes that easy
 163         pub(crate) fn take_inner(mut self) -> *mut nativeInvoiceRequest {
 164                 assert!(self.is_owned);
 165                 let ret = ObjOps::untweak_ptr(self.inner);
 166                 self.inner = core::ptr::null_mut();
 167                 ret
 168         }
 169 }
 170 impl Clone for InvoiceRequest {
 171         fn clone(&self) -> Self {
 172                 Self {
 173                         inner: if <*mut nativeInvoiceRequest>::is_null(self.inner) { core::ptr::null_mut() } else {
 174                                 ObjOps::heap_alloc(unsafe { &*ObjOps::untweak_ptr(self.inner) }.clone()) },
 175                         is_owned: true,
 176                 }
 177         }
 178 }
 179 #[allow(unused)]
 180 /// Used only if an object of this type is returned as a trait impl by a method
 181 pub(crate) extern "C" fn InvoiceRequest_clone_void(this_ptr: *const c_void) -> *mut c_void {
 182         Box::into_raw(Box::new(unsafe { (*(this_ptr as *mut nativeInvoiceRequest)).clone() })) as *mut c_void
 183 }
 184 #[no_mangle]
 185 /// Creates a copy of the InvoiceRequest
 186 pub extern "C" fn InvoiceRequest_clone(orig: &InvoiceRequest) -> InvoiceRequest {
 187         orig.clone()
 188 }
 189 /// An unpredictable series of bytes, typically containing information about the derivation of
 190 /// [`payer_id`].
 191 ///
 192 /// [`payer_id`]: Self::payer_id
 193 #[must_use]
 194 #[no_mangle]
 195 pub extern "C" fn InvoiceRequest_metadata(this_arg: &crate::lightning::offers::invoice_request::InvoiceRequest) -> crate::c_types::u8slice {
 196         let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.metadata();
 197         let mut local_ret = crate::c_types::u8slice::from_slice(ret);
 198         local_ret
 199 }
 200
 201 /// A chain from [`Offer::chains`] that the offer is valid for.
 202 #[must_use]
 203 #[no_mangle]
 204 pub extern "C" fn InvoiceRequest_chain(this_arg: &crate::lightning::offers::invoice_request::InvoiceRequest) -> crate::c_types::ThirtyTwoBytes {
 205         let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.chain();
 206         crate::c_types::ThirtyTwoBytes { data: ret.to_bytes() }
 207 }
 208
 209 /// The amount to pay in msats (i.e., the minimum lightning-payable unit for [`chain`]), which
 210 /// must be greater than or equal to [`Offer::amount`], converted if necessary.
 211 ///
 212 /// [`chain`]: Self::chain
 213 #[must_use]
 214 #[no_mangle]
 215 pub extern "C" fn InvoiceRequest_amount_msats(this_arg: &crate::lightning::offers::invoice_request::InvoiceRequest) -> crate::c_types::derived::COption_u64Z {
 216         let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.amount_msats();
 217         let mut local_ret = if ret.is_none() { crate::c_types::derived::COption_u64Z::None } else { crate::c_types::derived::COption_u64Z::Some( { ret.unwrap() }) };
 218         local_ret
 219 }
 220
 221 /// Features pertaining to requesting an invoice.
 222 #[must_use]
 223 #[no_mangle]
 224 pub extern "C" fn InvoiceRequest_features(this_arg: &crate::lightning::offers::invoice_request::InvoiceRequest) -> crate::lightning::ln::features::InvoiceRequestFeatures {
 225         let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.features();
 226         crate::lightning::ln::features::InvoiceRequestFeatures { inner: unsafe { ObjOps::nonnull_ptr_to_inner((ret as *const lightning::ln::features::InvoiceRequestFeatures<>) as *mut _) }, is_owned: false }
 227 }
 228
 229 /// The quantity of the offer's item conforming to [`Offer::is_valid_quantity`].
 230 #[must_use]
 231 #[no_mangle]
 232 pub extern "C" fn InvoiceRequest_quantity(this_arg: &crate::lightning::offers::invoice_request::InvoiceRequest) -> crate::c_types::derived::COption_u64Z {
 233         let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.quantity();
 234         let mut local_ret = if ret.is_none() { crate::c_types::derived::COption_u64Z::None } else { crate::c_types::derived::COption_u64Z::Some( { ret.unwrap() }) };
 235         local_ret
 236 }
 237
 238 /// A possibly transient pubkey used to sign the invoice request.
 239 #[must_use]
 240 #[no_mangle]
 241 pub extern "C" fn InvoiceRequest_payer_id(this_arg: &crate::lightning::offers::invoice_request::InvoiceRequest) -> crate::c_types::PublicKey {
 242         let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.payer_id();
 243         crate::c_types::PublicKey::from_rust(&ret)
 244 }
 245
 246 /// A payer-provided note which will be seen by the recipient and reflected back in the invoice
 247 /// response.
 248 ///
 249 /// Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None
 250 #[must_use]
 251 #[no_mangle]
 252 pub extern "C" fn InvoiceRequest_payer_note(this_arg: &crate::lightning::offers::invoice_request::InvoiceRequest) -> crate::lightning::util::string::PrintableString {
 253         let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.payer_note();
 254         let mut local_ret = crate::lightning::util::string::PrintableString { inner: if ret.is_none() { core::ptr::null_mut() } else {  { ObjOps::heap_alloc((ret.unwrap())) } }, is_owned: true };
 255         local_ret
 256 }
 257
 258 #[no_mangle]
 259 /// Serialize the InvoiceRequest object into a byte array which can be read by InvoiceRequest_read
 260 pub extern "C" fn InvoiceRequest_write(obj: &crate::lightning::offers::invoice_request::InvoiceRequest) -> crate::c_types::derived::CVec_u8Z {
 261         crate::c_types::serialize_obj(unsafe { &*obj }.get_native_ref())
 262 }
 263 #[no_mangle]
 264 pub(crate) extern "C" fn InvoiceRequest_write_void(obj: *const c_void) -> crate::c_types::derived::CVec_u8Z {
 265         crate::c_types::serialize_obj(unsafe { &*(obj as *const nativeInvoiceRequest) })
 266 }