Struct CKShare 

pub struct CKShare { /* private fields */ }

Available on crate features CKRecord and CKShare only.

Like CKRecords, CKShares can store arbitrary key-value pairs. They are modified and fetched in the same manner. A share, its root record, and its root record’s children records will only appear in a participant’s CKFetchRecordChangesOperation’s results after the share has been accepted by that participant. Clients have access to the share (and optionally the root record) before accepting a share, via the CKShareMetadata object. Note that in order to access a root record before accepting a share, you must run a CKFetchShareMetadataOperation requesting the root record. A CKShare will appear in a CKFetchRecordChangesOperation’s results set whenever the participant list is updated. For that reason, you shouldn’t place heavy key-value pairs in it.

See also Apple’s documentation

Implementations

impl CKShare

pub unsafe fn initWithRootRecord( this: Allocated<Self>, root_record: &CKRecord, ) -> Retained<Self>

When saving a newly created CKShare, you must save the share and its rootRecord in the same CKModifyRecordsOperation batch.

pub unsafe fn initWithRootRecord_shareID( this: Allocated<Self>, root_record: &CKRecord, share_id: &CKRecordID, ) -> Retained<Self>

Available on crate feature CKRecordID only.

pub unsafe fn initWithRecordZoneID( this: Allocated<Self>, record_zone_id: &CKRecordZoneID, ) -> Retained<Self>

Available on crate feature CKRecordZoneID only.

Creates a zone-wide CKShare.A zone-wide CKSharecan only exist in a zone with sharing capability CKRecordZoneCapabilityZoneWideSharing.Only one such share can exist in a zone at a time.

All records in this zone will appear in a participant’s CKFetchRecordZoneChangesOperationresults in the shared database after the share has been accepted by the participant.

Since these shares do not have an associated root record, shouldFetchRootRecordand rootRecordDesiredKeysare always ignored when running a CKFetchShareMetadataOperationon a zone-wide share URL. Additionally, rootRecordIDon the resulting CKShareMetadatais always absent.

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

Safety

a_decoder possibly has further requirements.

pub unsafe fn publicPermission(&self) -> CKShareParticipantPermission

Available on crate feature CKShareParticipant only.

Defines what permission a user has when not explicitly added to the share.

Shares with publicPermissionmore permissive than CKShareParticipantPermissionNonecan be joined by any user with access to the share’s shareURL. By default, public permission is CKShareParticipantPermissionNone.Changing the public permission to CKShareParticipantPermissionReadOnlyor CKShareParticipantPermissionReadWritewill result in all pending participants being removed. Already-accepted participants will remain on the share. Changing the public permission to CKShareParticipantPermissionNonewill result in all participants being removed from the share. You may subsequently choose to call addParticipant:before saving the share, those participants will be added to the share.

pub unsafe fn setPublicPermission( &self, public_permission: CKShareParticipantPermission, )

Available on crate feature CKShareParticipant only.

Setter for publicPermission.

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

A URL that can be used to invite participants to this share.

Only available after share record has been saved to the server. This url is stable, and is tied to the rootRecord. That is, if you share a rootRecord, delete the share, and re-share the same rootRecord via a newly created share, that newly created share’s url will be identical to the prior share’s url

pub unsafe fn participants(&self) -> Retained<NSArray<CKShareParticipant>>

Available on crate feature CKShareParticipant only.

All participants on the share that the current user has permissions to see.

At the minimum that will include the owner and the current user.

pub unsafe fn owner(&self) -> Retained<CKShareParticipant>

Available on crate feature CKShareParticipant only.

Convenience methods for fetching special users from the participant array

pub unsafe fn currentUserParticipant( &self, ) -> Option<Retained<CKShareParticipant>>

Available on crate feature CKShareParticipant only.

pub unsafe fn addParticipant(&self, participant: &CKShareParticipant)

Available on crate feature CKShareParticipant only.

If a participant with a matching userIdentity already exists, then that existing participant’s properties will be updated; no new participant will be added. A CKShareParticipant instance that has already been added to one CKShare cannot be added to another, unless it is removed from the first CKShare through removeParticipant. In order to modify the list of participants, a share must have publicPermission set to CKShareParticipantPermissionNone.That is, you cannot mix-and-match private users and public users in the same share.

See: CKShareParticipantRole

pub unsafe fn removeParticipant(&self, participant: &CKShareParticipant)

