GpioChangeReader GpioChangeReader GpioChangeReader GpioChangeReader Class

Definition

Represents a shared circular buffer between kernel mode and user mode into which high-resolution timestamps are placed when a general-purpose I/O (GPIO) pin changes value.

public : sealed class GpioChangeReader : IGpioChangeReader, IClosablepublic sealed class GpioChangeReader : IGpioChangeReader, IDisposablePublic NotInheritable Class GpioChangeReader Implements IGpioChangeReader, IDisposable// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Devices.DevicesLowLevelContract (introduced v3)

Remarks

Kernel mode places a timestamp into the buffer when a pin changes value, and user mode removes items from the buffer. An overflow occurs when there is no longer sufficient room in the buffer to place additional timestamps. Upon overflow, further events are not recorded, and the IsOverflowed property will return true.

This class is not thread-safe. Calling functions of this class concurrently from multiple threads will have unpredictable results.

Constructors

GpioChangeReader(GpioPin) GpioChangeReader(GpioPin) GpioChangeReader(GpioPin) GpioChangeReader(GpioPin)

Creates a new GpioChangeReader associated with the specified pin. Only a single GpioChangeReader may be associated with a pin at any given time.

public : GpioChangeReader(GpioPin pin)public GpioChangeReader(GpioPin pin)Public Sub New(pin As GpioPin)// You can use this method in JavaScript.
Parameters
pin
GpioPin GpioPin GpioPin GpioPin

The pin on which to read changes. The pin must have been opened in Exclusive mode, and cannot be associated with another change reader.

Remarks

The following exceptions can be thrown by this method:

  • E_POINTER - The pin passed in is null.
  • HRESULT_FROM_WIN32(ERROR_SHARING_VIOLATION) - The pin is already associated with a change reader. That change reader must be disposed before the pin can be associated with a new change reader.
  • E_ACCESSDENIED - The pin is not opened in Exclusive mode.

GpioChangeReader(GpioPin, Int32) GpioChangeReader(GpioPin, Int32) GpioChangeReader(GpioPin, Int32) GpioChangeReader(GpioPin, Int32)

Creates a new GpioChangeReader associated with the specified pin and with the specified minimum capacity for change records. Only a single GpioChangeReader may be associated with a pin at any given time.

public : GpioChangeReader(GpioPin pin, int minCapacity)public GpioChangeReader(GpioPin pin, Int32 minCapacity)Public Sub New(pin As GpioPin, minCapacity As Int32)// You can use this method in JavaScript.
Parameters
pin
GpioPin GpioPin GpioPin GpioPin

The pin on which to read changes. The pin must have been opened in Exclusive mode, and cannot be associated with another change reader.

minCapacity
int Int32 Int32 Int32

The minimum number of change records that the reader must be able to hold.

Remarks

The following exceptions can be thrown by this method:

  • E_POINTER - The pin passed in is null.
  • HRESULT_FROM_WIN32(ERROR_SHARING_VIOLATION) - The pin is already associated with a change reader. That change reader must be disposed before the pin can be associated with a new change reader.
  • E_ACCESSDENIED - The pin is not opened in Exclusive mode.

Properties

Capacity Capacity Capacity Capacity

Gets the maximum number of change records that the GpioChangeReader can store at one time.

public : int Capacity { get; }public int Capacity { get; }Public ReadOnly Property Capacity As int// You can use this property in JavaScript.
Value
int int int int

The maximum number of change records.

Remarks

When this maximum number of records is met, further changes will not be recorded and the IsOverflowed property will return true.

IsEmpty IsEmpty IsEmpty IsEmpty

Gets whether there are currently zero change records in the reader.

public : PlatForm::Boolean IsEmpty { get; }public bool IsEmpty { get; }Public ReadOnly Property IsEmpty As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

Returns true if there are zero change items in the reader, and false otherwise.

IsOverflowed IsOverflowed IsOverflowed IsOverflowed

Gets whether an attempt to place a change record into the reader's buffer has failed due to the buffer being full.

public : PlatForm::Boolean IsOverflowed { get; }public bool IsOverflowed { get; }Public ReadOnly Property IsOverflowed As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

Returns true if an attempt at placement has been unsuccessful, and false otherwise.

Remarks

Removing an item from the buffer will cause IsOverflowed to reset to false.

IsStarted IsStarted IsStarted IsStarted

Gets whether pin change recording is currently active.

public : PlatForm::Boolean IsStarted { get; }public bool IsStarted { get; }Public ReadOnly Property IsStarted As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

Returns true if pin changes are currently being recorded, and false otherwise.

Length Length Length Length

Gets the number of records currently in the change reader.

public : int Length { get; }public int Length { get; }Public ReadOnly Property Length As int// You can use this property in JavaScript.
Value
int int int int

The current number of change records.

Polarity Polarity Polarity Polarity

Gets or sets the polarity of transitions that will be recorded. The polarity may only be changed when pin change recording is not started.

