# Border Agent

# Border Agent

This module includes functions for the Thread Border Agent role.

## Summary

This module includes functions for the Thread Border Agent Admitter role.

All APIs in this module require both `OPENTHREAD_CONFIG_BORDER_AGENT_ENABLE` and `OPENTHREAD_CONFIG_BORDER_AGENT_ADMITTER_ENABLE` features to be enabled.

| ### Enumerations ||
|---|---|
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga08c9c41c9a0d113f606789afb31ccaf7{ https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gga08c9c41c9a0d113f606789afb31ccaf7acb916f53b4bf9b72b1cbb2d34215f8c4 = 0, https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gga08c9c41c9a0d113f606789afb31ccaf7aa3f2e05a622cfbbde316de1ed210363c = 1, https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gga08c9c41c9a0d113f606789afb31ccaf7a9568548f67267e2e6ecfd3c813f943f8 = 2, https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gga08c9c41c9a0d113f606789afb31ccaf7adf946ae99d57086ab0cb1388b406a8d1 = 3, https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gga08c9c41c9a0d113f606789afb31ccaf7a0ffa0c28845faaa4f5014cce32329b02 = 4 }` | enumRepresents Border Agent's Ephemeral Key Manager state. |

| ### Typedefs ||
|---|---|
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gab8ece9ff29e1deabcd9ea6a65208eb3b` | typedef `struct https://openthread.io/reference/struct/ot-border-admitter-enroller-info` Represents information about an enroller. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga53a85b7a05d045cc5600445de9c4e094` | typedef `struct https://openthread.io/reference/struct/ot-border-admitter-iterator` Represents an iterator for Border Admitter enroller. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gada7456f18eded470c0f0cfcf3fd079dc` | typedef `struct https://openthread.io/reference/struct/ot-border-admitter-joiner-info` Represents information about a joiner accepted by an enroller. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaed81438f04c9677328c07d8bd8900900` | typedef `struct https://openthread.io/reference/struct/ot-border-agent-counters` Defines Border Agent counters. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga90f5f379db4625b52425388b1b408140)(void *aContext)` | typedef `void(*` Callback function pointer to signal state changes to the Border Agent's Ephemeral Key Manager. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gab0caf537713a1c74fe1d0c9549414d18` | typedef `enum https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga08c9c41c9a0d113f606789afb31ccaf7` Represents Border Agent's Ephemeral Key Manager state. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaac50ac77aa5a3c38345a068510aa4788` | typedef `struct https://openthread.io/reference/struct/ot-border-agent-ephemeral-key-tap` Represents a Thread Administration One-Time Passcode (TAP). |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga74cf9feff73ae00344f9990f15aefbea` | typedef `struct https://openthread.io/reference/struct/ot-border-agent-id` Represents a Border Agent Identifier. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaeb2b8b99cb5c844d5a7e896959db937d)(void *aContext)` | typedef `void(*` This callback informs the application of the changes in the state of the MeshCoP service. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga76f0c8c47b72101a0c95ab06e0246b67` | typedef `struct https://openthread.io/reference/struct/ot-border-agent-mesh-co-p-service-txt-data` Represents the Border Agent MeshCoP Service TXT data. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga33da96c53601e445cd5ea03b37c0551d` | typedef `struct https://openthread.io/reference/struct/ot-border-agent-session-info` Represents information about a Border Agent session. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga5b29b7bf3b1cfb039f30b46369b97cb0` | typedef `struct https://openthread.io/reference/struct/ot-border-agent-session-iterator` Represents an iterator for Border Agent sessions. |

