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
58extern_conformance!(
59 unsafe impl NSObjectProtocol for LPMetadataProvider {}
60);
61
62impl LPMetadataProvider {
63 extern_methods!(
64 #[cfg(all(feature = "LPLinkMetadata", feature = "block2"))]
65 /// Fetches metadata for the given URL.
66 ///
67 /// Call this method once per ``LPMetadataProvider`` instance. If you attempt to
68 /// fetch metadata multiple times on a single ``LPMetadataProvider`` instance,
69 /// it throws an error.
70 ///
71 /// The completion handler executes on a background queue. Dispatch any
72 /// necessary UI updates back to the main queue. When the completion handler
73 /// returns, it deletes any file URLs returned in the resulting
74 /// ``LPLinkMetadata``.
75 ///
76 /// > Concurrency Note: You can call this method from synchronous code using a completion handler,
77 /// > as shown on this page, or you can call it as an asynchronous method that has the
78 /// > following declaration:
79 /// >
80 /// > ```swift
81 /// > func startFetchingMetadata(for url: URL) async throws -> LPLinkMetadata
82 /// > ```
83 /// >
84 /// > For information about concurrency and asynchronous code in Swift, see
85 /// <doc
86 /// ://com.apple.documentation/documentation/swift/calling-objective-c-apis-asynchronously>.
87 #[unsafe(method(startFetchingMetadataForURL:completionHandler:))]
88 #[unsafe(method_family = none)]
89 pub unsafe fn startFetchingMetadataForURL_completionHandler(
90 &self,
91 url: &NSURL,
92 completion_handler: &block2::DynBlock<dyn Fn(*mut LPLinkMetadata, *mut NSError)>,
93 );
94
95 #[cfg(all(feature = "LPLinkMetadata", feature = "block2"))]
96 /// Fetches metadata for the given ``NSURLRequest``.
97 ///
98 /// Call this method once per ``LPMetadataProvider`` instance. If you attempt to
99 /// fetch metadata multiple times on a single ``LPMetadataProvider`` instance,
100 /// it throws an error.
101 ///
102 /// The completion handler executes on a background queue. Dispatch any
103 /// necessary UI updates back to the main queue. When the completion handler
104 /// returns, it deletes any file URLs returned in the resulting
105 /// ``LPLinkMetadata``.
106 ///
107 /// > Concurrency Note: You can call this method from synchronous code using a completion handler,
108 /// > as shown on this page, or you can call it as an asynchronous method that has the
109 /// > following declaration:
110 /// >
111 /// > ```swift
112 /// > func startFetchingMetadata(for request: URLRequest) async throws -> LPLinkMetadata
113 /// > ```
114 /// >
115 /// > For information about concurrency and asynchronous code in Swift, see
116 /// <doc
117 /// ://com.apple.documentation/documentation/swift/calling-objective-c-apis-asynchronously>.
118 #[unsafe(method(startFetchingMetadataForRequest:completionHandler:))]
119 #[unsafe(method_family = none)]
120 pub unsafe fn startFetchingMetadataForRequest_completionHandler(
121 &self,
122 request: &NSURLRequest,
123 completion_handler: &block2::DynBlock<dyn Fn(*mut LPLinkMetadata, *mut NSError)>,
124 );
125
126 /// Cancels a metadata request.
127 ///
128 /// This method invokes the completion handler with the error code
129 /// ``LPErrorCode/LPErrorMetadataFetchCancelled`` if the request hasn’t already
130 /// completed.
131 #[unsafe(method(cancel))]
132 #[unsafe(method_family = none)]
133 pub unsafe fn cancel(&self);
134
135 /// A Boolean value indicating whether to download subresources specified by the
136 /// metadata.
137 ///
138 /// Subresources include the icon, image, or video. When set to `false`, the
139 /// returned ``LPLinkMetadata`` object consists only of metadata retrieved from
140 /// the main resource identified by the url passed to
141 /// ``LPMetadataProvider/startFetchingMetadataForURL:completionHandler:``.
142 ///
143 /// The default value is `true`.
144 #[unsafe(method(shouldFetchSubresources))]
145 #[unsafe(method_family = none)]
146 pub unsafe fn shouldFetchSubresources(&self) -> bool;
147
148 /// Setter for [`shouldFetchSubresources`][Self::shouldFetchSubresources].
149 #[unsafe(method(setShouldFetchSubresources:))]
150 #[unsafe(method_family = none)]
151 pub unsafe fn setShouldFetchSubresources(&self, should_fetch_subresources: bool);
152
153 /// The time interval after which the request automatically fails if it hasn’t
154 /// already completed.
155 ///
156 /// The default timeout interval is 30 seconds. If a metadata fetch takes longer
157 /// than the timeout interval, the completion handler is called with the error
158 /// code ``LPErrorCode/LPErrorMetadataFetchTimedOut``.
159 #[unsafe(method(timeout))]
160 #[unsafe(method_family = none)]
161 pub unsafe fn timeout(&self) -> NSTimeInterval;
162
163 /// Setter for [`timeout`][Self::timeout].
164 #[unsafe(method(setTimeout:))]
165 #[unsafe(method_family = none)]
166 pub unsafe fn setTimeout(&self, timeout: NSTimeInterval);
167 );
168}
169
170/// Methods declared on superclass `NSObject`.
171impl LPMetadataProvider {
172 extern_methods!(
173 #[unsafe(method(init))]
174 #[unsafe(method_family = init)]
175 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
176
177 #[unsafe(method(new))]
178 #[unsafe(method_family = new)]
179 pub unsafe fn new() -> Retained<Self>;
180 );
181}