public : GpioChangePolarity Polarity { get; set; }public GpioChangePolarity Polarity { get; set; }Public ReadWrite Property Polarity As GpioChangePolarity// You can use this property in JavaScript.
Value
GpioChangePolarity GpioChangePolarity GpioChangePolarity GpioChangePolarity

Rising or Falling. The default polarity value is Falling.

Remarks

Listening to a single edge (Falling or Rising) can be considerably more efficient than listening to both edges.

The following exceptions can be thrown when setting the polarity:

  • E_INVALIDARG - value is not a valid GpioChangePolarity value.
  • HRESULT_FROM_WIN32(ERROR_BAD_COMMAND) - change recording is currently active. Polarity can only be set before calling Start() or after calling Stop().

Methods

Clear() Clear() Clear() Clear()

Discards all change records from the reader's buffer.

public : void Clear()public void Clear()Public Function Clear() As void// You can use this method in JavaScript.

Remarks

This will also reset an active overflow condition, causing the IsOverflowed property to return false.

Close() Close() Close() Close()

Closes the change reader, releasing the associated memory buffer and disassociating the reader from its pin.

public : void Close()This member is not implemented in C#This member is not implemented in VB.Net// You can use this method in JavaScript.

Remarks

Calling this method will also cancel any pending WaitForItemsAsync() actions.

Dispose() Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

This member is not implemented in C++void Dispose()Sub Disposevoid Dispose()

GetAllItems() GetAllItems() GetAllItems() GetAllItems()

Removes and returns all items current in the reader's buffer.

public : IVector<GpioChangeRecord> GetAllItems()public IList<GpioChangeRecord> GetAllItems()Public Function GetAllItems() As IList( Of GpioChangeRecord )// You can use this method in JavaScript.
Returns
IVector<GpioChangeRecord> IList<GpioChangeRecord> IList<GpioChangeRecord> IList<GpioChangeRecord>

IVector<GpioChangeRecord >

The returned vector enables random access to all the change records removed from the buffer.

Remarks

This will also reset an active overflow condition, causing the IsOverflowed property to return false.

GetNextItem() GetNextItem() GetNextItem() GetNextItem()

Retrieves and removes the earliest inserted change record from the reader's buffer.

public : GpioChangeRecord GetNextItem()public GpioChangeRecord GetNextItem()Public Function GetNextItem() As GpioChangeRecord// You can use this method in JavaScript.
Returns

A GpioChangeRecord structure containing the timestamp and polarity (rising or falling) of the change.

Remarks

This will also reset an active overflow condition, causing the IsOverflowed property to return false.

The following exception can be thrown by this method:

  • HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS) - the reader's buffer is empty.

PeekNextItem() PeekNextItem() PeekNextItem() PeekNextItem()

Retrieves the earlier inserted change record from the reader's buffer, without removing it.

public : GpioChangeRecord PeekNextItem()public GpioChangeRecord PeekNextItem()Public Function PeekNextItem() As GpioChangeRecord// You can use this method in JavaScript.
Returns

A GpioChangeRecord structure containing the timestamp and polarity (rising or falling) of the change.

Remarks

The following exception can be thrown by this method:

  • HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS) - the reader's buffer is empty.

Start() Start() Start() Start()

Starts recording changes in pin polarity. This method may only be called when change recording is not already active.

public : void Start()public void Start()Public Function Start() As void// You can use this method in JavaScript.

Remarks

Calling Start() may enable or reconfigure interrupts for the pin.

The following exceptions can be thrown by this method:

  • HRESULT_FROM_WIN32(ERROR_BAD_COMMAND) - change reading is not currently active.
  • HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE) - the change reader or the associated pin has been disposed.

Stop() Stop() Stop() Stop()

Stop recording changes in pin polarity. This method may only be called when change recording is currently active.

public : void Stop()public void Stop()Public Function Stop() As void// You can use this method in JavaScript.

Remarks

Calling Stop() may disable or reconfigure interrupts for the pin.

The following exceptions can be thrown by this method:

  • HRESULT_FROM_WIN32(ERROR_BAD_COMMAND) - change reading has already been started.
  • HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE) - the change reader or the associated pin has been disposed.

WaitForItemsAsync(Int32) WaitForItemsAsync(Int32) WaitForItemsAsync(Int32) WaitForItemsAsync(Int32)

Waits for the buffer to fill with at least count number of items, at which point the async action will complete. This action is cancelable.

public : IAsyncAction WaitForItemsAsync(int count)public IAsyncAction WaitForItemsAsync(Int32 count)Public Function WaitForItemsAsync(count As Int32) As IAsyncAction// You can use this method in JavaScript.
Parameters
count
int Int32 Int32 Int32

The number of items with which the buffer must fill before the async operation completes.

Returns

Remarks

If the pin or change reader is closed while a wait is in progress, the async operation will be cancelled.

The following exceptions can be thrown by this method:

  • E_INVALIDARG - count is 0, or count is greater than the buffer's capacity.
  • HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE) - The change reader was disposed of the associated pin was closed.
  • HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED) - the async operation was canceled.