Struct IOHIDUserDevice

Source

pub struct IOHIDUserDevice { /* private fields */ }

Available on crate feature hidsystem only.

Expand description

Apple’s documentation

Implementations§

Source §

impl IOHIDUserDevice

Source

pub unsafe fn with_properties( allocator: Option<&CFAllocator>, properties: &CFDictionary, options: IOOptionBits, ) -> Option<CFRetained<IOHIDUserDevice>>

Creates a virtual IOHIDDevice in the kernel.

The IOHIDUserDeviceRef represents a virtual IOHIDDevice. In order to create the device, the entitlement “com.apple.developer.hid.virtual.device” is required to validate the source of the device.

Parameter allocator: Allocator to be used during creation.

Parameter properties: Dictionary containing device properties indexed by keys defined in IOHIDKeys.h. At the bare minimum, the kIOHIDReportDescriptorKey key must be provided, where the value represents a CFData representation of the device’s report descriptor.

Parameter options: Options to be used when creating the device.

Returns: Returns a IOHIDUserDeviceRef on success.

§Safety

properties generics must be of the correct type.

Source

pub unsafe fn register_get_report_block( &self, block: IOHIDUserDeviceGetReportBlock, )

Available on crate features block2 and hid only.

Registers a block to receive get report requests.

The call to IOHIDUserDeviceRegisterGetReportBlock should be made before the device is activated. The device must be activated in order to receive get report requests.

Parameter device: Reference to a IOHIDUserDeviceRef

Parameter block: The block to be invoked for get report calls.

§Safety

block must be a valid pointer.

Source

pub unsafe fn register_set_report_block( &self, block: IOHIDUserDeviceSetReportBlock, )

Available on crate features block2 and hid only.

Registers a block to receive set report requests.

The call to IOHIDUserDeviceRegisterSetReportBlock should be made before the device is activated. The device must be activated in order to receive set report requests.

Parameter device: Reference to a IOHIDUserDeviceRef

Parameter block: The block to be invoked for set report calls.

§Safety

block must be a valid pointer.

Source

pub unsafe fn set_dispatch_queue(&self, queue: &DispatchQueue)

Available on crate feature dispatch2 only.

Sets the dispatch queue to be associated with the IOHIDUserDevice. This is necessary in order to receive asynchronous events from the kernel.

A call to IOHIDUserDeviceSetDispatchQueue should only be made once.

After a dispatch queue is set, the IOHIDUserDevice must make a call to activate via IOHIDUserDeviceActivate and cancel via IOHIDUserDeviceCancel. All calls to “Register” functions should be done before activation and not after cancellation.

Parameter device: Reference to an IOHIDUserDevice

Parameter queue: The dispatch queue to which the event handler block will be submitted.

§Safety

queue possibly has additional threading requirements.

Source

pub unsafe fn set_cancel_handler(&self, handler: dispatch_block_t)

Available on crate feature dispatch2 only.

Sets a cancellation handler for the dispatch queue associated with IOHIDUserDeviceScheduleWithDispatchQueue.

The cancellation handler (if specified) will be submitted to the device’s dispatch queue in response to a call to to IOHIDUserDeviceCancel after all the events have been handled.

The IOHIDUserDeviceRef should only be released after the device has been cancelled, and the cancel handler has been called. This is to ensure all asynchronous objects are released. For example:

dispatch_block_t cancelHandler = dispatch_block_create(0, ^{ CFRelease(device); }); IOHIDUserDeviceSetCancelHandler(device, cancelHandler); IOHIDUserDeviceActivate(device); IOHIDUserDeviceCancel(device);

Parameter device: Reference to an IOHIDUserDevice.

Parameter handler: The cancellation handler block to be associated with the dispatch queue.

§Safety

handler must be a valid pointer.

Source

pub fn activate(&self)

Activates the IOHIDUserDevice object.

An IOHIDUserDevice object associated with a dispatch queue is created in an inactive state. The object must be activated in order to receive asynchronous events from the kernel.

A dispatch queue must be set via IOHIDUserDeviceSetDispatchQueue before activation.

An activated device must be cancelled via IOHIDUserDeviceCancel. All calls to “Register” functions should be done before activation and not after cancellation.

Calling IOHIDUserDeviceActivate on an active IOHIDUserDevice has no effect.

Parameter device: Reference to an IOHIDUserDevice.

Source

pub fn cancel(&self)

Cancels the IOHIDUserDevice preventing any further invocation of its event handler block.

Cancelling prevents any further invocation of the event handler block for the specified dispatch queue, but does not interrupt an event handler block that is already in progress.

Explicit cancellation of the IOHIDUserDevice is required, no implicit cancellation takes place.

Calling IOHIDUserDeviceCancel on an already cancelled queue has no effect.

The IOHIDUserDeviceRef should only be released after the device has been cancelled, and the cancel handler has been called. This is to ensure all asynchronous objects are released. For example:

dispatch_block_t cancelHandler = dispatch_block_create(0, ^{ CFRelease(device); }); IOHIDUserDeviceSetCancelHandler(device, cancelHandler); IOHIDUserDeviceActivate(device); IOHIDUserDeviceCancel(device);

Parameter device: Reference to an IOHIDUserDevice

Source

pub fn property(&self, key: &CFString) -> Option<CFRetained<CFType>>

Obtains a property from the device.

Parameter key: The property key.

Returns: Returns the property on success.

Source

pub unsafe fn set_property(&self, key: &CFString, property: &CFType) -> bool

Sets a property on the device.

Parameter key: The property key.

Parameter value: The value of the property.

Returns: Returns true on success.

§Safety

property should be of the correct type.

Source

pub unsafe fn handle_report_with_time_stamp( &self, timestamp: u64, report: NonNull<u8>, report_length: CFIndex, ) -> IOReturn

Dispatches a report on behalf of the device.

Parameter device: Reference to a IOHIDUserDeviceRef.

Parameter timestamp: mach_absolute_time() based timestamp.

Parameter report: Buffer containing a HID report.

Parameter reportLength: The report buffer length.

Returns: Returns kIOReturnSuccess on success.

§Safety

report must be a valid pointer.

Methods from Deref<Target = CFType>§

Source

pub fn downcast_ref<T>(&self) -> Option<&T>
where T: ConcreteType,

Attempt to downcast the type to that of type T.

This is the reference-variant. Use CFRetained::downcast if you want to convert a retained type. See also ConcreteType for more details on which types support being converted to.

Source

pub fn retain_count(&self) -> usize

Get the reference count of the object.

This function may be useful for debugging. You normally do not use this function otherwise.

Beware that some things (like CFNumbers, small CFStrings etc.) may not have a normal retain count for optimization purposes, and can return usize::MAX in that case.