LinkPresentation macOS xcode14.3 beta1

#LinkPresentation.framework

diff -ruN /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPError.h /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPError.h
--- /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPError.h	2022-11-12 15:59:30
+++ /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPError.h	2023-02-11 16:43:57
@@ -6,20 +6,30 @@
 #import <LinkPresentation/LPFoundation.h>
 
 /** LPErrorDomain is used to indicate a LinkPresentation error. */
+
+/// The domain for Link Presentation errors.
 LP_EXTERN NSErrorDomain const LPErrorDomain API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0));
 
 /** Constants used by NSError to indicate errors in the LinkPresentation domain. */
 typedef NS_ERROR_ENUM(LPErrorDomain, LPErrorCode) {
     /** LPErrorUnknown indicates that an unknown error occurred. */
+
+/// An unknown error.
     LPErrorUnknown = 1,
 
     /** LPErrorMetadataFetchFailed indicates that a metadata fetch failed.
      This can be due to network conditions, server availability, or any number of other causes. */
+
+/// An error indicating that a metadata fetch failed.
     LPErrorMetadataFetchFailed,
 
     /** LPErrorMetadataFetchCancelled indicates that the metadata fetch was cancelled by the client. */
+
+/// An error indicating that the metadata fetch was canceled by the client.
     LPErrorMetadataFetchCancelled,
 
     /** LPErrorMetadataFetchTimedOut indicates that the metadata fetch took longer than allowed. */
+
+/// An error indicating that the metadata fetch took longer than allowed.
     LPErrorMetadataFetchTimedOut
 } API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0));
diff -ruN /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPLinkMetadata.h /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPLinkMetadata.h
--- /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPLinkMetadata.h	2022-11-12 15:59:30
+++ /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPLinkMetadata.h	2023-02-12 14:14:19
@@ -10,39 +10,126 @@
 /**
  An LPLinkMetadata object contains metadata about a URL.
  */
+
+/// An object that contains metadata about a URL.
+///
+/// Use ``LPLinkMetadata`` to store the metadata about a URL, including its
+/// title, icon, images and video.
+///
+/// Fetch metadata using ``LPMetadataProvider``. For remote URLs, cache the
+/// metadata locally to avoid the data and performance cost of fetching it from
+/// the internet every time you present it. ``LPLinkMetadata`` is serializable
+/// with
+/// <doc://com.apple.documentation/documentation/foundation/nssecurecoding>.
+///
+/// For local file URLs, the
+/// <doc://com.apple.documentation/documentation/quicklookthumbnailing> API
+/// retrieves a representative thumbnail for the file, if possible.
+///
+/// ## Provide custom metadata
+///
+/// Say your app already has a database of links, with titles and images that
+/// weren’t fetched by ``LPMetadataProvider``. You don’t have to fetch new
+/// metadata from the internet in order to accelerate the share sheet or to
+/// present a rich link. Instead, you can fill in the fields of
+/// ``LPLinkMetadata`` yourself.
+///
+/// Create an ``LPLinkMetadata`` object, and fill in at least the
+/// ``LPLinkMetadata/originalURL`` and ``LPLinkMetadata/URL`` fields, plus
+/// whatever additional information you have.
+///
+/// ```swift
+/// func activityViewControllerLinkMetadata(_: UIActivityViewController) -> LPLinkMetadata? {
+///     let metadata = LPLinkMetadata()
+///     metadata.originalURL = URL(string: "https://www.example.com/apple-pie")
+///     metadata.url = metadata.originalURL
+///     metadata.title = "The Greatest Apple Pie In The World"
+///     metadata.imageProvider = NSItemProvider.init(contentsOf:
+///         Bundle.main.url(forResource: "apple-pie", withExtension: "jpg"))
+///     return metadata
+/// }
+/// ```
+///
+/// ## Accelerate the share sheet preview
+///
+/// For existing apps that share URLs, the share sheet automatically presents a
+/// preview of the link. The preview first shows a placeholder link icon
+/// alongside the base URL while fetching the link’s metadata over the network.
+/// The preview updates once the link’s icon and title become available.
+///
+/// If you already have an ``LPLinkMetadata`` object for a URL, pass it to the
+/// share sheet to present the preview instantly, without fetching data over the
+/// network. In your implementation of
+/// <doc://com.apple.documentation/documentation/uikit/uiactivityitemsource/3144571-activityviewcontrollerlinkmetada>,
+/// return the metadata object.
+///
+/// ```swift
+/// func activityViewControllerLinkMetadata(_:
+/// UIActivityViewController) -> LPLinkMetadata? {
+///     return self.metadata
+/// }
+/// ```
+///
+/// If the user chooses to share to Messages, the same metadata passes directly
+/// through, providing a smooth and seamless experience with no unnecessary
+/// loading.
 LP_EXTERN API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0))
 @interface LPLinkMetadata : NSObject <NSCopying, NSSecureCoding>
 
 /** The original URL that metadata was requested from. */
