Struct LPLinkMetadata 

pub struct LPLinkMetadata { /* private fields */ }

Available on crate feature LPLinkMetadata only.

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.

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.

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.

See also Apple’s documentation

Implementations

impl LPLinkMetadata

pub unsafe fn originalURL(&self) -> Option<Retained<NSURL>>

The original URL of the metadata request.

pub unsafe fn setOriginalURL(&self, original_url: Option<&NSURL>)

Setter for originalURL.

pub unsafe fn URL(&self) -> Option<Retained<NSURL>>

The URL that returned 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.

pub unsafe fn setURL(&self, url: Option<&NSURL>)

Setter for URL.

pub unsafe fn title(&self) -> Option<Retained<NSString>>

A representative title for the URL.

pub unsafe fn setTitle(&self, title: Option<&NSString>)

Setter for title.

This is copied when set.

pub unsafe fn iconProvider(&self) -> Option<Retained<NSItemProvider>>

An object that retrieves data corresponding to a representative icon for the URL.

pub unsafe fn setIconProvider(&self, icon_provider: Option<&NSItemProvider>)

Setter for iconProvider.

pub unsafe fn imageProvider(&self) -> Option<Retained<NSItemProvider>>

An object that retrieves data corresponding to a representative image for the URL.

pub unsafe fn setImageProvider(&self, image_provider: Option<&NSItemProvider>)

Setter for imageProvider.

pub unsafe fn videoProvider(&self) -> Option<Retained<NSItemProvider>>

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.

pub unsafe fn setVideoProvider(&self, video_provider: Option<&NSItemProvider>)

Setter for videoProvider.

pub unsafe fn remoteVideoURL(&self) -> Option<Retained<NSURL>>

A remote URL corresponding to a representative video for the URL.

This may reference a remote video file that <doc ://com.apple.documentation/documentation/avfoundation> can stream, or a YouTube video URL.

pub unsafe fn setRemoteVideoURL(&self, remote_video_url: Option<&NSURL>)

Setter for remoteVideoURL.

impl LPLinkMetadata

Methods declared on superclass NSObject.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn new() -> Retained<Self>

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for LPLinkMetadata

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<LPLinkMetadata> for LPLinkMetadata

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for LPLinkMetadata

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for LPLinkMetadata

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for LPLinkMetadata

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for LPLinkMetadata

const NAME: &'static str = "LPLinkMetadata"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<LPLinkMetadata as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl CopyingHelper for LPLinkMetadata

type Result = LPLinkMetadata

The immutable counterpart of the type, or Self if the type has no immutable counterpart.

impl Debug for LPLinkMetadata

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for LPLinkMetadata

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for LPLinkMetadata

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for LPLinkMetadata

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSCoding for LPLinkMetadata

unsafe fn encodeWithCoder(&self, coder: &NSCoder)

where Self: Sized + Message,

Safety

unsafe fn initWithCoder( this: Allocated<Self>, coder: &NSCoder, ) -> Option<Retained<Self>>

where Self: Sized + Message,

Safety

impl NSCopying for LPLinkMetadata

fn copy(&self) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

unsafe fn copyWithZone(&self, zone: *mut NSZone) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Returns a new instance that’s a copy of the receiver.

impl NSObjectProtocol for LPLinkMetadata

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl NSSecureCoding for LPLinkMetadata

fn supportsSecureCoding() -> bool

where Self: Sized + ClassType,

impl PartialEq for LPLinkMetadata

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for LPLinkMetadata

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for LPLinkMetadata

impl Eq for LPLinkMetadata