| ### Functions ||
|---|---|
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga77782412b56a39ae01b3e79aa167adf4(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint16_t` Gets the Joiner UDP port. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gadc36b2c2b4f973aa14ef4e66db98a02e(https://openthread.io/reference/struct/ot-border-admitter-iterator *aIterator, https://openthread.io/reference/struct/ot-border-admitter-enroller-info *aEnrollerInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Retrieves the information about the next Enroller registered with the Admitter. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga5f7b28a6042351c7e2932131e9e5269c(https://openthread.io/reference/struct/ot-border-admitter-iterator *aIterator, https://openthread.io/reference/struct/ot-border-admitter-joiner-info *aJoinerInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Retrieves the information about the next accepted joiner by the latest retrieved enroller during iteration. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga570e64eb6756ca8015943e2dc690916f(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-border-admitter-iterator *aIterator)` | `void` Initializes an `https://openthread.io/reference/struct/ot-border-admitter-iterator`. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga3afaf166bd9ea3446a2542b650a2ee13(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether the Prime Admitter is currently the active commissioner. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga04f7d7abbcf58599ef4722b3eb6de733(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether the Border Agent Admitter is enabled. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga8355b0e6535ab1bd2cc807d446fd14df(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether the Prime Admitter's petition to become the native mesh commissioner was rejected. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga76a69f3a80951c6d07fb224b9289675e(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether the device is currently the Prime Admitter. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga656d13f15f1f0cca40e4f9afca3145b5(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnable)` | `void` Enables or disables the Border Agent Admitter. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga7c1f6102e1b97d2a7620064d22827f70(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, uint16_t aUdpPort)` | `void` Sets the joiner UDP port. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gad517d013c4b5c3bb9f1e413deb0da4ca(https://openthread.io/reference/struct/ot-border-agent-ephemeral-key-tap *aTap)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Generates a cryptographically secure random Thread Administration One-Time Passcode (TAP) string. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gae22c5cc6460043718a3a11ee74243ee8(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga08c9c41c9a0d113f606789afb31ccaf7` Gets the state of Border Agent's Ephemeral Key Manager. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga14fea2b94268900cd845cb61f9ed6e57(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint16_t` Gets the UDP port used by Border Agent's Ephemeral Key Manager. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga6c4d0056dea384053dd3951dad90c556(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga90f5f379db4625b52425388b1b408140 aCallback, void *aContext)` | `void` Sets the callback function to notify state changes of Border Agent's Ephemeral Key Manager. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga594fa70a3c1d93812161697110c948cc(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnabled)` | `void` Enables/disables the Border Agent's Ephemeral Key Manager. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaff59a0f7d28e5001a5a12f6515735536(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aKeyString, uint32_t aTimeout, uint16_t aUdpPort)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Starts using an ephemeral key for a given timeout duration. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gac264ef7322988d0d20f7d859d5107ffd(https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga08c9c41c9a0d113f606789afb31ccaf7 aState)` | `const char *` Converts a given `otBorderAgentEphemeralKeyState` to a human-readable string. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga72943c0cccdf0f803b12263c878ccf64(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `void` Stops the ephemeral key use and disconnects any session using it. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga66097b3f798dfc62fa56dee99d21c410(const https://openthread.io/reference/struct/ot-border-agent-ephemeral-key-tap *aTap)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Validates a given Thread Administration One-Time Passcode (TAP) string. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga6c6aa076db2ec23d825778adfbaae40d(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Forcefully evicts the current active Thread Commissioner. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga3bd5026265c2d51b96cc48d879030fa8(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `const https://openthread.io/reference/struct/ot-border-agent-counters *` Gets the counters of the Thread Border Agent. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gacccad10d2b9a9f45b93f724894c6780f(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-border-agent-id *aId)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the randomly generated Border Agent ID. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaa1c6ebe4b6fc5cde1bb9212ffb48b441(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-border-agent-mesh-co-p-service-txt-data *aTxtData)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Gets the MeshCoP service TXT data. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaeddd5429664f14707e75bd26b2af9664(https://openthread.io/reference/struct/ot-border-agent-session-iterator *aIterator, https://openthread.io/reference/struct/ot-border-agent-session-info *aSessionInfo)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Retrieves the next Border Agent session information. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gad7f6d91b926eda80485d077ea53fa597(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `uint16_t` Gets the UDP port of the Thread Border Agent service. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga23a2fb8336f0d450213720cfa0413230(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/struct/ot-border-agent-session-iterator *aIterator)` | `void` Initializes a session iterator. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gacd82e75a0a0f4d1a0605cc8e921a3a96(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether or not the Border Agent service is enabled and also active. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga36f07bfac570be2423d9279db0807a3e(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance)` | `bool` Indicates whether or not the Border Agent service is enabled. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga35a5778765300a35d7645cc47553842d(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, bool aEnabled)` | `void` Enables or disables the Border Agent service on the device. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaa0a606383ee895407acb24d4f278d2f8(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const https://openthread.io/reference/struct/ot-border-agent-id *aId)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets the Border Agent ID. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga7709732123fee1d12cecbbdb25468ffe(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const char *aBaseName)` | `https://openthread.io/reference/group/api-error#group__api-error_1gabaaa90aaa35da8f9d394a227a23a6a49` Sets the base name to construct the service instance name used when advertising the mDNS `_meshcop._udp` service by the Border Agent. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gad4e5a310d1902b9e6a5518ab0728a502(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaeb2b8b99cb5c844d5a7e896959db937d aCallback, void *aContext)` | `void` Sets the callback function used by the Border Agent to notify of any changes to the state of the MeshCoP service. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gad0d6355aa15293e9b119f3cc548863bf(https://openthread.io/reference/group/api-instance#group__api-instance_1ga25440551213fb5b40869725378584960 *aInstance, const uint8_t *aVendorData, uint16_t aVendorDataLength)` | `void` Sets the vendor extra TXT data to be included when the Border Agent advertises the mDNS `_meshcop._udp` service. |

| ### Macros ||
|---|---|
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaaeb69ab2d654ea3feb7a9be80166d73d (2 * 60 * 1000u)` | Default ephemeral key timeout interval in milliseconds. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gad4d7c44c12e95d0365d88f553a251a87 9` | The string length of Thread Administration One-Time Passcode (TAP). |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gac23dcb55f4d5166f3281d49456129404 (16)` | The length of Border Agent/Router ID in bytes. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gafaaf28b12fcb0d23dc9c7f8a742d7536 (32)` | Maximum length of the ephemeral key string. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga518fdbc00382ec282bc9aea19c6cd229 (10 * 60 * 1000u)` | Maximum ephemeral key timeout interval in milliseconds. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaf333feabd84674b42eb95fc692803695 (OT_DNS_MAX_LABEL_SIZE - 13)` | Maximum string length of base name used in `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga7709732123fee1d12cecbbdb25468ffe`. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaf4c0b3c48b31170530fffe7f7b1c2f66 256` | Maximum length of the OT core generated MeshCoP Service TXT data. |
| `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gafbdae50452b42831f9c2ba001c20b27c (6)` | Minimum length of the ephemeral key string. |

| ### Structs ||
|---|---|
| [otBorderAdmitterEnrollerInfo](https://openthread.io/reference/struct/ot-border-admitter-enroller-info) | Represents information about an enroller. |
| [otBorderAdmitterIterator](https://openthread.io/reference/struct/ot-border-admitter-iterator) | Represents an iterator for Border Admitter enroller. |
| [otBorderAdmitterJoinerInfo](https://openthread.io/reference/struct/ot-border-admitter-joiner-info) | Represents information about a joiner accepted by an enroller. |
| [otBorderAgentCounters](https://openthread.io/reference/struct/ot-border-agent-counters) | Defines Border Agent counters. |
| [otBorderAgentEphemeralKeyTap](https://openthread.io/reference/struct/ot-border-agent-ephemeral-key-tap) | Represents a Thread Administration One-Time Passcode (TAP). |
| [otBorderAgentId](https://openthread.io/reference/struct/ot-border-agent-id) | Represents a Border Agent Identifier. |
| [otBorderAgentMeshCoPServiceTxtData](https://openthread.io/reference/struct/ot-border-agent-mesh-co-p-service-txt-data) | Represents the Border Agent MeshCoP Service TXT data. |
| [otBorderAgentSessionInfo](https://openthread.io/reference/struct/ot-border-agent-session-info) | Represents information about a Border Agent session. |
| [otBorderAgentSessionIterator](https://openthread.io/reference/struct/ot-border-agent-session-iterator) | Represents an iterator for Border Agent sessions. |

## Enumerations

### otBorderAgentEphemeralKeyState

```
 otBorderAgentEphemeralKeyState
```
Represents Border Agent's Ephemeral Key Manager state.

| Properties ||
|---|---|
| `OT_BORDER_AGENT_STATE_ACCEPTED` | Session is established and candidate is accepted as full commissioner. |
| `OT_BORDER_AGENT_STATE_CONNECTED` | Session is established with an external commissioner candidate. |
| `OT_BORDER_AGENT_STATE_DISABLED` | Ephemeral Key Manager is disabled. |
| `OT_BORDER_AGENT_STATE_STARTED` | Ephemeral key is set. Listening to accept secure connections. |
| `OT_BORDER_AGENT_STATE_STOPPED` | Enabled, but no ephemeral key is in use (not set or started). |

## Typedefs

### otBorderAdmitterEnrollerInfo

```
struct otBorderAdmitterEnrollerInfo otBorderAdmitterEnrollerInfo
```
Represents information about an enroller.

To ensure consistent `mRegisterDuration` calculations, the iterator's initialization time is stored within the iterator, and each enroller `mRegisterDuration` is calculated relative to this time.

### otBorderAdmitterIterator

```
struct otBorderAdmitterIterator otBorderAdmitterIterator
```
Represents an iterator for Border Admitter enroller.

The caller MUST NOT access or update the fields in this struct. It is intended for OpenThread internal use only.

### otBorderAdmitterJoinerInfo

```
struct otBorderAdmitterJoinerInfo otBorderAdmitterJoinerInfo
```
Represents information about a joiner accepted by an enroller.

To ensure consistent duration calculations, the iterator's initialization time is stored within the iterator, and the `mMsecSinceAccept` is calculated relative to this time.

### otBorderAgentCounters

```
struct otBorderAgentCounters otBorderAgentCounters
```
Defines Border Agent counters.

The `mEpskc` related counters require `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.

### otBorderAgentEphemeralKeyCallback

```
void(* otBorderAgentEphemeralKeyCallback)(void *aContext)
```
Callback function pointer to signal state changes to the Border Agent's Ephemeral Key Manager.

This callback is invoked whenever the `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gae22c5cc6460043718a3a11ee74243ee8` gets changed.

Any OpenThread API, including `otBorderAgent` APIs, can be safely called from this callback.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aContext` | A pointer to an arbitrary context (provided when callback is set). | |

### otBorderAgentEphemeralKeyState

```
enum otBorderAgentEphemeralKeyState otBorderAgentEphemeralKeyState
```
Represents Border Agent's Ephemeral Key Manager state.

### otBorderAgentEphemeralKeyTap

```
struct otBorderAgentEphemeralKeyTap otBorderAgentEphemeralKeyTap
```
Represents a Thread Administration One-Time Passcode (TAP).

### otBorderAgentId

```
struct otBorderAgentId otBorderAgentId
```
Represents a Border Agent Identifier.

### otBorderAgentMeshCoPServiceChangedCallback

```
void(* otBorderAgentMeshCoPServiceChangedCallback)(void *aContext)
```
This callback informs the application of the changes in the state of the MeshCoP service.

In specific, the 'state' includes the MeshCoP TXT data originated from the Thread network and whether the Border Agent is Active (which can be obtained by `otBorderAgentIsActive`).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aContext` | A pointer to application-specific context. | |

### otBorderAgentMeshCoPServiceTxtData

```
struct otBorderAgentMeshCoPServiceTxtData otBorderAgentMeshCoPServiceTxtData
```
Represents the Border Agent MeshCoP Service TXT data.

### otBorderAgentSessionInfo

```
struct otBorderAgentSessionInfo otBorderAgentSessionInfo
```
Represents information about a Border Agent session.

This structure is populated by `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaeddd5429664f14707e75bd26b2af9664` during iteration over the list of sessions using an `https://openthread.io/reference/struct/ot-border-agent-session-iterator`.

To ensure consistent `mLifetime` calculations, the iterator's initialization time is stored within the iterator, and each session's `mLifetime` is calculated relative to this time.

### otBorderAgentSessionIterator

```
struct otBorderAgentSessionIterator otBorderAgentSessionIterator
```
Represents an iterator for Border Agent sessions.

The caller MUST NOT access or update the fields in this struct. It is intended for OpenThread internal use only.

## Functions

### otBorderAdmitterGetJoinerUdpPort

```
uint16_t otBorderAdmitterGetJoinerUdpPort(
  otInstance *aInstance
)
```
Gets the Joiner UDP port.

A zero value indicates the Joiner UDP port is not specified/fixed by the Admitter (Joiner Routers can pick).

<br />

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

### otBorderAdmitterGetNextEnrollerInfo

```
otError otBorderAdmitterGetNextEnrollerInfo(
  otBorderAdmitterIterator *aIterator,
  otBorderAdmitterEnrollerInfo *aEnrollerInfo
)
```
Retrieves the information about the next Enroller registered with the Admitter.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aIterator` | The iterator to use. | | `[out] aEnrollerInfo` | A pointer to an `https://openthread.io/reference/struct/ot-border-admitter-enroller-info` to populate. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully retrieved the next enroller info. | | `OT_ERROR_NOT_FOUND` | No more enrollers are available. The end of the list has been reached. | |

### otBorderAdmitterGetNextJoinerInfo

```
otError otBorderAdmitterGetNextJoinerInfo(
  otBorderAdmitterIterator *aIterator,
  otBorderAdmitterJoinerInfo *aJoinerInfo
)
```
Retrieves the information about the next accepted joiner by the latest retrieved enroller during iteration.

Iterates over all joiners which are accepted by the latest enroller, i.e., the last enroller which was retrieved using the `aIterator` along with `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gadc36b2c2b4f973aa14ef4e66db98a02e`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aIterator` | The iterator to use. | | `[out] aJoinerInfo` | A pointer to an `https://openthread.io/reference/struct/ot-border-admitter-joiner-info` to populate. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully retrieved the next joiner info. | | `OT_ERROR_NOT_FOUND` | No more joiners are available. The end of the list has been reached. | |

### otBorderAdmitterInitIterator

```
void otBorderAdmitterInitIterator(
  otInstance *aInstance,
  otBorderAdmitterIterator *aIterator
)
```
Initializes an `https://openthread.io/reference/struct/ot-border-admitter-iterator`.

An iterator MUST be initialized before it is used.

An iterator can be initialized again to restart from the beginning of the list.

When iterating over enrollers, the initialization time is recorded and used to calculate a consistent `mRegisterDuration` for each enroller.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aIterator` | A pointer to the iterator to initialize. | |

### otBorderAdmitterIsActiveCommissioner

```
bool otBorderAdmitterIsActiveCommissioner(
  otInstance *aInstance
)
```
Indicates whether the Prime Admitter is currently the active commissioner.

After becoming the Prime Admitter and having at least one enroller register, the Admitter petitions the Leader to be granted the commissioner role.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | This device is the active commissioner. | | `FALSE` | This device is not the active commissioner. | |

### otBorderAdmitterIsEnabled

```
bool otBorderAdmitterIsEnabled(
  otInstance *aInstance
)
```
Indicates whether the Border Agent Admitter is enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | The Border Agent Admitter is enabled. | | `FALSE` | The Border Agent Admitter is disabled. | |

### otBorderAdmitterIsPetitionRejected

```
bool otBorderAdmitterIsPetitionRejected(
  otInstance *aInstance
)
```
Indicates whether the Prime Admitter's petition to become the native mesh commissioner was rejected.

A rejection typically occurs if there is already another active commissioner in the Thread network.

The Admitter will automatically retry petitioning. It monitors the Thread Network Data to see when the other commissioner is removed and retry its own petition.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | The petition was rejected. | | `FALSE` | The petition was not rejected. | |

### otBorderAdmitterIsPrimeAdmitter

```
bool otBorderAdmitterIsPrimeAdmitter(
  otInstance *aInstance
)
```
Indicates whether the device is currently the Prime Admitter.

The Prime Admitter is the device that wins the election among all Admitters within the Thread mesh network. The election algorithm ensures convergence on a single Prime Admitter within the mesh.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | This device is the Prime Admitter. | | `FALSE` | This device is not the Prime Admitter. | |

### otBorderAdmitterSetEnabled

```
void otBorderAdmitterSetEnabled(
  otInstance *aInstance,
  bool aEnable
)
```
Enables or disables the Border Agent Admitter.

The default enable/disable state of Border Admitter (after OpenThread stack initialization) is determined by the OpenThread config `OPENTHREAD_CONFIG_BORDER_AGENT_ADMITTER_ENABLED_BY_DEFAULT`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aEnabled` | A boolean to indicate whether to enable (TRUE) or disable (FALSE) the Border Agent Admitter. | |

### otBorderAdmitterSetJoinerUdpPort

```
void otBorderAdmitterSetJoinerUdpPort(
  otInstance *aInstance,
  uint16_t aUdpPort
)
```
Sets the joiner UDP port.

A zero value indicates the Joiner UDP port is not specified/fixed by the Admitter (Joiner Routers can pick).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aUdpPort` | The joiner UDP port number. | |

### otBorderAgentEphemeralKeyGenerateTap

```
otError otBorderAgentEphemeralKeyGenerateTap(
  otBorderAgentEphemeralKeyTap *aTap
)
```
Generates a cryptographically secure random Thread Administration One-Time Passcode (TAP) string.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE` and `OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE`.

The TAP is a string of 9 characters, generated as a sequence of eight cryptographically secure random numeric digits \[`0`-`9`\] followed by a single check digit determined using the Verhoeff algorithm.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[out] aTap` | A pointer to an `https://openthread.io/reference/struct/ot-border-agent-ephemeral-key-tap` to output the generated TAP. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully generated a random TAP. `aTap` is updated. | | `OT_ERROR_FAILED` | Failed to generate a random TAP. | |

### otBorderAgentEphemeralKeyGetState

```
otBorderAgentEphemeralKeyState otBorderAgentEphemeralKeyGetState(
  otInstance *aInstance
)
```
Gets the state of Border Agent's Ephemeral Key Manager.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The current state of Ephemeral Key Manager. |

### otBorderAgentEphemeralKeyGetUdpPort

```
uint16_t otBorderAgentEphemeralKeyGetUdpPort(
  otInstance *aInstance
)
```
Gets the UDP port used by Border Agent's Ephemeral Key Manager.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.

The port is applicable if an ephemeral key is in use, i.e., the state is not `OT_BORDER_AGENT_STATE_DISABLED` or `OT_BORDER_AGENT_STATE_STOPPED`.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | The UDP port being used by Border Agent's Ephemeral Key Manager (when active). |

### otBorderAgentEphemeralKeySetCallback

```
void otBorderAgentEphemeralKeySetCallback(
  otInstance *aInstance,
  otBorderAgentEphemeralKeyCallback aCallback,
  void *aContext
)
```
Sets the callback function to notify state changes of Border Agent's Ephemeral Key Manager.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.

A subsequent call to this function will replace any previously set callback.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aCallback` | The callback function pointer. | | `[in] aContext` | The arbitrary context to use with callback. | |

### otBorderAgentEphemeralKeySetEnabled

```
void otBorderAgentEphemeralKeySetEnabled(
  otInstance *aInstance,
  bool aEnabled
)
```
Enables/disables the Border Agent's Ephemeral Key Manager.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.

If this function is called to disable, while an an ephemeral key is in use, the ephemeral key use will be stopped (as if `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga72943c0cccdf0f803b12263c878ccf64` is called).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aEnabled` | Whether to enable or disable the Ephemeral Key Manager. | |

### otBorderAgentEphemeralKeyStart

```
otError otBorderAgentEphemeralKeyStart(
  otInstance *aInstance,
  const char *aKeyString,
  uint32_t aTimeout,
  uint16_t aUdpPort
)
```
Starts using an ephemeral key for a given timeout duration.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.

An ephemeral key can only be set when `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gae22c5cc6460043718a3a11ee74243ee8` is `OT_BORDER_AGENT_STATE_STOPPED`, i.e., enabled but not yet started. Otherwise, `OT_ERROR_INVALID_STATE` is returned. This means that setting the ephemeral key again while a previously set key is still in use will fail. Callers can stop the previous key by calling `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga72943c0cccdf0f803b12263c878ccf64` before starting with a new key.

The Ephemeral Key Manager and the Border Agent service (which uses PSKc) can be enabled and used in parallel, as they use independent and separate DTLS transport and sessions.

The given `aKeyString` is used directly as the ephemeral PSK (excluding the trailing null `\0` character). Its length must be between `OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH` and `OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH`, inclusive. Otherwise `OT_ERROR_INVALID_ARGS` is returned.

When successfully set, the ephemeral key can be used only once by an external commissioner candidate to establish a secure session. After the commissioner candidate disconnects, the use of the ephemeral key is stopped. If the timeout expires, the use of the ephemeral key is stopped, and any connected session using the key is immediately disconnected.

The Ephemeral Key Manager limits the number of failed DTLS connections to 10 attempts. After the 10th failed attempt, the use of the ephemeral key is automatically stopped (even if the timeout has not yet expired).

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aKeyString` | The ephemeral key. | | `[in] aTimeout` | The timeout duration, in milliseconds, to use the ephemeral key. If zero, the default `OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT` value is used. If the timeout value is larger than `OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT`, the maximum value is used instead. | | `[in] aUdpPort` | The UDP port to use with the ephemeral key. If the UDP port is zero, an ephemeral port will be used. `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga14fea2b94268900cd845cb61f9ed6e57` returns the current UDP port being used. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully started using the ephemeral key. | | `OT_ERROR_INVALID_STATE` | A previously set ephemeral key is still in use or the feature is disabled. | | `OT_ERROR_INVALID_ARGS` | The given `aKeyString` is not valid. | | `OT_ERROR_FAILED` | Failed to start (e.g., it could not bind to the given UDP port). | |

### otBorderAgentEphemeralKeyStateToString

```
const char * otBorderAgentEphemeralKeyStateToString(
  otBorderAgentEphemeralKeyState aState
)
```
Converts a given `otBorderAgentEphemeralKeyState` to a human-readable string.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aState` | The state to convert. | |
| **Returns** | Human-readable string corresponding to `aState`. |

### otBorderAgentEphemeralKeyStop

```
void otBorderAgentEphemeralKeyStop(
  otInstance *aInstance
)
```
Stops the ephemeral key use and disconnects any session using it.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE`.

If there is no ephemeral key in use, calling this function has no effect.

<br />

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

### otBorderAgentEphemeralKeyValidateTap

```
otError otBorderAgentEphemeralKeyValidateTap(
  const otBorderAgentEphemeralKeyTap *aTap
)
```
Validates a given Thread Administration One-Time Passcode (TAP) string.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE` and `OPENTHREAD_CONFIG_VERHOEFF_CHECKSUM_ENABLE`.

Validates that the TAP string has the proper length, contains digit characters \[`0`-`9`\], and validates the Verhoeff checksum.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aTap` | The `https://openthread.io/reference/struct/ot-border-agent-ephemeral-key-tap` to validate. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully validated the `aTap`. | | `OT_ERROR_INVALID_ARGS` | The `aTap` string has an invalid length or contains non-digit characters. | | `OT_ERROR_FAILED` | Checksum validation failed. | |

### otBorderAgentEvictActiveCommissioner

```
otError otBorderAgentEvictActiveCommissioner(
  otInstance *aInstance
)
```
Forcefully evicts the current active Thread Commissioner.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_COMMISSIONER_EVICTION_API_ENABLE`.

This is intended as an administrator tool to address a misbehaving or stale commissioner session that may be connected through a different Border Agent. It provides a mechanism to clear the single Active Commissioner role within the Thread network, allowing a new candidate to be selected as the Active commissioner.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully sent the eviction request to the Leader. | | `OT_ERROR_NOT_FOUND` | There is no active commissioner session to evict. | | `OT_ERROR_NO_BUFS` | Could not allocate a message buffer to send the request. | |

### otBorderAgentGetCounters

```
const otBorderAgentCounters * otBorderAgentGetCounters(
  otInstance *aInstance
)
```
Gets the counters of the Thread Border Agent.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | A pointer to the Border Agent counters. |

### otBorderAgentGetId

```
otError otBorderAgentGetId(
  otInstance *aInstance,
  otBorderAgentId *aId
)
```
Gets the randomly generated Border Agent ID.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_ID_ENABLE`.

The ID is saved in persistent storage and survives reboots. The typical use case of the ID is to be published in the MeshCoP mDNS service as the `id` TXT value for the client to identify this Border Router/Agent device.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[out] aId` | A pointer to buffer to receive the ID. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | If successfully retrieved the Border Agent ID. | | `...` | If failed to retrieve the Border Agent ID. | |

**See also:**   
[otBorderAgentSetId](https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaa0a606383ee895407acb24d4f278d2f8)   

### otBorderAgentGetMeshCoPServiceTxtData

```
otError otBorderAgentGetMeshCoPServiceTxtData(
  otInstance *aInstance,
  otBorderAgentMeshCoPServiceTxtData *aTxtData
)
```
Gets the MeshCoP service TXT data.

The generated TXT data includes a subset of keys (depending on the device's current state and whether features are enabled) as specified in the documentation of the `OT_BORDER_AGENT_MESHCOP_SERVICE_TXT_DATA_MAX_LENGTH` constant. Notably, if `OPENTHREAD_CONFIG_BORDER_AGENT_MESHCOP_SERVICE_ENABLE` is enabled and `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gad0d6355aa15293e9b119f3cc548863bf` was used to set extra vendor-specific TXT data bytes, those vendor-specified TXT data bytes are NOT included in the TXT data returned by this function.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[out] aTxtData` | A pointer to a MeshCoP Service TXT data struct to get the data. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | If successfully retrieved the Border Agent MeshCoP Service TXT data. | | `OT_ERROR_NO_BUFS` | If the buffer in `aTxtData` doesn't have enough size. | |

### otBorderAgentGetNextSessionInfo

```
otError otBorderAgentGetNextSessionInfo(
  otBorderAgentSessionIterator *aIterator,
  otBorderAgentSessionInfo *aSessionInfo
)
```
Retrieves the next Border Agent session information.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aIterator` | The iterator to use. | | `[out] aSessionInfo` | A pointer to an `https://openthread.io/reference/struct/ot-border-agent-session-info` to populate. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | Successfully retrieved the next session info. | | `OT_ERROR_NOT_FOUND` | No more sessions are available. The end of the list has been reached. | |

### otBorderAgentGetUdpPort

```
uint16_t otBorderAgentGetUdpPort(
  otInstance *aInstance
)
```
Gets the UDP port of the Thread Border Agent service.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| **Returns** | UDP port of the Border Agent. |

### otBorderAgentInitSessionIterator

```
void otBorderAgentInitSessionIterator(
  otInstance *aInstance,
  otBorderAgentSessionIterator *aIterator
)
```
Initializes a session iterator.

An iterator MUST be initialized before being used in `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gaeddd5429664f14707e75bd26b2af9664`. A previously initialized iterator can be re-initialized to start from the beginning of the session list.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aIterator` | The iterator to initialize. | |

### otBorderAgentIsActive

```
bool otBorderAgentIsActive(
  otInstance *aInstance
)
```
Indicates whether or not the Border Agent service is enabled and also active.

While the Border Agent is active, external commissioner candidates can try to connect to and establish secure DTLS sessions with the Border Agent using PSKc. A connected commissioner can then petition to become a full commissioner.

If `OPENTHREAD_CONFIG_BORDER_AGENT_EPHEMERAL_KEY_ENABLE` is enabled, independent and separate DTLS transport and sessions are used for the ephemeral key. Therefore, the ephemeral key and Border Agent service can be enabled and used in parallel.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | The Border Agent is active. | | `FALSE` | The Border Agent is not active. | |

### otBorderAgentIsEnabled

```
bool otBorderAgentIsEnabled(
  otInstance *aInstance
)
```
Indicates whether or not the Border Agent service is enabled.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | |
| Return Values | |---|---| | `TRUE` | The Border Agent service is enabled. | | `FALSE` | The Border Agent service is disabled. | |

### otBorderAgentSetEnabled

```
void otBorderAgentSetEnabled(
  otInstance *aInstance,
  bool aEnabled
)
```
Enables or disables the Border Agent service on the device.

By default, the Border Agent service is enabled when the `OPENTHREAD_CONFIG_BORDER_AGENT_ENABLE` feature is used. This function allows higher-layer code to explicitly control its state. This can be useful in scenarios such as:


- The higher-layer code wishes to delay the start of the Border Agent service (and its mDNS advertisement of the `_meshcop._udp` service on the infrastructure link). This allows time to prepare or determine vendor-specific TXT data entries for inclusion.
- Unit tests or test scripts might disable the Border Agent service to prevent it from interfering with specific test steps. For example, tests validating mDNS or DNS-SD functionality may disable the Border Agent to prevent its registration of the MeshCoP service.

<br />

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aEnabled` | A boolean to indicate whether to to enable (TRUE), or disable (FALSE). | |

### otBorderAgentSetId

```
otError otBorderAgentSetId(
  otInstance *aInstance,
  const otBorderAgentId *aId
)
```
Sets the Border Agent ID.

Requires `OPENTHREAD_CONFIG_BORDER_AGENT_ID_ENABLE`.

The Border Agent ID will be saved in persistent storage and survive reboots. It's required to set the ID only once after factory reset. If the ID has never been set by calling this function, a random ID will be generated and returned when `otBorderAgentGetId` is called.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aId` | A pointer to the Border Agent ID. | |
| Return Values | |---|---| | `OT_ERROR_NONE` | If successfully set the Border Agent ID. | | `...` | If failed to set the Border Agent ID. | |

**See also:**   
[otBorderAgentGetId](https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1gacccad10d2b9a9f45b93f724894c6780f)   

### otBorderAgentSetMeshCoPServiceBaseName

```
otError otBorderAgentSetMeshCoPServiceBaseName(
  otInstance *aInstance,
  const char *aBaseName
)
```
Sets the base name to construct the service instance name used when advertising the mDNS `_meshcop._udp` service by the Border Agent.

Requires the `OPENTHREAD_CONFIG_BORDER_AGENT_MESHCOP_SERVICE_ENABLE` feature.

The name can also be configured using the `OPENTHREAD_CONFIG_BORDER_AGENT_MESHCOP_SERVICE_BASE_NAME` configuration option (which is the recommended way to specify this name). This API is provided for projects where the name needs to be set after device initialization and at run-time.

Per the Thread specification, the service instance should be a user-friendly name identifying the device model or product. A recommended format is "VendorName ProductName".

To construct the full name and ensure name uniqueness, the OpenThread Border Agent module appends a suffix (e.g., " #XXXX" where "XXXX" represents the last two bytes of the device's Extended Address in hex) to the given base name. If a name conflict is detected on the network, an additional index may be appended (e.g., " #XXXX (1)").

Note that the same name will be used for the ephemeral key service `_meshcop-e._udp` when the ephemeral key feature is enabled and used.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aBaseName` | The base name to use (MUST not be NULL). | |
| Return Values | |---|---| | `OT_ERROR_NONE` | The name was set successfully. | | `OT_ERROR_INVALID_ARGS` | The name is too long or invalid. | |

### otBorderAgentSetMeshCoPServiceChangedCallback

```
void otBorderAgentSetMeshCoPServiceChangedCallback(
  otInstance *aInstance,
  otBorderAgentMeshCoPServiceChangedCallback aCallback,
  void *aContext
)
```
Sets the callback function used by the Border Agent to notify of any changes to the state of the MeshCoP service.

The callback is invoked when the 'Is Active' state of the Border Agent or the MeshCoP service TXT data values change. For example, it is invoked when the network name or the extended PAN ID changes and passes the updated encoded TXT data to the application layer.

This callback is invoked once right after this API is called to provide initial states of the MeshCoP service.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | A pointer to an OpenThread instance. | | `[in] aCallback` | The callback to be invoked when there are any changes of the MeshCoP service. | | `[in] aContext` | A pointer to application-specific context. | |

### otBorderAgentSetVendorTxtData

```
void otBorderAgentSetVendorTxtData(
  otInstance *aInstance,
  const uint8_t *aVendorData,
  uint16_t aVendorDataLength
)
```
Sets the vendor extra TXT data to be included when the Border Agent advertises the mDNS `_meshcop._udp` service.

Requires the `OPENTHREAD_CONFIG_BORDER_AGENT_MESHCOP_SERVICE_ENABLE` feature.

The provided `aVendorData` bytes are appended as they appear in the buffer to the end of the TXT data generated by the Border Agent itself, and are then included in the advertised mDNS `_meshcop._udp` service.

This function itself does not perform any validation of the format of the provided `aVendorData`. Therefore, the caller MUST ensure it is formatted properly. Per the Thread specification, vendor-specific Key-Value TXT data pairs use TXT keys starting with 'v'. For example, `vn` for vendor name and generally `v*`.

The OpenThread stack will create and retain its own copy of the bytes in `aVendorData`. So, the buffer passed to this function does not need to persist beyond the scope of the call.

The vendor TXT data can be set at any time while the Border Agent is in any state. If there is a change from the previously set value, it will trigger an update of the registered mDNS service to advertise the new TXT data.

<br />

| Details ||
|---|---|
| Parameters | |---|---| | `[in] aInstance` | The OpenThread instance. | | `[in] aVendorData` | A pointer to the buffer containing the vendor TXT data. | | `[in] aVendorDataLength` | The length of `aVendorData` in bytes. | |

## Macros

### OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT

```
 OT_BORDER_AGENT_DEFAULT_EPHEMERAL_KEY_TIMEOUT (2 * 60 * 1000u)
```
Default ephemeral key timeout interval in milliseconds.

### OT_BORDER_AGENT_EPHEMERAL_KEY_TAP_STRING_LENGTH

```
 OT_BORDER_AGENT_EPHEMERAL_KEY_TAP_STRING_LENGTH 9
```
The string length of Thread Administration One-Time Passcode (TAP).

### OT_BORDER_AGENT_ID_LENGTH

```
 OT_BORDER_AGENT_ID_LENGTH (16)
```
The length of Border Agent/Router ID in bytes.

### OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH

```
 OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_LENGTH (32)
```
Maximum length of the ephemeral key string.

### OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT

```
 OT_BORDER_AGENT_MAX_EPHEMERAL_KEY_TIMEOUT (10 * 60 * 1000u)
```
Maximum ephemeral key timeout interval in milliseconds.

### OT_BORDER_AGENT_MESHCOP_SERVICE_BASE_NAME_MAX_LENGTH

```
 OT_BORDER_AGENT_MESHCOP_SERVICE_BASE_NAME_MAX_LENGTH (OT_DNS_MAX_LABEL_SIZE - 13)
```
Maximum string length of base name used in `https://openthread.io/reference/group/api-border-agent#group__api-border-agent_1ga7709732123fee1d12cecbbdb25468ffe`.

To ensure name uniqueness and handle potential name conflicts, the OpenThread Border Agent module appends a suffix (e.g., " #XXXX" where "XXXX" represents the last two bytes of the device's Extended Address in hex) to the given base name.

### OT_BORDER_AGENT_MESHCOP_SERVICE_TXT_DATA_MAX_LENGTH

```
 OT_BORDER_AGENT_MESHCOP_SERVICE_TXT_DATA_MAX_LENGTH 256
```
Maximum length of the OT core generated MeshCoP Service TXT data.

Each field has the format: \| Length (1 byte) \| "Keyname=" \| Data \|

Fields: Border Agent Id (id) - 4 + 16 = 20 bytes Version of TXT record format (rv) - 4 + 1 = 5 bytes Network Name (nn) - 4 + 16 = 20 bytes ExtendedPanId (xp) - 4 + 8 = 12 bytes Thread Version (tv) - 4 + 5 = 9 bytes Extended Address (xa) - 4 + 8 = 12 bytes State Bitmap (sb) - 4 + 4 = 8 bytes Partition Id (pt) - 4 + 4 = 8 bytes Active Timestamp (at) - 4 + 8 = 12 bytes Backbone Router Sequence Number (sq) - 4 + 1 = 5 bytes Backbone Router Udp Port (bb) - 4 + 2 = 6 bytes Backbone Router Domain Name (dn) - 4 + 16 = 20 bytes On-Mesh Routable Prefix (omr) - 5 + 9 = 14 bytes

Maximum possible data length: 151 bytes

### OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH

```
 OT_BORDER_AGENT_MIN_EPHEMERAL_KEY_LENGTH (6)
```
Minimum length of the ephemeral key string.

## 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).