+
+/// The original URL of the metadata request.
 @property (nonatomic, retain, nullable) NSURL *originalURL;
 
 /**
  The URL that metadata was retrieved from.
  This takes server-side redirects into account.
  */
+
+/// The URL that returns the metadata, taking server-side redirects into
+/// account.
+///
+/// The URL that returns the metadata may differ from the
+/// ``LPLinkMetadata/originalURL`` to which you sent the metadata request. This
+/// can happen if the server redirects the request, for example, when a resource
+/// has moved, or when the original URL is a domain alias.
 @property (nonatomic, retain, nullable) NSURL *URL;
 
 /**
  A title for the URL.
  */
+
+/// A representative title for the URL.
 @property (nonatomic, copy, nullable) NSString *title;
 
 /**
  An item provider which will return data corresponding to a representative
  icon for the URL.
  */
+
+/// An object that retrieves data corresponding to a representative icon for the
+/// URL.
 @property (nonatomic, retain, nullable) NSItemProvider *iconProvider;
 
 /**
  An item provider which will return data corresponding to a representative
  image for the URL.
  */
+
+/// An object that retrieves data corresponding to a representative image for
+/// the URL.
 @property (nonatomic, retain, nullable) NSItemProvider *imageProvider;
 
 /**
  An item provider which will return data corresponding to a representative
  video for the URL that AVFoundation can play.
  */
+
+/// An object that retrieves data corresponding to a representative video for
+/// the URL.
+///
+/// The item provider returns a video that
+/// <doc://com.apple.documentation/documentation/avfoundation> can play.
 @property (nonatomic, retain, nullable) NSItemProvider *videoProvider;
 
 /**
@@ -51,6 +138,8 @@
  This may point to to a remote video file that AVFoundation can stream,
  or to a YouTube video URL.
  */
+
+/// A remote URL corresponding to a representative video for the URL.
 @property (nonatomic, retain, nullable) NSURL *remoteVideoURL;
 
 @end
diff -ruN /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPLinkView.h /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPLinkView.h
--- /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPLinkView.h	2022-11-12 15:59:30
+++ /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPLinkView.h	2023-02-11 16:43:57
@@ -23,15 +23,67 @@
  */
 LP_EXTERN API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0))
 #if TARGET_OS_IPHONE
