Struct CHHapticEngine

Source

pub struct CHHapticEngine { /* private fields */ }

Available on crate feature CHHapticEngine only.

Expand description

Represents the connection with the haptic server.

Implementations§

Source §

impl CHHapticEngine

Source

pub unsafe fn capabilitiesForHardware() -> Retained<ProtocolObject<dyn CHHapticDeviceCapability>>

Available on crate feature CHHapticDeviceCapability only.

Get the protocol that describes haptic and audio capabilities on this device.

Detailed description on the capability protocol is in CHHapticDeviceCapability.h.

Source

pub unsafe fn currentTime(&self) -> NSTimeInterval

The absolute time from which all current and future event times may be calculated. The units are seconds.

Source

pub unsafe fn stoppedHandler(&self) -> CHHapticEngineStoppedHandler

Available on crate feature block2 only.

The engine will call this block when it has stopped due to external causes (such as an audio session interruption or the app going into the background). It will NOT be called if the client calls stopWithCompletionHandler:.

In general, callbacks arrive on a non-main thread and it is the client’s responsibility to handle it in a thread-safe manner.

Source

pub unsafe fn setStoppedHandler( &self, stopped_handler: CHHapticEngineStoppedHandler, )

Available on crate feature block2 only.

Setter for stoppedHandler.

§Safety

stopped_handler must be a valid pointer.

Source

pub unsafe fn resetHandler(&self) -> CHHapticEngineResetHandler

Available on crate feature block2 only.

This block will called asynchronously if the haptic engine has to reset itself after a server failure.

In response to this handler being called, the client must release all haptic pattern players and recreate them. All CHHapticPattern objects and CHHapticEngine properties will have been preserved. In general, callbacks arrive on a non-main thread and it is the client’s responsibility to handle it in a thread-safe manner.

Source

pub unsafe fn setResetHandler(&self, reset_handler: CHHapticEngineResetHandler)

Available on crate feature block2 only.

Setter for resetHandler.

§Safety

reset_handler must be a valid pointer.

Source

pub unsafe fn playsHapticsOnly(&self) -> bool

If set to YES, the CHHapticEngine will ignore all events of type CHHapticEventTypeAudio and play only haptic events.

This behavior change will only take effect after the engine is stopped and restarted. The default is NO.

Source

pub unsafe fn setPlaysHapticsOnly(&self, plays_haptics_only: bool)

Setter for playsHapticsOnly.

Source

pub unsafe fn playsAudioOnly(&self) -> bool

If set to YES, the CHHapticEngine will ignore all events of type CHHapticEventTypeHaptic and play only audio events.

This behavior change will only take effect after the engine is stopped and restarted. The default is NO.

Source

pub unsafe fn setPlaysAudioOnly(&self, plays_audio_only: bool)

Setter for playsAudioOnly.

Source

pub unsafe fn isMutedForAudio(&self) -> bool

When set to YES, the CHHapticEngine mutes audio playback from its players.

Default is NO.

Source

pub unsafe fn setIsMutedForAudio(&self, is_muted_for_audio: bool)

Setter for isMutedForAudio.

Source

pub unsafe fn isMutedForHaptics(&self) -> bool

When set to YES, the CHHapticEngine mutes haptic playback from its players.

Default is NO.

Source

pub unsafe fn setIsMutedForHaptics(&self, is_muted_for_haptics: bool)

Setter for isMutedForHaptics.

Source

pub unsafe fn isAutoShutdownEnabled(&self) -> bool

When auto shutdown is enabled, the haptic engine can start and stop the hardware dynamically, to conserve power.

To conserve power, it is advised that the client stop the haptic engine when not in use. But when auto shutdown is enabled, the haptic engine will stop the hardware if it was running idle for a certain duration, and restart it later when required. Note that, because this operation is dynamic, it may affect the start times of the pattern players (e.g. CHHapticPatternplayer), if the engine has to resume from its shutdown state.

This feature is disabled by default, but the client can enable it if needed.

Source

pub unsafe fn setAutoShutdownEnabled(&self, auto_shutdown_enabled: bool)

Setter for isAutoShutdownEnabled.

Source

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

Source

pub unsafe fn initAndReturnError( this: Allocated<Self>, ) -> Result<Retained<Self>, Retained<NSError>>

Create an instance of the CHHapticEngine.

More than one instance may exist within a process. Each will function independently of the others. CHHapticEngines created using this method will be associated with the device’s internal haptics hardware system, if one exists. For systems without internal haptics, this method will fail with the error CHHapticErrorCodeNotSupported. To access engine instances associated with external game controllers, see the GameController framework documentation for the hapticEngines property on the GCController class.

