#[repr(C)]pub struct NSFileProviderExtension { /* private fields */ }
Extension
only.Expand description
Implementations§
Source§impl NSFileProviderExtension
impl NSFileProviderExtension
pub unsafe fn itemForIdentifier_error( &self, identifier: &NSFileProviderItemIdentifier, ) -> Result<Retained<NSFileProviderItem>, Retained<NSError>>
NSFileProviderItem
only.Sourcepub unsafe fn URLForItemWithPersistentIdentifier(
&self,
identifier: &NSFileProviderItemIdentifier,
) -> Option<Retained<NSURL>>
Available on crate feature NSFileProviderItem
only.
pub unsafe fn URLForItemWithPersistentIdentifier( &self, identifier: &NSFileProviderItemIdentifier, ) -> Option<Retained<NSURL>>
NSFileProviderItem
only.Should return the URL corresponding to a specific identifier. Fail if it’s not a subpath of documentStorageURL.
This is a static mapping; each identifier must always return a path corresponding to the same file. By default, this returns the path relative to the path returned by documentStorageURL.
pub unsafe fn persistentIdentifierForItemAtURL( &self, url: &NSURL, ) -> Option<Retained<NSFileProviderItemIdentifier>>
NSFileProviderItem
only.Sourcepub unsafe fn providePlaceholderAtURL_completionHandler(
&self,
url: &NSURL,
completion_handler: &DynBlock<dyn Fn(*mut NSError)>,
)
Available on crate feature block2
only.
pub unsafe fn providePlaceholderAtURL_completionHandler( &self, url: &NSURL, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )
block2
only.This method is called when a placeholder URL should be provided for the item at the given URL.
The implementation of this method should call +[NSFileProviderManager writePlaceholderAtURL:withMetadata:error:] with the URL returned by +[NSFileProviderManager placeholderURLForURL:], then call the completion handler.
Sourcepub unsafe fn startProvidingItemAtURL_completionHandler(
&self,
url: &NSURL,
completion_handler: &DynBlock<dyn Fn(*mut NSError)>,
)
Available on crate feature block2
only.
pub unsafe fn startProvidingItemAtURL_completionHandler( &self, url: &NSURL, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )
block2
only.Should ensure that the actual file is in the position returned by URLForItemWithPersistentIdentifier:, then call the completion handler.
Sourcepub unsafe fn stopProvidingItemAtURL(&self, url: &NSURL)
pub unsafe fn stopProvidingItemAtURL(&self, url: &NSURL)
Called after the last claim to the file has been released. At this point, it is safe for the file provider to remove the content file.
Care should be taken that the corresponding placeholder file stays behind after the content file has been deleted.
Sourcepub unsafe fn itemChangedAtURL(&self, url: &NSURL)
pub unsafe fn itemChangedAtURL(&self, url: &NSURL)
Called at some point after the file has changed; the provider may then trigger an upload.
Source§impl NSFileProviderExtension
Methods declared on superclass NSObject
.
impl NSFileProviderExtension
Methods declared on superclass NSObject
.
Source§impl NSFileProviderExtension
Deprecated.
impl NSFileProviderExtension
Deprecated.
Sourcepub unsafe fn writePlaceholderAtURL_withMetadata_error(
placeholder_url: &NSURL,
metadata: &NSDictionary<NSURLResourceKey, AnyObject>,
) -> Result<(), Retained<NSError>>
👎Deprecated: Use the corresponding method on NSFileProviderManager instead
pub unsafe fn writePlaceholderAtURL_withMetadata_error( placeholder_url: &NSURL, metadata: &NSDictionary<NSURLResourceKey, AnyObject>, ) -> Result<(), Retained<NSError>>
Writes out a placeholder at the specified URL. The URL should be one returned by placeholderURLForURL:; if URL resource values are requested, the system will consult the placeholder before consulting your app extension.
Metadata contains NSURLNameKey, NSURLFileSizeKey, NSURLIsPackageKey.
Sourcepub unsafe fn placeholderURLForURL(url: &NSURL) -> Retained<NSURL>
👎Deprecated
pub unsafe fn placeholderURLForURL(url: &NSURL) -> Retained<NSURL>
Returns the designated placeholder URL for a given URL. This placeholder will be consulted before falling back to your app extension to enhance performance. To write out a placeholder, use the writePlaceHolderAtURL: method above.
Sourcepub unsafe fn providerIdentifier(&self) -> Retained<NSString>
👎Deprecated
pub unsafe fn providerIdentifier(&self) -> Retained<NSString>
An identifier unique to this provider.
When modifying the files stored in the directory returned by documentStorageURL, you should pass this identifier to your file coordinator’s setPurposeIdentifier: method.
Sourcepub unsafe fn documentStorageURL(&self) -> Retained<NSURL>
👎Deprecated
pub unsafe fn documentStorageURL(&self) -> Retained<NSURL>
The root URL for provided documents. This URL is derived by consulting the NSExtensionFileProviderDocumentGroup property on your extension. The document storage URL is the folder “File Provider Storage” in the corresponding container.
Source§impl NSFileProviderExtension
NSFileProviderActions.
This category encapsulates common user-driven actions on FileProvider’s items.
impl NSFileProviderExtension
NSFileProviderActions. This category encapsulates common user-driven actions on FileProvider’s items.
Sourcepub unsafe fn importDocumentAtURL_toParentItemIdentifier_completionHandler(
&self,
file_url: &NSURL,
parent_item_identifier: &NSFileProviderItemIdentifier,
completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
)
Available on crate features NSFileProviderActions
and NSFileProviderItem
and block2
only.
pub unsafe fn importDocumentAtURL_toParentItemIdentifier_completionHandler( &self, file_url: &NSURL, parent_item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>, )
NSFileProviderActions
and NSFileProviderItem
and block2
only.Import a document.
The file or package at fileURL should be moved on disk into the file provider’s own storage, where it will later be uploaded. The completion block should be executed after the move on disk, but before the upload. Before doing any network, actually.
In the completion block, importedDocumentItem should have these properties set:
- itemIdentifier
- parentItemIdentifier (to the value passed in to this method)
- filename (to fileURL’s resource value for key NSURLNameKey)
- creationDate (to NSURLCreationDateKey)
- contentModificationDate (to NSURLContentModificationDateKey)
- contentType (to NSURLContentTypeKey)
- documentSize (to NSURLTotalFileSizeKey on a flat file, or to the sum of the files sizes for a package)
- capabilities
[fileURL startAccessingSecurityScopedResource] needs to be called prior to accessing this security scoped URL, and stopAccessingSecurityScopedResource needs to be called when done.
Note that itemIdentifier should be set with no network call. It doesn’t have to be the final identifier. If the identifier changes after talking to the server then the file provider should send a delete for the temporary, local identifier immediately followed by an add with the final identifier.
A reasonable way of organizing files in the file provider storage is:
/ <filename . <extension
If the item identifier was to change, you should move the file on disk to update its path, under coordination with NSFileCoordinatorWritingForMoving.
This is expected to work offline even if there might be a collision (another item with the same filename and parentItemIdentifier) only detected when later syncing up this change to the server. In that case, it is suggested that a follow up update to the item change its filename to something unique. This wouldn’t be considered an error to import.
If however you can tell right away, with no communication to your server, that there is a collision then this call should fail with error code NSFileProviderErrorFilenameCollision generated with this method: -[NSError (NSFileProviderError) fileProviderErrorForCollisionWithItem:].
The existing item set in this error will be used to handle the collision, and ask the user if she or he would like to replace the existing item. This takes into account the existing item’s capabilities (particularly NSFileProviderItemCapabilitiesAllowsTrashing and AllowsDeleting.)
Collision checks should be case insensitive even if the filesystem or file provider might allow two coexisting filenames differing only by their case.
Upload errors (such as NSFileProviderErrorInsufficientQuota) should be handled with a subsequent update to the item, setting its uploadingError property. Upload errors should not prevent creating or importing a document, because they can be resolved at a later date (for example, when the user has quota again.)
Other errors will be presented to the user, but are unexpected. If you want to prevent imports in a given directory, then the directory item’s capacities should exclude NSFileProviderItemCapabilitiesAllowsAddingSubItems.
Sourcepub unsafe fn createDirectoryWithName_inParentItemIdentifier_completionHandler(
&self,
directory_name: &NSString,
parent_item_identifier: &NSFileProviderItemIdentifier,
completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
)
Available on crate features NSFileProviderActions
and NSFileProviderItem
and block2
only.
pub unsafe fn createDirectoryWithName_inParentItemIdentifier_completionHandler( &self, directory_name: &NSString, parent_item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>, )
NSFileProviderActions
and NSFileProviderItem
and block2
only.Create a directory.
This is expected to complete before doing any network.
In the completion block, createdDirectoryItem should have these properties set:
- itemIdentifier
- parentItemIdentifier (to the value passed in to this method)
- filename (to directoryName)
- creationDate (to the current date and time)
- contentType (to “public.folder” - UTTypeFolder)
- childItemCount (to 0)
- capabilities
Errors (including collision errors) are handled as documented for the import method above. Directory creation is gated by the capabilities of the destination directory, with NSFileProviderItemCapabilitiesAllowsAddingSubItems.
Sourcepub unsafe fn renameItemWithIdentifier_toName_completionHandler(
&self,
item_identifier: &NSFileProviderItemIdentifier,
item_name: &NSString,
completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
)
Available on crate features NSFileProviderActions
and NSFileProviderItem
and block2
only.
pub unsafe fn renameItemWithIdentifier_toName_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, item_name: &NSString, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>, )
NSFileProviderActions
and NSFileProviderItem
and block2
only.Rename a document or a directory.
This is expected to complete before doing any network.
itemName is the full file or directory name, complete with its file extension. In the completion block, property renamedItem.filename should change to itemName. Property renamedItem.displayName should also be updated if you chose to overwrite that method.
Errors (including collision errors) are handled as documented for the import method above. Renames are gated by the capabilities of the renamed item, with NSFileProviderItemCapabilitiesAllowsRenaming.
Sourcepub unsafe fn reparentItemWithIdentifier_toParentItemWithIdentifier_newName_completionHandler(
&self,
item_identifier: &NSFileProviderItemIdentifier,
parent_item_identifier: &NSFileProviderItemIdentifier,
new_name: Option<&NSString>,
completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
)
Available on crate features NSFileProviderActions
and NSFileProviderItem
and block2
only.
pub unsafe fn reparentItemWithIdentifier_toParentItemWithIdentifier_newName_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, parent_item_identifier: &NSFileProviderItemIdentifier, new_name: Option<&NSString>, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>, )
NSFileProviderActions
and NSFileProviderItem
and block2
only.Move an item to a new directory.
This is expected to complete before doing any network.
If newName is non null, the moved item should be renamed to newName.
Errors (including collision errors) are handled as documented for the import method above. Moves are gated by the capabilities of both the moved item with NSFileProviderItemCapabilitiesAllowsReparenting, and the destination directory with NSFileProviderItemCapabilitiesAllowsAddingSubItems.
Sourcepub unsafe fn trashItemWithIdentifier_completionHandler(
&self,
item_identifier: &NSFileProviderItemIdentifier,
completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
)
Available on crate features NSFileProviderActions
and NSFileProviderItem
and block2
only.
pub unsafe fn trashItemWithIdentifier_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>, )
NSFileProviderActions
and NSFileProviderItem
and block2
only.Move an item to the trash.
In the completion block, property trashedItem.isTrashed should be set to YES. You should keep track of the original parentItemIdentifier of the item before it was moved to trash, so you can move the item back where it used to be in the untrash method. You could use the trashedItem.parentItemIdentifier property for that.
The trashed item should continue to belong to the working set of documents cached on the device and visible offline to the user. But if it is a directory, then all of its children should be removed from the working set and the file provider extension should send deletion events to make sure that they no longer appear in the recent lists.
It is also suggested that shared documents be unshared when trashed.
Trash is gated by the capabilities of the trashed item with NSFileProviderItemCapabilitiesAllowsTrashing.
Sourcepub unsafe fn untrashItemWithIdentifier_toParentItemIdentifier_completionHandler(
&self,
item_identifier: &NSFileProviderItemIdentifier,
parent_item_identifier: Option<&NSFileProviderItemIdentifier>,
completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
)
Available on crate features NSFileProviderActions
and NSFileProviderItem
and block2
only.
pub unsafe fn untrashItemWithIdentifier_toParentItemIdentifier_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, parent_item_identifier: Option<&NSFileProviderItemIdentifier>, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>, )
NSFileProviderActions
and NSFileProviderItem
and block2
only.Move an item out of the trash.
If parentItemIdentifier is nil, the file provider should attempt to put the item back where it was when it was moved to the trash; otherwise it should move it to this new parent.
If the item is a directory, then the file provider extension should enumerate the children and send addition events in the working set so that the documents in the now untrashed directory may be reindexed.
Untrash is gated by the capabilities of the destination directory, with NSFileProviderItemCapabilitiesAllowsAddingSubItems.
Sourcepub unsafe fn deleteItemWithIdentifier_completionHandler(
&self,
item_identifier: &NSFileProviderItemIdentifier,
completion_handler: &DynBlock<dyn Fn(*mut NSError)>,
)
Available on crate features NSFileProviderActions
and NSFileProviderItem
and block2
only.
pub unsafe fn deleteItemWithIdentifier_completionHandler( &self, item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, )
NSFileProviderActions
and NSFileProviderItem
and block2
only.Delete an item forever.
This is called when the user deletes an item that was already in the Trash and the item should no longer appear there after this call. This call should remove the item from the working set.
Delete is gated by the capabilities of the removed item with NSFileProviderItemCapabilitiesAllowsDeleting.
Sourcepub unsafe fn setLastUsedDate_forItemIdentifier_completionHandler(
&self,
last_used_date: Option<&NSDate>,
item_identifier: &NSFileProviderItemIdentifier,
completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
)
Available on crate features NSFileProviderActions
and NSFileProviderItem
and block2
only.
pub unsafe fn setLastUsedDate_forItemIdentifier_completionHandler( &self, last_used_date: Option<&NSDate>, item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>, )
NSFileProviderActions
and NSFileProviderItem
and block2
only.Mark an item as recently used, or clear its lastUsedDate if nil.
This last used date is the sort key for the recent lists. It is the primary hint that an item must belong to the working set cached and indexed on the user’s device.
The file provider is asked to persist the new last used date on disk, then call the completion callback with the updated last used date. At a later point, the file provider should sync the new last used date to their server.
The error parameter is here for debugging purposes alone; it won’t be presented to the user or otherwise handled, but it will be logged.
Sourcepub unsafe fn setTagData_forItemIdentifier_completionHandler(
&self,
tag_data: Option<&NSData>,
item_identifier: &NSFileProviderItemIdentifier,
completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
)
Available on crate features NSFileProviderActions
and NSFileProviderItem
and block2
only.
pub unsafe fn setTagData_forItemIdentifier_completionHandler( &self, tag_data: Option<&NSData>, item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>, )
NSFileProviderActions
and NSFileProviderItem
and block2
only.Tag an item, or untag it if tagData is nil.
The file provider is asked to persist the new tag data on disk, then call the completion callback with the updated tagged data. At a later point, the file provider should sync the new tag data to their server.
Tagged items are relevant to the user and should be in the working set even if they haven’t been used recently.
If set, the error will be immediately presented to the user and the item just won’t be tagged.
On shared items, tags should sync across the devices of any one participant but shouldn’t sync across users.
Sourcepub unsafe fn setFavoriteRank_forItemIdentifier_completionHandler(
&self,
favorite_rank: Option<&NSNumber>,
item_identifier: &NSFileProviderItemIdentifier,
completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>,
)
Available on crate features NSFileProviderActions
and NSFileProviderItem
and block2
only.
pub unsafe fn setFavoriteRank_forItemIdentifier_completionHandler( &self, favorite_rank: Option<&NSNumber>, item_identifier: &NSFileProviderItemIdentifier, completion_handler: &DynBlock<dyn Fn(*mut NSFileProviderItem, *mut NSError)>, )
NSFileProviderActions
and NSFileProviderItem
and block2
only.Mark a directory as favorite (or no longer favorite if favoriteRank is nil.)
The favorite rank is used to represent the relative order of two favorite directories in the UI. It is a 64 bit unsigned integer. It needs to be synced.
Favorite directories are relevant to the user and should be in the working set even if they haven’t been used recently. The documents and directories in the favorite directory however don’t all have to be in the working set, and don’t all have to be made accessible offline.
The file provider is asked to persist the new favorite rank on disk, then call the completion callback with the updated favorite rank. At a later point, the file provider should sync the new favorite rank to their server.
Source§impl NSFileProviderExtension
NSFileProviderDomain.
impl NSFileProviderExtension
NSFileProviderDomain.
pub unsafe fn domain(&self) -> Option<Retained<NSFileProviderDomain>>
NSFileProviderDomain
only.Source§impl NSFileProviderExtension
NSFileProviderEnumeration.
impl NSFileProviderExtension
NSFileProviderEnumeration.
Sourcepub unsafe fn enumeratorForContainerItemIdentifier_error(
&self,
container_item_identifier: &NSFileProviderItemIdentifier,
) -> Result<Retained<ProtocolObject<dyn NSFileProviderEnumerator>>, Retained<NSError>>
Available on crate features NSFileProviderEnumerating
and NSFileProviderItem
only.
pub unsafe fn enumeratorForContainerItemIdentifier_error( &self, container_item_identifier: &NSFileProviderItemIdentifier, ) -> Result<Retained<ProtocolObject<dyn NSFileProviderEnumerator>>, Retained<NSError>>
NSFileProviderEnumerating
and NSFileProviderItem
only.Create an enumerator for an item.
When the user opens the browse tab of the UIDocumentsBrowserViewController and selects a file provider, this is called with NSFileProviderRootContainerItemIdentifier, and -[NSFileProviderEnumerator enumerateItemsForObserver:startingAtPage:] is immediately called to list the first items available under at the root level of the file provider.
As the user navigates down into directories, new enumerators are created with this method, passing in the itemIdentifier of those directories. Past enumerators are then invalidated.
This method is also called with NSFileProviderWorkingSetContainerItemIdentifier, which is enumerated with -[NSFileProviderEnumerator enumerateChangesForObserver:fromSyncAnchor:]. That enumeration is special in that it isn’t driven by the UIDocumentsBrowserViewController. It happens in the background to sync the working set down to the device.
This is also used to subscribe to live updates for a single document. In that case, -[NSFileProviderEnumerator enumerateChangesToObserver:fromSyncAnchor:] will be called and the enumeration results shouldn’t include items other than the very item that the enumeration was started on.
If returning nil, you must set the error out parameter.
Source§impl NSFileProviderExtension
NSFileProviderService.
A file provider can override the method in this category to return service
sources that provide custom communication channels to client applications.
The service sources must be tied to the item identified by
itemIdentifier.
Client applications can retrieve the list of supported services by calling
-[NSFileManager
getFileProviderServicesForItemAtURL:] for a specific item URL.
impl NSFileProviderExtension
NSFileProviderService.
A file provider can override the method in this category to return service
sources that provide custom communication channels to client applications.
The service sources must be tied to the item identified by
itemIdentifier.
Client applications can retrieve the list of supported services by calling
-[NSFileManager
getFileProviderServicesForItemAtURL:] for a specific item URL.
pub unsafe fn supportedServiceSourcesForItemIdentifier_error( &self, item_identifier: &NSFileProviderItemIdentifier, ) -> Result<Retained<NSArray<ProtocolObject<dyn NSFileProviderServiceSource>>>, Retained<NSError>>
NSFileProviderService
and NSFileProviderItem
only.Source§impl NSFileProviderExtension
NSFileProviderThumbnailing.
impl NSFileProviderExtension
NSFileProviderThumbnailing.
Sourcepub unsafe fn fetchThumbnailsForItemIdentifiers_requestedSize_perThumbnailCompletionHandler_completionHandler(
&self,
item_identifiers: &NSArray<NSFileProviderItemIdentifier>,
size: CGSize,
per_thumbnail_completion_handler: &DynBlock<dyn Fn(NonNull<NSFileProviderItemIdentifier>, *mut NSData, *mut NSError)>,
completion_handler: &DynBlock<dyn Fn(*mut NSError)>,
) -> Retained<NSProgress>
Available on crate features NSFileProviderThumbnailing
and NSFileProviderItem
and block2
and objc2-core-foundation
only.
pub unsafe fn fetchThumbnailsForItemIdentifiers_requestedSize_perThumbnailCompletionHandler_completionHandler( &self, item_identifiers: &NSArray<NSFileProviderItemIdentifier>, size: CGSize, per_thumbnail_completion_handler: &DynBlock<dyn Fn(NonNull<NSFileProviderItemIdentifier>, *mut NSData, *mut NSError)>, completion_handler: &DynBlock<dyn Fn(*mut NSError)>, ) -> Retained<NSProgress>
NSFileProviderThumbnailing
and NSFileProviderItem
and block2
and objc2-core-foundation
only.The system calls this method to fetch thumbnails.
The
perThumbnailCompletionHandler
should be called for each thumbnail, and
completionHandler
only after all the per thumbnail completion blocks.
In the event of a global error, the implementation is allowed to skip calling
the
perThumbnailCompletionHandler
for individual thumbnails. In that case,
the
completionHandler's
error parameter would apply to all item identifiers
for which
perThumbnailCompletionHandler
had not been called.
If there is no thumbnail for a given item, the
perThumbnailCompletionHandler
should be called with its
imageData
and
error
parameters both
set to nil.
If the system decides that an in-flight thumbnail request is not needed anymore,
it will call the returned
NSProgress
object’s
-cancel
method,
at which time the implementation should clean up any held resources.
The system will cache the thumbnail for the item, and the cache will be invalidated when itemVersion.contentVersion changes.
Methods from Deref<Target = NSObject>§
Sourcepub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
Handle messages the object doesn’t recognize.
See Apple’s documentation for details.
Methods from Deref<Target = AnyObject>§
Sourcepub fn class(&self) -> &'static AnyClass
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());
Sourcepub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
👎Deprecated: this is difficult to use correctly, use Ivar::load
instead.
pub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
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.
Sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: DowncastTarget,
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§
Source§impl AsRef<AnyObject> for NSFileProviderExtension
impl AsRef<AnyObject> for NSFileProviderExtension
Source§impl AsRef<NSObject> for NSFileProviderExtension
impl AsRef<NSObject> for NSFileProviderExtension
Source§impl Borrow<AnyObject> for NSFileProviderExtension
impl Borrow<AnyObject> for NSFileProviderExtension
Source§impl Borrow<NSObject> for NSFileProviderExtension
impl Borrow<NSObject> for NSFileProviderExtension
Source§impl ClassType for NSFileProviderExtension
impl ClassType for NSFileProviderExtension
Source§const NAME: &'static str = "NSFileProviderExtension"
const NAME: &'static str = "NSFileProviderExtension"
Source§type ThreadKind = <<NSFileProviderExtension as ClassType>::Super as ClassType>::ThreadKind
type ThreadKind = <<NSFileProviderExtension as ClassType>::Super as ClassType>::ThreadKind
Source§impl Debug for NSFileProviderExtension
impl Debug for NSFileProviderExtension
Source§impl Deref for NSFileProviderExtension
impl Deref for NSFileProviderExtension
Source§impl Hash for NSFileProviderExtension
impl Hash for NSFileProviderExtension
Source§impl Message for NSFileProviderExtension
impl Message for NSFileProviderExtension
Source§impl NSObjectProtocol for NSFileProviderExtension
impl NSObjectProtocol for NSFileProviderExtension
Source§fn isEqual(&self, other: Option<&AnyObject>) -> bool
fn isEqual(&self, other: Option<&AnyObject>) -> bool
Source§fn hash(&self) -> usize
fn hash(&self) -> usize
Source§fn isKindOfClass(&self, cls: &AnyClass) -> bool
fn isKindOfClass(&self, cls: &AnyClass) -> bool
Source§fn is_kind_of<T>(&self) -> bool
fn is_kind_of<T>(&self) -> bool
isKindOfClass
directly, or cast your objects with AnyObject::downcast_ref