+/// A rich visual representation of a link.
+///
+/// ``LPLinkView`` presents a link based on its available metadata. Use it to
+/// show a link’s title and icon, associated images, inline audio, video
+/// playback, and maps in a familiar and consistent style.
+///
+/// ## Present a rich link
+///
+/// To present a rich link in your app, create an ``LPLinkView``, passing an
+/// ``LPLinkMetadata`` instance into its initializer. Then add the
+/// ``LPLinkView`` to your view.
+///
+/// For example, to present links in a table view, add an ``LPLinkView``
+/// instance as a subview when populating each cell.
+///
+/// ```swift
+/// let linkView = LPLinkView(metadata: metadata)
+/// cell.contentView.addSubview(linkView)
+/// linkView.sizeToFit()
+/// ```
+///
+/// ``LPLinkView`` has an intrinsic size, but it also responds to
+/// <doc://com.apple.documentation/documentation/uikit/uiview/1622630-sizetofit>
+/// to present a layout at any size.
 @interface LPLinkView : UIView
 #else
+/// A rich visual representation of a link.
+///
+/// ``LPLinkView`` presents a link based on its available metadata. Use it to
+/// show a link’s title and icon, associated images, inline audio, video
+/// playback, and maps in a familiar and consistent style.
+///
+/// ## Present a rich link
+///
+/// To present a rich link in your app, create an ``LPLinkView``, passing an
+/// ``LPLinkMetadata`` instance into its initializer. Then add the
+/// ``LPLinkView`` to your view.
+///
+/// For example, to present links in a table view, add an ``LPLinkView``
+/// instance as a subview when populating each cell.
+///
+/// ```swift
+/// let linkView = LPLinkView(metadata: metadata)
+/// cell.contentView.addSubview(linkView)
+/// linkView.sizeToFit()
+/// ```
+///
+/// ``LPLinkView`` has an intrinsic size, but it also responds to
+/// <doc://com.apple.documentation/documentation/uikit/uiview/1622630-sizetofit>
+/// to present a layout at any size.
 @interface LPLinkView : NSView
 #endif
 
 - (instancetype)initWithCoder:(NSCoder *)coder NS_UNAVAILABLE;
 - (void)encodeWithCoder:(NSCoder *)coder NS_UNAVAILABLE;
 
+
+/// Initializes a placeholder link view without metadata for a given URL.
 - (instancetype)initWithURL:(NSURL *)URL;
+
+/// Initializes a link view with specified metadata.
 - (instancetype)initWithMetadata:(LPLinkMetadata *)metadata;
 
 /**
@@ -40,6 +92,8 @@
  The metadata can either be generated automatically from a URL by LPMetadataProvider,
  or manually constructed with the desired data.
  */
+
+/// The metadata from which to generate a rich presentation.
 @property (nonatomic, copy) LPLinkMetadata *metadata;
 
 @end
diff -ruN /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPMetadataProvider.h /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPMetadataProvider.h
--- /Applications/Xcode_14.2.0.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPMetadataProvider.h	2022-11-12 15:59:30
+++ /Applications/Xcode_14.3.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/LinkPresentation.framework/Headers/LPMetadataProvider.h	2023-02-12 14:14:19
@@ -20,6 +20,46 @@
 
  @see `LPLinkMetadata`
  */
+
+/// An object that retrieves metadata for a URL.
+///
+/// Use ``LPMetadataProvider`` to fetch metadata for a URL, including its title,
+/// icon, and image or video links. All properties on the resulting
+/// ``LPLinkMetadata`` instance are optional.
+///
+/// - Note: To enable macOS clients to fetch metadata for remote URLs, add the
+/// <doc://com.apple.documentation/documentation/bundleresources/entitlements/com_apple_security_network_client>
+/// entitlement.
+///
+/// ## Fetch link metadata from a URL
+///
+/// For each metadata request, create an instance of ``LPMetadataProvider`` and
+/// call ``LPMetadataProvider/startFetchingMetadataForURL:completionHandler:``.
+///
+/// In the completion handler, check the error. If your user doesn’t have a
+/// network connection, the fetch can fail. If the server doesn’t respond or is
+/// too slow, the fetch can time out. Alternatively, the app may cancel the
+/// request, or an unknown error may occur.
+///
+/// Otherwise, use the metadata however you want, for example, to populate the
+/// title for a table view cell.
+///
+/// ```swift
+/// let metadataProvider = LPMetadataProvider()
+/// let url = URL(string: "https://www.apple.com/ipad")!
+///
+/// metadataProvider.startFetchingMetadata(for: url) { metadata, error in
+///     if error != nil {
+///         // The fetch failed; handle the error.
+///         return
+///     }
+///
+///     // Make use of fetched metadata.
+/// }
+/// ```
+///
+/// For more information about handling link presentation errors, see
+/// ``LinkPresentation/LPError``.
 LP_EXTERN API_AVAILABLE(macos(10.15), ios(13.0), watchos(9.0)) API_UNAVAILABLE(tvos)
 @interface LPMetadataProvider : NSObject
 