Source

pub unsafe fn initWithAudioSession_error( this: Allocated<Self>, audio_session: Option<&AVAudioSession>, ) -> Result<Retained<Self>, Retained<NSError>>

Available on crate feature objc2-avf-audio only.

Create an instance of an CHHapticEngine and associate it with an audio session. If ‘audioSession’ is nil, the engine will create its own.

More than one instance may exist within a process. Each will function independently of the others, but all CHHapticEngines which share an audio session will have identical audio behavior with regard to interruptions, etc. CHHapticEngines created using this method will be associated with the device’s internal haptics hardware system, if one exists. For systems without internal haptics, this method will fail with the error CHHapticErrorCodeNotSupported. To access engine instances associated with external game controllers, see the GameController framework documentation for the hapticEngines property on the GCController class.

Source

pub unsafe fn startWithCompletionHandler( &self, completion_handler: CHHapticCompletionHandler, )

Available on crate feature block2 only.

Asynchronously start the engine. The handler will be called when the operation completes.

The handler is guaranteed to be called on either success or failure.

§Safety

completion_handler must be a valid pointer or null.

Source

pub unsafe fn startAndReturnError(&self) -> Result<(), Retained<NSError>>

Start the engine and block until the engine has started.

This method will return NO upon failure, and outError will be set to a valid NSError describing the error.

Source

pub unsafe fn stopWithCompletionHandler( &self, completion_handler: CHHapticCompletionHandler, )

Available on crate feature block2 only.

Asynchronously stop the engine. The handler will be called when the operation completes.

The handler is guaranteed to be called on either success or failure.

§Safety

completion_handler must be a valid pointer or null.

Source

pub unsafe fn notifyWhenPlayersFinished( &self, finished_handler: CHHapticEngineFinishedHandler, )

Available on crate feature block2 only.

Tell the engine to asynchronously call the passed-in handler when all active pattern players associated with this engine have stopped.

Parameter finishedHandler: The block that will be called asynchronously. The return value of this block determines the action the engine will take when the block finishes (see CHHapticEngineFinishedHandler).

If additional players are started after this call is made, they will delay the callback. If no players are active or the engine is stopped, the callback will happen immediately.

§Safety

finished_handler must be a valid pointer.

Source

pub unsafe fn createPlayerWithPattern_error( &self, pattern: &CHHapticPattern, ) -> Result<Retained<ProtocolObject<dyn CHHapticPatternPlayer>>, Retained<NSError>>

Available on crate features CHHapticPattern and CHHapticPatternPlayer only.

Factory method for creating a CHHapticPatternPlayer from a CHHapticPattern.

Parameter pattern: The pattern to be played.

Source

pub unsafe fn createAdvancedPlayerWithPattern_error( &self, pattern: &CHHapticPattern, ) -> Result<Retained<ProtocolObject<dyn CHHapticAdvancedPatternPlayer>>, Retained<NSError>>

Available on crate features CHHapticPattern and CHHapticPatternPlayer only.

Factory method for creating a CHHapticAdvancedPatternPlayer from a CHHapticPattern.

Parameter pattern: The pattern to be played.

Source

pub unsafe fn unregisterAudioResource_error( &self, resource_id: CHHapticAudioResourceID, ) -> Result<(), Retained<NSError>>

Available on crate feature CHHapticEvent only.

Unregister and remove a previously-registered audio resource.

Parameter resourceID: The resource ID that was returned when the resource was registered.

Parameter outError: If the unregister operation fails, this will be set to a valid NSError describing the error.

Source

pub unsafe fn playPatternFromURL_error( &self, file_url: &NSURL, ) -> Result<(), Retained<NSError>>

Simple one-shot call to play a pattern specified by a URL.

Parameter fileURL: The URL of the file containing a haptic/audio pattern dictionary.

Parameter outError: If the operation fails, this will be set to a valid NSError describing the error.

The engine should be started prior to calling this method if low latency is desired. If this is not done, this method will start it, which can cause a significant delay.

Source

pub unsafe fn playPatternFromData_error( &self, data: &NSData, ) -> Result<(), Retained<NSError>>

Simple one-shot call to play a pattern specified by NSData.

Parameter data: The NSData containing a haptic/audio pattern dictionary.

Parameter outError: If the operation fails, this will be set to a valid NSError describing the error.

The engine should be started prior to calling this method if low latency is desired. If this is not done, this method will start it, which can cause a significant delay.

Source §

impl CHHapticEngine

Methods declared on superclass NSObject.

Source

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

Methods from Deref<Target = NSObject>§

Source

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

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>§

Source

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());

Source

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.

Source

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`
    }
}