# Seeker

# Seeker

This module includes functions for the Thread Seeker role.

## Summary


> [!NOTE]
> **Note:** The functions in this module require `OPENTHREAD_CONFIG_SEEKER_ENABLE`.

<br />

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gac495b95f5f8aeb6dc6ce3625333321a3{ https://openthread.io/reference/group/api-seeker#group__api-seeker_1ggac495b95f5f8aeb6dc6ce3625333321a3a84ab272801e2dfa008758b70960a69db, https://openthread.io/reference/group/api-seeker#group__api-seeker_1ggac495b95f5f8aeb6dc6ce3625333321a3aeb12a152e5b1a022784357bfc1bb1640, https://openthread.io/reference/group/api-seeker#group__api-seeker_1ggac495b95f5f8aeb6dc6ce3625333321a3a3bffc2a40aa3ad8860e182648bb4113e }` | enumRepresents a verdict returned from the `otSeekerScanEvaluator` callback when evaluating a Discover Scan result. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-seeker#group__api-seeker_1ga71e19bcbea465ba9cb952ed55425bad3)(void *aContext, const otSeekerScanResult *aResult)` | typedef `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gac495b95f5f8aeb6dc6ce3625333321a3(*` Represents the callback function type used to evaluate a scan result or report the end of a scan. |
| `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gaef46900d4366d369fde7988ac5939828` | typedef `https://openthread.io/reference/struct/ot-active-scan-result` Represents a Discover Scan result. |
| `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gab9ef807b0361cb4da4b9d90694809119` | typedef `enum https://openthread.io/reference/group/api-seeker#group__api-seeker_1gac495b95f5f8aeb6dc6ce3625333321a3` Represents a verdict returned from the `otSeekerScanEvaluator` callback when evaluating a Discover Scan result. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gaa90f0048aa1ac84022948114aaa478d2(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint16_t` Gets the Seeker UDP port (unsecure port). |
| `https://openthread.io/reference/group/api-seeker#group__api-seeker_1ga74002d71f182dc734da4f1546c84cef1(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether or not the Seeker is running. |
| `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gaf5c8551cc2f3bbf936a1732323d1efaf(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aUdpPort)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets the Seeker UDP port (unsecure port). |
| `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gaddda11527b67907c022d90d8dde96224(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-sock-addr *aSockAddr)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Selects the next best candidate and prepares the connection. |
| `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gaec40e3e6915fd37fb0c81e1a0f11c703(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-seeker#group__api-seeker_1ga71e19bcbea465ba9cb952ed55425bad3 aScanEvaluator, void *aContext)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts the Seeker operation. |
| `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gab2c8ab54a519b5940a328dd495286b94(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Stops the Seeker operation. |

## Enumerations

### otSeekerVerdict

```
 otSeekerVerdict
```
Represents a verdict returned from the `otSeekerScanEvaluator` callback when evaluating a Discover Scan result.

| Properties ||
|---|---|
| `OT_SEEKER_ACCEPT` | The scan result is acceptable. |
| `OT_SEEKER_ACCEPT_PREFERRED` | The scan result is acceptable and preferred. |
| `OT_SEEKER_IGNORE` | The scan result should be ignored. |

## Typedefs

### otSeekerScanEvaluator

```
otSeekerVerdict(* otSeekerScanEvaluator)(void *aContext, const otSeekerScanResult *aResult)
```
Represents the callback function type used to evaluate a scan result or report the end of a scan.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aContext` | A pointer to the callback context. | | `[in] aResult` | A pointer to the scan result to evaluate, or `NULL` to indicate scan completion. | |
| **Returns** | The verdict for the scan result (Accept, AcceptPreferred, or Ignore). If `aResult` is `NULL` (scan complete), the return value is ignored. |

### otSeekerScanResult

```
otActiveScanResult otSeekerScanResult
```
Represents a Discover Scan result.

### otSeekerVerdict

```
enum otSeekerVerdict otSeekerVerdict
```
Represents a verdict returned from the `otSeekerScanEvaluator` callback when evaluating a Discover Scan result.

## Functions

### otSeekerGetUdpPort

```
uint16_t otSeekerGetUdpPort(
  otInstance *aInstance
)
```
Gets the Seeker UDP port (unsecure port).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| **Returns** | The Seeker UDP port. |

### otSeekerIsRunning

```
bool otSeekerIsRunning(
  otInstance *aInstance
)
```
Indicates whether or not the Seeker is running.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | The Seeker is active and running. | | `FALSE` | The Seeker is stopped. | |

### otSeekerSetUdpPort

```
otError otSeekerSetUdpPort(
  otInstance *aInstance,
  uint16_t aUdpPort
)
```
Sets the Seeker UDP port (unsecure port).

This UDP port can only be changed when the Seeker is not running.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aUdpPort` | The Seeker UDP port. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully set the Joiner/Seeker UDP port. | | `OT_ERROR_INVALID_STATE` | The Seeker is already running. | |

### otSeekerSetUpNextConnection

```
otError otSeekerSetUpNextConnection(
  otInstance *aInstance,
  otSockAddr *aSockAddr
)
```
Selects the next best candidate and prepares the connection.

This function MUST be called after the discovery scan has completed (indicated by the `otSeekerScanEvaluator` callback receiving `NULL`). Calling it before scan completion will result in `OT_ERROR_INVALID_STATE`.

This function iterates through the discovered Joiner Router candidates in order of priority. For the selected candidate, it configures the radio channel and PAN ID, and populates `aSockAddr` with the candidate's address. It also registers the Seeker UDP port `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gaa90f0048aa1ac84022948114aaa478d2` as an unsecure port to allow a UDP connection to the candidate. The next layer code can start sending UDP messages to the given `https://openthread.io/reference/struct/ot-sock-addr` ensuring to use the unsecure Seeker UDP port as the source port. These messages are then forwarded by the Joiner Router onward to a Commissioner/Enroller connected via a Border Agent/Admitter.

If the list is exhausted, this function returns `OT_ERROR_NOT_FOUND` and automatically calls `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gab2c8ab54a519b5940a328dd495286b94`, which removes the unsecure port and clears internal state.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[out] aSockAddr` | A pointer to a socket address to output the candidate's address. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully set up the connection to the next candidate. | | `OT_ERROR_NOT_FOUND` | No more candidates are available (list exhausted). | | `OT_ERROR_INVALID_STATE` | The Seeker is not in a valid state (e.g. scan not yet completed). | |

### otSeekerStart

```
otError otSeekerStart(
  otInstance *aInstance,
  otSeekerScanEvaluator aScanEvaluator,
  void *aContext
)
```
Starts the Seeker operation.

The Seeker generates and sets a random MAC address for anonymity, then initiates an MLE Discover Scan to find Joiner Router candidates.

Found candidates are reported to the `aScanEvaluator` callback. Based on the returned `otSeekerVerdict`, the Seeker maintains a prioritized list of candidates for future connection attempts.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aScanEvaluator` | The callback function to evaluate scan results. | | `[in] aContext` | An arbitrary context pointer to use with `aScanEvaluator`. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully started the Seeker. | | `OT_ERROR_BUSY` | The Seeker is already active (scanning or connecting). | | `OT_ERROR_INVALID_STATE` | The IPv6 interface is not enabled, or MLE is enabled. | |

### otSeekerStop

```
void otSeekerStop(
  otInstance *aInstance
)
```
Stops the Seeker operation.

This function stops any ongoing discovery or connection process, unregisters the unsecure Joiner/Seeker UDP port, and clears internal state. If the Seeker is already stopped, this method has no effect.

If the join process succeeds after a call to `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gaddda11527b67907c022d90d8dde96224`, the caller MUST call this method to stop the Seeker and, importantly, unregister the Seeker UDP port as an unsecure port.


> [!NOTE]
> **Note:** If `https://openthread.io/reference/group/api-seeker#group__api-seeker_1gaddda11527b67907c022d90d8dde96224` returns `OT_ERROR_NOT_FOUND` (indicating the candidate list is exhausted), the Seeker stops automatically.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |

## Resources

OpenThread API Reference topics originate from the source code, available
on [GitHub](https://github.com/openthread/openthread/tree/main/include/openthread).
For more information, or to contribute to our documentation, refer to
[Resources](https://openthread.io/resources).