@@ -34,6 +74,17 @@
  An exception will be thrown if this is called more than once
  on a particular LPMetadataProvider instance.
  */
+
+/// Fetches metadata for the given URL.
+///
+/// Call this method once per ``LPMetadataProvider`` instance. If you attempt to
+/// fetch metadata multiple times on a single ``LPMetadataProvider`` instance,
+/// it throws an error.
+///
+/// The completion handler executes on a background queue. Dispatch any
+/// necessary UI updates back to the main queue. When the completion handler
+/// returns, it deletes any file URLs returned in the resulting
+/// ``LPLinkMetadata``.
 - (void)startFetchingMetadataForURL:(NSURL *)URL completionHandler:(void(^)(LPLinkMetadata *_Nullable metadata, NSError *_Nullable error))completionHandler;
 
 /**
@@ -47,6 +98,16 @@
  An exception will be thrown if this is called more than once
  on a particular LPMetadataProvider instance.
  */
+
+/// > Concurrency Note: You can call this method from synchronous code using a completion handler,
+/// > as shown on this page, or you can call it as an asynchronous method that has the
+/// > following declaration:
+/// >
+/// > ```swift
+/// >  func startFetchingMetadata(for request: URLRequest) async throws -> LPLinkMetadata
+/// > ```
+/// >
+/// > For information about concurrency and asynchronous code in Swift, see <doc://com.apple.documentation/documentation/swift/calling-objective-c-apis-asynchronously>.
 - (void)startFetchingMetadataForRequest:(NSURLRequest *)request completionHandler:(void(^)(LPLinkMetadata *_Nullable metadata, NSError *_Nullable error))completionHandler API_AVAILABLE(macos(12.0), ios(15.0));
 
 /**
@@ -55,6 +116,12 @@
  If the request had not already completed, the completion handler will be invoked
  with the error code `LPErrorMetadataFetchCancelled`.
  */
+
+/// Cancels a metadata request.
+///
+/// This method invokes the completion handler with the error code
+/// ``LPErrorCode/LPErrorMetadataFetchCancelled`` if the request hasn’t already
+/// completed.
 - (void)cancel;
 
 /**
@@ -65,6 +132,16 @@
  
  The default value is `YES`.
  */
+
+/// A Boolean value indicating whether to download subresources specified by the
+/// metadata.
+///
+/// Subresources include the icon, image, or video. When set to `false`, the
+/// returned ``LPLinkMetadata`` object consists only of metadata retrieved from
+/// the main resource identified by the url passed to
+/// ``LPMetadataProvider/startFetchingMetadataForURL:completionHandler:``.
+///
+/// The default value is `true`.
 @property (nonatomic) BOOL shouldFetchSubresources;
 
 /**
@@ -76,6 +153,13 @@
 
  The default timeout is 30 seconds.
 */
+
+/// The time interval after which the request automatically fails if it hasn’t
+/// already completed.
+///
+/// The default timeout interval is 30 seconds. If a metadata fetch takes longer
+/// than the timeout interval, the completion handler is called with the error
+/// code ``LPErrorCode/LPErrorMetadataFetchTimedOut``.
 @property (nonatomic) NSTimeInterval timeout;
 
 @end