Struct WCSession 

pub struct WCSession { /* private fields */ }

Available on crate feature WCSession only.

–––––––––––––––– WCSession –––––––––––––––– The default session is used to communicate between two counterpart apps (i.e. iOS app and its native WatchKit extension). The session provides methods for sending, receiving, and tracking state.

On start up an app should set a delegate on the default session and call activate. This will allow the system to populate the state properties and deliver any outstanding background transfers.

See also Apple’s documentation

Implementations

impl WCSession

pub unsafe fn isSupported() -> bool

Check if session is supported on this iOS device. Session is always available on WatchOS

pub unsafe fn defaultSession() -> Retained<WCSession>

Use the default session for all transferring of content and state monitoring.

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

Use the default session instead.

pub unsafe fn delegate( &self, ) -> Option<Retained<ProtocolObject<dyn WCSessionDelegate>>>

A delegate must exist before the session will allow sends.

pub unsafe fn setDelegate( &self, delegate: Option<&ProtocolObject<dyn WCSessionDelegate>>, )

Setter for delegate.

This is a weak property.

pub unsafe fn activateSession(&self)

The default session must be activated on startup before the session’s properties contain correct values and will begin receiving delegate callbacks. Calling activate without a delegate set is undefined. If the WCSessionDelegate session:activationDidCompleteWithState:error: is implemented this method becomes an asynchronous call.

pub unsafe fn activationState(&self) -> WCSessionActivationState

The state of the current session

pub unsafe fn hasContentPending(&self) -> bool

Whether or not there is more content for the session to deliver

pub unsafe fn isPaired(&self) -> bool

Check if iOS device is paired to a watch

pub unsafe fn isWatchAppInstalled(&self) -> bool

Check if the user has the Watch app installed

pub unsafe fn isComplicationEnabled(&self) -> bool

Check if the user has the Watch app’s complication enabled

pub unsafe fn remainingComplicationUserInfoTransfers(&self) -> NSUInteger

The number of calls remaining to transferCurrentComplicationUserInfo: before the system starts transferring the complicationUserInfo as regular userInfos. If this is 0, the complicationUserInfo will be transferred as regular userInfos. Count will be 0 whenever the complication is not enabled

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

Use this directory to persist any data specific to the selected Watch. The location of the URL will change when the selected Watch changes. This directory will be deleted upon next launch if the watch app is uninstalled for the selected Watch, or that Watch is unpaired. If the watch app is not installed for the selected Watch the value will be nil.

pub unsafe fn isCompanionAppInstalled(&self) -> bool

Check if the companion app is installed on the paired iPhone. This only applies to Watch apps that can run independently.

pub unsafe fn isReachable(&self) -> bool

The counterpart app must be reachable for a send message to succeed.

pub unsafe fn iOSDeviceNeedsUnlockAfterRebootForReachability(&self) -> bool

Reachability in the Watch app requires the paired iOS device to have been unlocked at least once after reboot. This property can be used to determine if the iOS device needs to be unlocked. If the reachable property is set to NO it may be because the iOS device has rebooted and needs to be unlocked. If this is the case, the Watch can show a prompt to the user suggesting they unlock their paired iOS device.

pub unsafe fn sendMessage_replyHandler_errorHandler( &self, message: &NSDictionary<NSString, AnyObject>, reply_handler: Option<&DynBlock<dyn Fn(NonNull<NSDictionary<NSString, AnyObject>>)>>, error_handler: Option<&DynBlock<dyn Fn(NonNull<NSError>)>>, )

Available on crate feature block2 only.

Clients can use this method to send messages to the counterpart app. Clients wishing to receive a reply to a particular message should pass in a replyHandler block. If the message cannot be sent or if the reply could not be received, the errorHandler block will be invoked with an error. If both a replyHandler and an errorHandler are specified, then exactly one of them will be invoked. Messages can only be sent while the sending app is running. If the sending app exits before the message is dispatched the send will fail. If the counterpart app is not running the counterpart app will be launched upon receiving the message (iOS counterpart app only). The message dictionary can only accept the property list types.

Safety

message generic should be of the correct type.

pub unsafe fn sendMessageData_replyHandler_errorHandler( &self, data: &NSData, reply_handler: Option<&DynBlock<dyn Fn(NonNull<NSData>)>>, error_handler: Option<&DynBlock<dyn Fn(NonNull<NSError>)>>, )