Available on crate feature CKShareParticipant only.

It’s not allowed to call removeParticipant on a CKShare with a CKShareParticipant that has never been added to that share through addParticipant.

pub unsafe fn oneTimeURLForParticipantID( &self, participant_id: &NSString, ) -> Option<Retained<NSURL>>

Invitation URLs that can be used by any receiver to claim the associated participantID and join the share.

Only available after a share record has been saved to the server for participants created via CKShareParticipant/oneTimeURLParticipant. One-time URLs are stable, and tied to the associated participantIDs as long as the participant is part of the share. Typically, a recipient user invited via their handle is provided a URL directly by the share’s owner. However, any user can also use a one-time URL in the same manner to fetch share metadata and accept the share. After share acceptance, the one-time URL becomes functionally equivalent to the regular URL.

• Parameters:
• participantID: The CKShareParticipant/participantID corresponding to the CKShareParticipant/oneTimeURLParticipant added to the share.

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

These superclass-provided initializers are not allowed for CKShare

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

pub unsafe fn initWithRecordType( this: Allocated<Self>, record_type: &CKRecordType, ) -> Retained<Self>

pub unsafe fn initWithRecordType_recordID( this: Allocated<Self>, record_type: &CKRecordType, record_id: &CKRecordID, ) -> Retained<Self>

Available on crate feature CKRecordID only.

pub unsafe fn initWithRecordType_zoneID( this: Allocated<Self>, record_type: &CKRecordType, zone_id: &CKRecordZoneID, ) -> Retained<Self>

Available on crate feature CKRecordZoneID only.

pub unsafe fn requesters(&self) -> Retained<NSArray<CKShareAccessRequester>>

Available on crate feature CKShareAccessRequester only.

A list of all uninvited users who have requested access to this share.

When share access requests are allowed, uninvited users can request to join the share. All pending access requests appear in this array. Each requester is returned with name components and either an email or phone number.

Either share owners or administrators can respond to these access requests.

Responding to Access Requests:

• Approve Requesters:

• Fetch the participant information by running CKFetchShareParticipantsOperation with the requester’s CKShareAccessRequester/participantLookupInfo.

• Add the resulting participant to the share.

• Deny Requesters:

• Use CloudKit/CKShare/denyRequesters: to remove the requester from the requesters list.

• Block Requesters:

• Use CloudKit/CKShare/blockRequesters: to block requesters.

• Blocking a requester prevents them from sending future access requests to the share.

pub unsafe fn blockedIdentities( &self, ) -> Retained<NSArray<CKShareBlockedIdentity>>

Available on crate feature CKShareBlockedIdentity only.

A list of users blocked from requesting access to this share.

Identities remain in this list until an owner or administrator calls CloudKit/CKShare/unblockIdentities:.

pub unsafe fn allowsAccessRequests(&self) -> bool

Indicates whether uninvited users can request access to this share.

By default, this property is set to NO. When set to YES, uninvited users can request access to the share if they discover the share URL. When set to NO, the server prevents uninvited users from requesting access and does not indicate whether the share exists.

Only the share owner or an administrator can modify this property. Attempts by other participants to modify this property result in an exception.

pub unsafe fn setAllowsAccessRequests(&self, allows_access_requests: bool)

Setter for allowsAccessRequests.

pub unsafe fn denyRequesters( &self, requesters: &NSArray<CKShareAccessRequester>, )

Available on crate feature CKShareAccessRequester only.

Denies access requests from specified users.

Use this method to deny pending access requests from uninvited users. Denied requesters are removed from the CloudKit/CKShare/requesters array. To persist the changes, save the share to the server after calling this method.

After denial, requesters can still submit new access requests unless explicitly blocked using CloudKit/CKShare/blockRequesters:.

Only the share owner or an administrator can invoke this method. Attempts by other participants result in an exception.

• Parameter requesters: An array of CKShareAccessRequester objects to deny.

pub unsafe fn blockRequesters( &self, requesters: &NSArray<CKShareAccessRequester>, )

Available on crate feature CKShareAccessRequester only.

Blocks specified users from requesting access to this share.

Blocking prevents users from submitting future access requests and removes existing participants from the share. Blocked requesters appear in the CloudKit/CKShare/blockedIdentities array.

To persist this change, save the share to the server after calling this method.

Only the share owner or an administrator can invoke this method. Attempts by other participants result in an exception.

