objc2_link_presentation/generated/LPMetadataProvider.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5use objc2::__framework_prelude::*;
6use objc2_foundation::*;
7
8use crate::*;
9
10extern_class!(
11 /// An object that retrieves metadata for a URL.
12 ///
13 /// Use ``LPMetadataProvider`` to fetch metadata for a URL, including its title,
14 /// icon, and image or video links. All properties on the resulting
15 /// ``LPLinkMetadata`` instance are optional.
16 ///
17 /// - Note: To enable macOS clients to fetch metadata for remote URLs, add the
18 /// <doc
19 /// ://com.apple.documentation/documentation/bundleresources/entitlements/com_apple_security_network_client>
20 /// entitlement.
21 ///
22 /// ## Fetch link metadata from a URL
23 ///
24 /// For each metadata request, create an instance of ``LPMetadataProvider`` and
25 /// call ``LPMetadataProvider/startFetchingMetadataForURL:completionHandler:``.
26 ///
27 /// In the completion handler, check the error. If your user doesn’t have a
28 /// network connection, the fetch can fail. If the server doesn’t respond or is
29 /// too slow, the fetch can time out. Alternatively, the app may cancel the
30 /// request, or an unknown error may occur.
31 ///
32 /// Otherwise, use the metadata however you want, for example, to populate the
33 /// title for a table view cell.
34 ///
35 /// ```swift
36 /// let metadataProvider = LPMetadataProvider()
37 /// let url = URL(string: "https://www.apple.com/ipad")!
38 ///
39 /// metadataProvider.startFetchingMetadata(for: url) { metadata, error in
40 /// if error != nil {
41 /// // The fetch failed; handle the error.
42 /// return
43 /// }
44 ///
45 /// // Make use of fetched metadata.
46 /// }
47 /// ```
48 ///
49 /// For more information about handling errors, see
50 /// ``LinkPresentation/LPError``.
51 ///
52 /// See also [Apple's documentation](https://developer.apple.com/documentation/linkpresentation/lpmetadataprovider?language=objc)
53 #[unsafe(super(NSObject))]
54 #[derive(Debug, PartialEq, Eq, Hash)]
55 pub struct LPMetadataProvider;
56);
57
58unsafe impl NSObjectProtocol for LPMetadataProvider {}
59
60impl LPMetadataProvider {
61 extern_methods!(
62 #[cfg(all(feature = "LPLinkMetadata", feature = "block2"))]
63 /// Fetches metadata for the given URL.
64 ///
65 /// Call this method once per ``LPMetadataProvider`` instance. If you attempt to
66 /// fetch metadata multiple times on a single ``LPMetadataProvider`` instance,
67 /// it throws an error.
68 ///
69 /// The completion handler executes on a background queue. Dispatch any
70 /// necessary UI updates back to the main queue. When the completion handler
71 /// returns, it deletes any file URLs returned in the resulting
72 /// ``LPLinkMetadata``.
73 ///
74 /// > Concurrency Note: You can call this method from synchronous code using a completion handler,
75 /// > as shown on this page, or you can call it as an asynchronous method that has the
76 /// > following declaration:
77 /// >
78 /// > ```swift
79 /// > func startFetchingMetadata(for url: URL) async throws -> LPLinkMetadata
80 /// > ```
81 /// >
82 /// > For information about concurrency and asynchronous code in Swift, see
83 /// <doc
84 /// ://com.apple.documentation/documentation/swift/calling-objective-c-apis-asynchronously>.
85 #[unsafe(method(startFetchingMetadataForURL:completionHandler:))]
86 #[unsafe(method_family = none)]
87 pub unsafe fn startFetchingMetadataForURL_completionHandler(
88 &self,
89 url: &NSURL,
90 completion_handler: &block2::Block<dyn Fn(*mut LPLinkMetadata, *mut NSError)>,
91 );
92
93 #[cfg(all(feature = "LPLinkMetadata", feature = "block2"))]
94 /// Fetches metadata for the given ``NSURLRequest``.
95 ///
96 /// Call this method once per ``LPMetadataProvider`` instance. If you attempt to
97 /// fetch metadata multiple times on a single ``LPMetadataProvider`` instance,
98 /// it throws an error.
99 ///
100 /// The completion handler executes on a background queue. Dispatch any
101 /// necessary UI updates back to the main queue. When the completion handler
102 /// returns, it deletes any file URLs returned in the resulting
103 /// ``LPLinkMetadata``.
104 ///
105 /// > Concurrency Note: You can call this method from synchronous code using a completion handler,
106 /// > as shown on this page, or you can call it as an asynchronous method that has the
107 /// > following declaration:
108 /// >
109 /// > ```swift
110 /// > func startFetchingMetadata(for request: URLRequest) async throws -> LPLinkMetadata
111 /// > ```
112 /// >
113 /// > For information about concurrency and asynchronous code in Swift, see
114 /// <doc
115 /// ://com.apple.documentation/documentation/swift/calling-objective-c-apis-asynchronously>.
116 #[unsafe(method(startFetchingMetadataForRequest:completionHandler:))]
117 #[unsafe(method_family = none)]
118 pub unsafe fn startFetchingMetadataForRequest_completionHandler(
119 &self,
120 request: &NSURLRequest,
121 completion_handler: &block2::Block<dyn Fn(*mut LPLinkMetadata, *mut NSError)>,
122 );
123
124 /// Cancels a metadata request.
125 ///
126 /// This method invokes the completion handler with the error code
127 /// ``LPErrorCode/LPErrorMetadataFetchCancelled`` if the request hasn’t already
128 /// completed.
129 #[unsafe(method(cancel))]
130 #[unsafe(method_family = none)]
131 pub unsafe fn cancel(&self);
132
133 /// A Boolean value indicating whether to download subresources specified by the
134 /// metadata.
135 ///
136 /// Subresources include the icon, image, or video. When set to `false`, the
137 /// returned ``LPLinkMetadata`` object consists only of metadata retrieved from
138 /// the main resource identified by the url passed to
139 /// ``LPMetadataProvider/startFetchingMetadataForURL:completionHandler:``.
140 ///
141 /// The default value is `true`.
142 #[unsafe(method(shouldFetchSubresources))]
143 #[unsafe(method_family = none)]
144 pub unsafe fn shouldFetchSubresources(&self) -> bool;
145
146 /// Setter for [`shouldFetchSubresources`][Self::shouldFetchSubresources].
147 #[unsafe(method(setShouldFetchSubresources:))]
148 #[unsafe(method_family = none)]
149 pub unsafe fn setShouldFetchSubresources(&self, should_fetch_subresources: bool);
150
151 /// The time interval after which the request automatically fails if it hasn’t
152 /// already completed.
153 ///
154 /// The default timeout interval is 30 seconds. If a metadata fetch takes longer
155 /// than the timeout interval, the completion handler is called with the error
156 /// code ``LPErrorCode/LPErrorMetadataFetchTimedOut``.
157 #[unsafe(method(timeout))]
158 #[unsafe(method_family = none)]
159 pub unsafe fn timeout(&self) -> NSTimeInterval;
160
161 /// Setter for [`timeout`][Self::timeout].
162 #[unsafe(method(setTimeout:))]
163 #[unsafe(method_family = none)]
164 pub unsafe fn setTimeout(&self, timeout: NSTimeInterval);
165 );
166}
167
168/// Methods declared on superclass `NSObject`.
169impl LPMetadataProvider {
170 extern_methods!(
171 #[unsafe(method(init))]
172 #[unsafe(method_family = init)]
173 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
174
175 #[unsafe(method(new))]
176 #[unsafe(method_family = new)]
177 pub unsafe fn new() -> Retained<Self>;
178 );
179}