Thread Direct Listener
This module includes functions and definitions for Thread Direct (TD) Wake Listener.
Summary
The APIs in this module require Thread Direct Wake Listener functionality to be enabled via OPENTHREAD_CONFIG_TD_WAKE_LISTENER_ENABLE.
Typedefs |
|
|---|---|
otThreadDirectListenerConfig
|
typedefstruct otThreadDirectListenerConfig
Represents the configuration parameters for starting the Thread Direct Wake Listener. |
otThreadDirectListenerWakeCallback)(void *aContext)
|
typedefvoid(*
Pointer to a function that is called when a valid Thread Direct Wake frame is received by the Thread Direct Wake Listener. |
otThreadDirectListenerWakeInfo
|
typedef Represents information about a received Thread Direct Wake frame. |
Functions |
|
|---|---|
otThreadDirectListenerEstablishLink(otInstance *aInstance, const otThreadDirectLinkConfig *aLinkConfig)
|
Accepts the most recently received Wake frame on the Thread Direct Wake Listener and initiates establishment of a Thread Direct Link (
otThreadDirectLink). |
otThreadDirectListenerGetWakeInfo(otInstance *aInstance, otThreadDirectListenerWakeInfo *aWakeInfo)
|
Gets the information for the most recently received Wake frame on the Thread Direct Wake Listener.
|
otThreadDirectListenerIsRunning(otInstance *aInstance)
|
bool
Indicates whether the Thread Direct Wake Listener is currently running.
|
otThreadDirectListenerStart(otInstance *aInstance, const otThreadDirectListenerConfig *aConfig)
|
Starts the Thread Direct Wake Listener with the given configuration.
|
otThreadDirectListenerStop(otInstance *aInstance)
|
void
Stops the Thread Direct Wake Listener if it is currently running.
|
Macros |
|
|---|---|
OT_THREAD_DIRECT_LISTENER_CHANNEL 20
|
Default radio channel for Thread Direct Wake Listener.
|
OT_THREAD_DIRECT_LISTENER_DURATION 8000
|
Default listen duration in microseconds (8 milliseconds).
|
OT_THREAD_DIRECT_LISTENER_INTERVAL 1000000
|
Default listen interval in microseconds (1 second).
|
Structs |
|
|---|---|
| otThreadDirectListenerConfig |
Represents the configuration parameters for starting the Thread Direct Wake Listener. |
| otThreadDirectListenerWakeInfo |
Represents information about a received Thread Direct Wake frame. |
Typedefs
otThreadDirectListenerConfig
struct otThreadDirectListenerConfig otThreadDirectListenerConfig
Represents the configuration parameters for starting the Thread Direct Wake Listener.
To ensure forward compatibility as new fields may be added in future revisions, the caller MUST zero-initialize (memset to zero) this structure before setting its fields.
For mChannel, mInterval, and mDuration, setting a field to 0 selects its specification-mandated default (OT_THREAD_DIRECT_LISTENER_CHANNEL, OT_THREAD_DIRECT_LISTENER_INTERVAL, and OT_THREAD_DIRECT_LISTENER_DURATION, respectively). Specifying a value other than 0 or the specification-mandated default makes the operation non-compliant with the specification and is intended for testing purposes only. Callers SHOULD either leave these fields set to 0 or set them to the corresponding OT_THREAD_DIRECT_LISTENER_* constant.
otThreadDirectListenerWakeCallback
void(* otThreadDirectListenerWakeCallback)(void *aContext)
Pointer to a function that is called when a valid Thread Direct Wake frame is received by the Thread Direct Wake Listener.
Inside this callback (or afterward while the listener remains running), the caller can call otThreadDirectListenerGetWakeInfo() to retrieve details of the received Wake frame, and otThreadDirectListenerEstablishLink() to accept the wake and initiate a Thread Direct Link. The caller MAY also call otThreadDirectListenerStop() from within this callback to stop the listener.
| Details | |||
|---|---|---|---|
| Parameters |
|
otThreadDirectListenerWakeInfo
struct otThreadDirectListenerWakeInfo otThreadDirectListenerWakeInfo
Represents information about a received Thread Direct Wake frame.
Functions
otThreadDirectListenerEstablishLink
otThreadDirectLink * otThreadDirectListenerEstablishLink( otInstance *aInstance, const otThreadDirectLinkConfig *aLinkConfig )
Accepts the most recently received Wake frame on the Thread Direct Wake Listener and initiates establishment of a Thread Direct Link (otThreadDirectLink).
This function can be called from within otThreadDirectListenerWakeCallback or afterward while the listener remains running, and acts on the latest Wake frame reported via otThreadDirectListenerWakeCallback (and inspectable via otThreadDirectListenerGetWakeInfo()). This function returns NULL if the wake cannot be accepted (for example, if the listener is not running, no Wake frame has been received yet, the latest Wake frame was already accepted, the wake type is not OT_THREAD_DIRECT_WAKE_TYPE_TD_LINK, or a link could not be allocated/started).
The caller MUST zero-initialize (memset to zero) aLinkConfig before populating its fields. OpenThread copies aLinkConfig, so it does not need to persist after this call returns.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
||||
| Returns |
A pointer to the newly created
otThreadDirectLink, or NULL if the wake could not be accepted. |
otThreadDirectListenerGetWakeInfo
otError otThreadDirectListenerGetWakeInfo( otInstance *aInstance, otThreadDirectListenerWakeInfo *aWakeInfo )
Gets the information for the most recently received Wake frame on the Thread Direct Wake Listener.
This function can be called from within otThreadDirectListenerWakeCallback or afterward while the listener remains running. The mKey pointer in aWakeInfo remains valid as long as that key remains registered. If the key is unregistered (via otThreadDirectUnregisterKey() or otThreadDirectUnregisterAllKeys()), the stored Wake information is invalidated and subsequent calls to this function will return OT_ERROR_NOT_FOUND until a new Wake frame is received.
| Details | |||||||
|---|---|---|---|---|---|---|---|
| Parameters |
|
||||||
| Return Values |
|
otThreadDirectListenerIsRunning
bool otThreadDirectListenerIsRunning( otInstance *aInstance )
Indicates whether the Thread Direct Wake Listener is currently running.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
||||
| Return Values |
|
otThreadDirectListenerStart
otError otThreadDirectListenerStart( otInstance *aInstance, const otThreadDirectListenerConfig *aConfig )
Starts the Thread Direct Wake Listener with the given configuration.
When running, the listener schedules periodic receive windows during radio sleep intervals (when the radio is enabled and sleeping). Other MAC and radio operations (such as continuous reception when RxOnWhenIdle is enabled, active frame transmissions, scans, or CSL receive windows) take precedence over the listener's receive windows.
The caller MUST zero-initialize (memset to zero) aConfig before populating its fields to ensure forward compatibility with future revisions. OpenThread copies the contents of aConfig, so the structure does not need to persist after this function returns.
| Details | |||||||
|---|---|---|---|---|---|---|---|
| Parameters |
|
||||||
| Return Values |
|
otThreadDirectListenerStop
void otThreadDirectListenerStop( otInstance *aInstance )
Stops the Thread Direct Wake Listener if it is currently running.
This function can be called at any time, including from within otThreadDirectListenerWakeCallback. If the listener is not running, this function does nothing.
| Details | |||
|---|---|---|---|
| Parameters |
|
Macros
OT_THREAD_DIRECT_LISTENER_CHANNEL
OT_THREAD_DIRECT_LISTENER_CHANNEL 20
Default radio channel for Thread Direct Wake Listener.
OT_THREAD_DIRECT_LISTENER_DURATION
OT_THREAD_DIRECT_LISTENER_DURATION 8000
Default listen duration in microseconds (8 milliseconds).
OT_THREAD_DIRECT_LISTENER_INTERVAL
OT_THREAD_DIRECT_LISTENER_INTERVAL 1000000
Default listen interval in microseconds (1 second).
Resources
OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.