• Parameter requesters: An array of CKShareAccessRequester objects to block.

pub unsafe fn unblockIdentities( &self, blocked_identities: &NSArray<CKShareBlockedIdentity>, )

Available on crate feature CKShareBlockedIdentity only.

Unblocks previously blocked users, allowing them to request access again.

Use this method to remove specified identities from the CloudKit/CKShare/blockedIdentities array. Unblocked identities can request access again if access requests are enabled.

To persist this change, save the share to the server after calling this method.

Only the share owner or an administrator can invoke this method. Attempts by other participants result in an exception.

• Parameter blockedIdentities: An array of CKShareBlockedIdentity objects to unblock.

Methods from Deref<Target = CKRecord>

pub unsafe fn recordType(&self) -> Retained<CKRecordType>

pub unsafe fn recordID(&self) -> Retained<CKRecordID>

Available on crate feature CKRecordID only.

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

Change tags are updated by the server to a unique value every time a record is modified. A different change tag necessarily means that the contents of the record are different.

pub unsafe fn creatorUserRecordID(&self) -> Option<Retained<CKRecordID>>

Available on crate feature CKRecordID only.

This is a User Record recordID, identifying the user that created this record.

pub unsafe fn creationDate(&self) -> Option<Retained<NSDate>>

pub unsafe fn lastModifiedUserRecordID(&self) -> Option<Retained<CKRecordID>>

Available on crate feature CKRecordID only.

This is a User Record recordID, identifying the user that last modified this record.

pub unsafe fn modificationDate(&self) -> Option<Retained<NSDate>>

pub unsafe fn objectForKey( &self, key: &CKRecordFieldKey, ) -> Option<Retained<ProtocolObject<dyn CKRecordValue>>>

In addition to objectForKey:and setObject:forKey:,dictionary-style subscripting ( record[key]and

 record[key] = value

) can be used to get and set values. Acceptable value object classes are:

• CKReference
• CKAsset
• CLLocation
• NSData
• NSDate
• NSNumber
• NSString
• NSArray containing objects of any of the types above

Any other classes will result in an exception with name NSInvalidArgumentException. Whenever possible, value objects will be copied when set on a record.

Field keys starting with ‘’ are reserved. Attempting to set a key prefixed with a ‘’ will result in an error.

Key names roughly match C variable name restrictions. They must begin with an ASCII letter and can contain ASCII letters and numbers and the underscore character. The maximum key length is 255 characters.

pub unsafe fn setObject_forKey( &self, object: Option<&ProtocolObject<dyn CKRecordValue>>, key: &CKRecordFieldKey, )

pub unsafe fn allKeys(&self) -> Retained<NSArray<CKRecordFieldKey>>

pub unsafe fn allTokens(&self) -> Retained<NSArray<NSString>>

A special property that returns an array of token generated from all the string field values in the record.

These tokens have been normalized for the current locale, so they are suitable for performing full-text searches.

pub unsafe fn objectForKeyedSubscript( &self, key: &CKRecordFieldKey, ) -> Option<Retained<ProtocolObject<dyn CKRecordValue>>>

pub unsafe fn setObject_forKeyedSubscript( &self, object: Option<&ProtocolObject<dyn CKRecordValue>>, key: &CKRecordFieldKey, )

pub unsafe fn changedKeys(&self) -> Retained<NSArray<CKRecordFieldKey>>

A list of keys that have been modified on the local CKRecord instance

pub unsafe fn encodeSystemFieldsWithCoder(&self, coder: &NSCoder)

CKRecordsupports NSSecureCoding.When you invoke encodeWithCoder:on a CKRecord,it encodes all its values. Including the record values you’ve set. If you want to store a CKRecordinstance locally, AND you’re already storing the record values locally, that’s overkill. In that case, you can use encodeSystemFieldsWithCoder:.This will encode all parts of a CKRecordexcept the record keys / values you have access to via the changedKeysand objectForKey:methods. If you use initWithCoder:to reconstitute a CKRecordyou encoded via encodeSystemFieldsWithCoder:,then be aware that

• any record values you had set on the original instance, but had not saved, will be lost
• the reconstituted CKRecord’s changedKeyswill be empty

Safety

coder possibly has further requirements.

pub unsafe fn share(&self) -> Option<Retained<CKReference>>

Available on crate feature CKReference only.