Available on crate feature block2 only.

Clients can use this method to send message data. All the policies of send message apply to send message data. Send message data is meant for clients that have an existing transfer format and do not need the convenience of the send message dictionary.

pub unsafe fn applicationContext( &self, ) -> Retained<NSDictionary<NSString, AnyObject>>

Setting the applicationContext is a way to transfer the latest state of an app. After updating the applicationContext, the system initiates the data transfer at an appropriate time, which can occur after the app exits. The counterpart app will receive a delegate callback on next launch if the applicationContext has successfully arrived. If there is no app context, it should be updated with an empty dictionary. The applicationContext dictionary can only accept the property list types.

pub unsafe fn updateApplicationContext_error( &self, application_context: &NSDictionary<NSString, AnyObject>, ) -> Result<(), Retained<NSError>>

Safety

application_context generic should be of the correct type.

pub unsafe fn receivedApplicationContext( &self, ) -> Retained<NSDictionary<NSString, AnyObject>>

Stores the most recently received applicationContext from the counterpart app.

pub unsafe fn transferUserInfo( &self, user_info: &NSDictionary<NSString, AnyObject>, ) -> Retained<WCSessionUserInfoTransfer>

Available on crate feature WCSessionUserInfoTransfer only.

The system will enqueue the user info dictionary and transfer it to the counterpart app at an opportune time. The transfer of user info will continue after the sending app has exited. The counterpart app will receive a delegate callback on next launch if the file has successfully arrived. The userInfo dictionary can only accept the property list types.

Safety

user_info generic should be of the correct type.

pub unsafe fn transferCurrentComplicationUserInfo( &self, user_info: &NSDictionary<NSString, AnyObject>, ) -> Retained<WCSessionUserInfoTransfer>

Available on crate feature WCSessionUserInfoTransfer only.

Enqueues a user info dictionary containing the most current information for an enabled complication. If the app’s complication is enabled the system will try to transfer this user info immediately. Once a current complication user info is received the system will launch the Watch App Extension in the background and allow it to update the complication content. If the current user info cannot be transferred (i.e. devices disconnected, out of background launch budget, etc.) it will wait in the outstandingUserInfoTransfers queue until next opportune time. There can only be one current complication user info in the outstandingUserInfoTransfers queue. If a current complication user info is outstanding (waiting to transfer) and -transferCurrentComplicationUserInfo: is called again with new user info, the new user info will be tagged as current and the previously current user info will be untagged. The previous user info will however stay in the queue of outstanding transfers.

Safety

user_info generic should be of the correct type.

pub unsafe fn outstandingUserInfoTransfers( &self, ) -> Retained<NSArray<WCSessionUserInfoTransfer>>

Available on crate feature WCSessionUserInfoTransfer only.

Returns an array of user info transfers that are still transferring (i.e. have not been cancelled, failed, or been received by the counterpart app).

pub unsafe fn transferFile_metadata( &self, file: &NSURL, metadata: Option<&NSDictionary<NSString, AnyObject>>, ) -> Retained<WCSessionFileTransfer>

Available on crate feature WCSessionFile only.

The system will enqueue the file and transfer it to the counterpart app at an opportune time. The transfer of a file will continue after the sending app has exited. The counterpart app will receive a delegate callback on next launch if the file has successfully arrived. The metadata dictionary can only accept the property list types.

Safety

metadata generic should be of the correct type.

pub unsafe fn outstandingFileTransfers( &self, ) -> Retained<NSArray<WCSessionFileTransfer>>

Available on crate feature WCSessionFile only.

Returns an array of file transfers that are still transferring (i.e. have not been cancelled, failed, or been received by the counterpart app).

impl WCSession

Methods declared on superclass NSObject.

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 WCSession

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for WCSession

fn as_ref(&self) -> &NSObject

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

impl AsRef<WCSession> for WCSession

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for WCSession

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for WCSession

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for WCSession

const NAME: &'static str = "WCSession"

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

type Super = NSObject

The superclass of this class.

type ThreadKind = <<WCSession 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 Debug for WCSession

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

Formats the value using the given formatter.

impl Deref for WCSession

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for WCSession

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 WCSession

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for WCSession

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 PartialEq for WCSession

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 WCSession

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

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

impl DowncastTarget for WCSession

impl Eq for WCSession