CustomSensor
CustomSensor
CustomSensor
CustomSensor
Class
Definition
Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Prerelease APIs are identified by a Prerelease label.
[Contains prerelease APIs.]
Represents a custom sensor.
This class reuses the same ReadingChanged event mechanism and the same common properties (DeviceId, ReportInterval ) as the Windows.Devices.Sensors classes (Accelerometer, Gyrometer, Magnetometer, and so on).
public : sealed class CustomSensor : ICustomSensorpublic sealed class CustomSensor : ICustomSensorPublic NotInheritable Class CustomSensor Implements ICustomSensor// You can use this class in JavaScript.
- Attributes
| Device family |
Windows 10 (introduced v10.0.10240.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v1)
|
Properties
DeviceId DeviceId DeviceId DeviceId
Gets the device identifier of the sensor.
public : PlatForm::String DeviceId { get; }public string DeviceId { get; }Public ReadOnly Property DeviceId As string// You can use this property in JavaScript.
- Value
- PlatForm::String string string string
The device identifier.
MaxBatchSize MaxBatchSize MaxBatchSize MaxBatchSize
Prerelease. Gets the maximum number of events that can be batched by the sensor.
public : unsigned int MaxBatchSize { get; }public uint MaxBatchSize { get; }Public ReadOnly Property MaxBatchSize As uint// You can use this property in JavaScript.
- Value
- unsigned int uint uint uint
The maximum number of batched events.
| Device family |
Windows 10 Insider Preview (introduced v10.0.16257.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v5)
|
Remarks
A sensor may not support batched data collection. In that case, this property will be 0. Otherwise, this determines the maximum number of events the sensor can gather before submitting them. This in turn will determine the maximum supported ReportLatency. The maximum latency equals the ReportInterval times the MaxBatchSize. For more information about sensor batching, see Sensors.
MinimumReportInterval MinimumReportInterval MinimumReportInterval MinimumReportInterval
Gets the minimum report interval that is supported by the sensor.
public : unsigned int MinimumReportInterval { get; }public uint MinimumReportInterval { get; }Public ReadOnly Property MinimumReportInterval As uint// You can use this property in JavaScript.
- Value
- unsigned int uint uint uint
The minimum report interval that is supported by the sensor.
ReportInterval ReportInterval ReportInterval ReportInterval
Gets or sets the current report interval for the sensor.
public : unsigned int ReportInterval { get; set; }public uint ReportInterval { get; set; }Public ReadWrite Property ReportInterval As uint// You can use this property in JavaScript.
- Value
- unsigned int uint uint uint
The current report interval for the sensor.
Remarks
The report interval is specified in milliseconds.
The report interval will be set to a default value that will vary based on the sensor driver’s implementation. If your app doesn't want to use this default value, set the report interval to a non-zero value prior to registering an event handler or calling GetCurrentReading. The sensor will then attempt to allocate resources to satisfy the app’s requirements but the sensor also has to balance the needs of other apps using the sensor.
Changes to the report interval after an event handler has been registered or GetCurrentReading has been called may apply to the delivery of subsequent sensor readings.
Conversely, when an app is finished with the sensor, we recommend that it explicitly return the sensor to its default report interval by setting it to zero. This is important for power conservation, especially when using a language that may keep the sensor object active for an indefinite period prior to garbage collection.
We recommend that the app consult the MinimumReportInterval property prior to setting the report interval to ensure that the sensor can honor the requested report interval. Setting a value below the minimum supported interval will either trigger an exception or have undefined results.
Although the app can set this value to request a particular report interval, the driver will determine the actual report interval, based on internal logic. For example, the driver might use the shortest report interval that is requested by any caller.
Setting a value of zero requests the driver to use its default report interval. As with requesting a specific interval, the driver may choose a different interval based on other client requests and internal logic.
The custom sensor platform automatically sets the change sensitivity for custom sensors based on the current report interval. This table specifies the change sensitivity values for given intervals.
| Current report interval (specified in milliseconds) | Change sensitivity (specified as G force) |
|---|---|
| 1 ms – 16 ms | 0.01 G |
| 17 ms – 32 ms | 0.02 G |
| >= 33 ms | 0.05 G |
ReportLatency ReportLatency ReportLatency ReportLatency
Prerelease. Gets or sets the delay between batches of sensor information.
public : unsigned int ReportLatency { get; set; }public uint ReportLatency { get; set; }Public ReadWrite Property ReportLatency As uint// You can use this property in JavaScript.
- Value
- unsigned int uint uint uint
The delay between batches of sensor information in milliseconds.
| Device family |
Windows 10 Insider Preview (introduced v10.0.16257.0)
|
| API contract |
Windows.Foundation.UniversalApiContract (introduced v5)
|
Remarks
This property is in reference to the frequency of ReadingChanged events.
Not all sensors support ReportLatency. If the sensor does not support this property, it will function the same as if you set this value to 0. Setting this value to 0 will use the default latency for the sensor.
If you set ReportLatency to a value higher than the maximum supported latency, the sensor will use the maximum supported latency. However, this property will not change in value. The maximum possible ReportLatency equals the MaxBatchSize times the ReportInterval.
Be aware that multiple applications could be dependent on a single sensor. Each of those applications can set a different value for ReportLatency. In this scenario, the sensor needs to try to accommodate the lowest value for ReportLatency. Because of this, the actual latency may not match the latency defined by this property in your application. This property corresponds to your ideal latency, which may not be the same latency on the sensor.
For more information about sensor batching, see Sensors.
Methods
FromIdAsync(String) FromIdAsync(String) FromIdAsync(String) FromIdAsync(String)
Asynchronously obtains the sensor from its identifier.
public : static IAsyncOperation<CustomSensor> FromIdAsync(PlatForm::String sensorId)public static IAsyncOperation<CustomSensor> FromIdAsync(String sensorId)Public Static Function FromIdAsync(sensorId As String) As IAsyncOperation( Of CustomSensor )// You can use this method in JavaScript.
- sensorId
- PlatForm::String String String String
The sensor identifier.
Returns the CustomSensor object from its identifier.
GetCurrentReading() GetCurrentReading() GetCurrentReading() GetCurrentReading()
Gets the current sensor reading.
public : CustomSensorReading GetCurrentReading()public CustomSensorReading GetCurrentReading()Public Function GetCurrentReading() As CustomSensorReading// You can use this method in JavaScript.
The current sensor reading.
Remarks
An app may use this method to poll the sensor for the current reading as an alternative to registering a ReadingChanged event handler. This would be the preferred alternative for an app that updates its user interface at a specific frame rate. Whether polling once or many times, the app must establish a desired ReportInterval. This informs the sensor driver to allocate resources to satisfy subsequent polling requests.
Before using the return value from this method, the app must first check that the value is not null. (If the value is null and you attempt to retrieve it, Windows will generate an exception.)
GetDeviceSelector(Guid) GetDeviceSelector(Guid) GetDeviceSelector(Guid) GetDeviceSelector(Guid)
Gets the device selector from the given interface identifier.
public : static PlatForm::String GetDeviceSelector(PlatForm::Guid interfaceId)public static string GetDeviceSelector(Guid interfaceId)Public Static Function GetDeviceSelector(interfaceId As Guid) As string// You can use this method in JavaScript.
- interfaceId
- PlatForm::Guid Guid Guid Guid
The interface Guid that is associated with the custom sensor. This Guid is defined and registered by the sensor.
Returns the device selector, if it exists; otherwise, null.
Events
ReadingChanged ReadingChanged ReadingChanged ReadingChanged
Occurs each time the sensor reports a new sensor reading.
public : event TypedEventHandler ReadingChanged<CustomSensor, CustomSensorReadingChangedEventArgs>public event TypedEventHandler ReadingChanged<CustomSensor, CustomSensorReadingChangedEventArgs>Public Event ReadingChanged<CustomSensor, CustomSensorReadingChangedEventArgs>// You can use this event in JavaScript.
Remarks
An app may register this event handler to obtain sensor readings. The app must establish a desired ReportInterval. This informs the sensor driver to allocate resources to satisfy the requirements of the app.