The share property on a record can be set by creating a share using

 -[CKShare initWithRootRecord:]

.

The share property on a record will be removed when the corresponding CKShare is deleted from the server. Send this record in the same batch as the share delete and this record’s share property will be updated.

Sharing is only supported in zones with the CKRecordZoneCapabilitySharingcapability. The default zone does not support sharing.

If any records have a parent reference to this record, they are implicitly shared alongside this record.

Note that records in a parent chain must only exist within one share. If a child record already has a share reference set then you will get a CKErrorAlreadySharederror if you try to share any of that record’s parents.

Child records can be shared independently, even if they have a common parent. For example: Record A has two child records, Record B and Record C. A /
B C

These configurations are supported:

• Record A part of Share 1, or
• Record B part of Share 1, or
• Record C part of Share 1, or
• Record B part of Share 1, Record C part of Share 2

These configurations are not supported: Record A part of Share 1, Record B part of Share 2, or – This is not allowed because Record B would then be in two shares; Share 1 by being Record A’s child, and Share 2 Record A part of Share 1, Record C part of Share 2, or – This is not allowed because Record C would then be in two shares; Share 1 by being Record A’s child, and Share 2 Record A part of Share 1, Record B part of Share 2, Record C part of Share 3 – This is not allowed because both Record B and Record C would then each be in two shares.

Whenever possible, it is suggested that you construct your parent hierarchies such that you will only need to share the topmost record of that hierarchy.

pub unsafe fn parent(&self) -> Option<Retained<CKReference>>

Available on crate feature CKReference only.

Use a parent reference to teach CloudKit about the hierarchy of your records.

When a record is shared, all children of that record are also shared.

A parent record reference must have CKReferenceActionNoneset. You can create a separate reference with CKReferenceActionDeleteSelfif you would like your hierarchy cleaned up when the parent record is deleted.

The target of a parent reference must exist at save time - either already on the server, or part of the same CKModifyRecordsOperationbatch.

You are encouraged to set up the parentrelationships as part of normal record saves, even if you’re not planning on sharing records at this time. This allows you to share and unshare a hierarchy of records at a later date by only modifying the “top level” record, setting or clearing its sharereference.

pub unsafe fn setParent(&self, parent: Option<&CKReference>)

Available on crate feature CKReference only.

Setter for parent.

This is copied when set.

pub unsafe fn setParentReferenceFromRecord( &self, parent_record: Option<&CKRecord>, )

Convenience wrappers around creating a CKReferenceto a parent record. The resulting CKReferencewill have

 referenceAction = CKReferenceActionNone

pub unsafe fn setParentReferenceFromRecordID( &self, parent_record_id: Option<&CKRecordID>, )

Available on crate feature CKRecordID only.

pub unsafe fn encryptedValues( &self, ) -> Retained<ProtocolObject<dyn CKRecordKeyValueSetting>>

Any values set here will be locally encrypted before being saved to the server and locally decrypted when fetched from the server. Encryption and decryption is handled by the CloudKit framework. Key material necessary for decryption are available to the owner of the record, as well as any users that can access this record via a CKShare. All CKRecordValue types can be set here except CKAsset and CKReference.

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 CKShare

fn as_ref(&self) -> &AnyObject

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

impl AsRef<CKRecord> for CKShare

fn as_ref(&self) -> &CKRecord

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

impl AsRef<CKShare> for CKShare

fn as_ref(&self) -> &Self

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

impl AsRef<NSObject> for CKShare

fn as_ref(&self) -> &NSObject

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

impl Borrow<AnyObject> for CKShare

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<CKRecord> for CKShare

fn borrow(&self) -> &CKRecord

Immutably borrows from an owned value.

impl Borrow<NSObject> for CKShare

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for CKShare

const NAME: &'static str = "CKShare"

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

type Super = CKRecord

The superclass of this class.

type ThreadKind = <<CKShare 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 CKShare

type Result = CKShare

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

impl Debug for CKShare

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

Formats the value using the given formatter.

impl Deref for CKShare

type Target = CKRecord

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for CKShare

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 CKShare

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSCoding for CKShare

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 CKShare

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 CKShare

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 CKShare

fn supportsSecureCoding() -> bool

where Self: Sized + ClassType,

impl PartialEq for CKShare

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 CKShare

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

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

impl DowncastTarget for CKShare

impl Eq for CKShare