wnc

README

cisco-ios-xe-wireless-go

A Go SDK for interacting with Cisco Catalyst 9800 Wireless Network Controller.

✨️ Key Features

• 🔧 Developer-Friendly: Seamless YANG model handling with responses consistently in JSON
• 🚀 Fast Integration: Start in minutes with straightforward setup and clear examples
• 📊 Broad Coverage: Access most configurations and statistics provided by the WNC
• 🎯 Type-Safe Operations: Strongly typed Go structs for reliable API calls and responses
• 📖 Detailed Documentation: Detailed API references, testing guides, and best practices via godoc

📡 Supported Environment

Cisco Catalyst 9800 Wireless Network Controller running on:

• Cisco IOS-XE 17.12.x - Verified on 17.12.8
• Cisco IOS-XE 17.15.x - Verified on 17.15.6 (Experimental: Spaces)
• Cisco IOS-XE 17.18.x - Verified on 17.18.4a (Experimental: URWB, WAT)

📦 Installation

This SDK requires Go 1.27 or newer.

go get github.com/umatare5/cisco-ios-xe-wireless-go

🚀 Quick Start

You have to enable RESTCONF and HTTPS on the C9800 before using this SDK. Please see:

• Cisco IOS XE 17.15 Programmability Configuration Guide — RESTCONF

1. Generate a Basic Auth token

Encode your controller credentials as Base64.

# username:password → Base64
echo -n "admin:your-password" | base64
# Output: YWRtaW46eW91ci1wYXNzd29yZA==

2. Create a sample application

Use your controller host and token to fetch AP operational data.

package main

import (
    "context"
    "fmt"
    "os"
    "time"

    wnc "github.com/umatare5/cisco-ios-xe-wireless-go"
)

func main() {
    // Load environment variables
    controller := os.Getenv("WNC_CONTROLLER")
    token := os.Getenv("WNC_ACCESS_TOKEN")

    // Create client
    client, err := wnc.NewClient(controller, token,
        wnc.WithTimeout(30*time.Second),
        wnc.WithInsecureSkipVerify(true), // remove for production
    )
    if err != nil {
        fmt.Fprintf(os.Stderr, "Failed to create client: %v\n", err)
        os.Exit(1)
    }

    // Create simple context with timeout
    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()

    // Request AP operational data
    apData, err := client.AP().GetOperational(ctx)
    if err != nil {
        fmt.Fprintf(os.Stderr, "AP oper request failed: %v\n", err)
        os.Exit(1)
    }

    // Print AP operational data
    fmt.Printf("Successfully connected! Found %d APs\n",
        len(apData.CiscoIOSXEWirelessAPOperData.CAPWAPData))
}

[!CAUTION] The wnc.WithInsecureSkipVerify(true) option disables TLS certificate verification. This should only be used in development environments or when connecting to controllers with self-signed certificates. Never use this option in production environments as it compromises security. Where the controller presents a certificate from a private CA, pass wnc.WithRootCAs(pool) instead: the certificate is then verified rather than unverified.

3. Run the application with environment variables

# Set environment variables
export WNC_CONTROLLER="wnc1.example.internal"
export WNC_ACCESS_TOKEN="YWRtaW46eW91ci1wYXNzd29yZA=="

# Run the application
go run main.go

# result: Successfully connected! Found 2 APs

🌐 API Reference

This SDK provides a client to interact with the Cisco Catalyst 9800 Wireless Network Controller's RESTCONF.

Client Initialization

To create a new client, use the wnc.NewClient function with the controller address and access token.

Parameter	Type	Description
controller	string	The hostname or IP address of the WNC.
accessToken	string	The Base64-encoded Basic Auth token.
options...	...Option	Optional client configuration options.

Client Options

There are several options to customize the client behavior. Each argument type is in the package documentation.

Option	Default	Description
WithTimeout(d)	60s	Whole-request timeout
WithResponseHeaderTimeout(d)	5s	Header wait timeout
WithTLSHandshakeTimeout(d)	5s	TLS handshake wait
WithRootCAs(pool)	host roots	Trust a private CA
WithClientCertificate(cert)	none	Present a client cert
WithInsecureSkipVerify(skip)	false	Skip TLS verify
WithProxy(fn)	nil	Proxy resolver
WithLogger(l)	slog.Default()	Structured logger
WithUserAgent(ua)	cisco-ios-xe-wireless-go/<version>	Custom User-Agent

Request Options

Every read method takes optional GetOption values after ctx, which apply to that single request.

Option	Value on the wire	Description
WithDefaults(wnc.ReportAll)	with-defaults=report-all	Adds the leaves in force at their default.
WithDefaults(wnc.Explicit)	with-defaults=explicit	Adds the leaves a client set to the default.
WithFields(expr)	fields=<expr>	Returns only the nodes named.
WithDepth(n)	depth=<n>	Returns the top n levels only.

entries, err := client.WLAN().ListWlanCfgEntries(ctx, wnc.WithDefaults(wnc.ReportAll))

[!NOTE]

RFC 6243 3.3 is why wnc.Explicit differs from a plain GET, which omits any leaf equal to its default. Scope wnc.ReportAll to the container you need, because on a whole-container read the added leaves accumulate across every nested one. A pruned leaf decodes to zero, so WithFields and WithDepth must name every node the caller reads.

Untyped Requests

Every node this SDK types has an accessor.

For one it does not — a container a later IOS-XE release adds, or an RPC with no typed wrapper — the root client carries untyped methods that share the client's credentials, TLS settings, timeouts and *APIError typing.

Method	RESTCONF resource	Notes
GetData(ctx, path, opts...)	/restconf/data	Read with same GetOption
GetDataInto[T](ctx, client, path, opts...)	/restconf/data	Read into a typed envelope
PostData / PutData / PatchData / DeleteData	/restconf/data	Edit via fixed call verb
PostRPC(ctx, path, payload)	/restconf/operations	Invoke RPC
Request(ctx, method, path, payload)	either	Fallback; carries the status

GetDataInto is the one entry above that validates the envelope, so it takes a T whose outermost tag is the module-qualified node the path reads. It is a function rather than a method because a generic method may not be declared in an interface and is invisible to reflect.

body, err := client.PatchData(ctx, "Cisco-IOS-XE-wireless-wlan-cfg:wlan-cfg-data/wlan-cfg-entries/wlan-cfg-entry=1,demo", payload)

[!WARNING]

A []byte or json.RawMessage payload is sent as written once checked for well-formed JSON, and anything else is marshaled. Edit a body read with GetData as bytes, because decoding it into a Go value first rounds a 64-bit number.

Supported Services

Please refer to the Go Reference for the complete reference.

The following table summarizes the supported service APIs and their capabilities.

Legend:

• ✅️ Supported
• 🟩 Partial Supported
• 🟨 Experimental Supported
• ⬜️ Not Supported

API	GetOperational()	GetConfig()	Other Functions	Notes
AFC()	✅️	⬜️	⬜️
AP()	✅️	✅️	🟩	Issue #47 on 17.15+
APF()	⬜️	✅️	⬜️
AWIPS()	✅️	⬜️	⬜️	Issue #48 on 17.15+
BLE()	✅️	⬜️	⬜️
Client()	✅️	⬜️	⬜️
Controller()	⬜️	⬜️	🟩
CTS()	⬜️	✅️	⬜️
Dot11()	⬜️	✅️	⬜️
Dot15()	⬜️	✅️	⬜️
Fabric()	⬜️	✅️	⬜️
Flex()	⬜️	✅️	⬜️
General()	✅️	✅️	⬜️
Geolocation()	✅️	⬜️	⬜️
Hyperlocation()	✅️	⬜️	⬜️
LISP()	✅️	⬜️	⬜️
Location()	✅️	✅️	⬜️
Mcast()	✅️	⬜️	⬜️
MDNS()	✅️	⬜️	⬜️
Mesh()	✅️	✅️	⬜️
Mobility()	✅️	⬜️	⬜️
NMSP()	✅️	⬜️	⬜️
Radio()	⬜️	✅️	⬜️
RF()	⬜️	✅️	⬜️
RFTag()	⬜️	⬜️	🟩
RFID()	✅️	✅️	⬜️
Rogue()	✅️	⬜️	⬜️
RRM()	✅️	✅️	⬜️
Site()	✅️	✅️	⬜️
SiteTag()	⬜️	⬜️	🟩
Spaces()	🟨	⬜️	⬜️	Requires 17.15+
URWB()	🟨	🟨	⬜️	Requires 17.18+
WAT()	⬜️	🟨	⬜️	Requires 17.18+
WLAN()	✅️	✅️	⬜️
PolicyTag()	⬜️	⬜️	🟩

[!TIP]

wtpMac is the same as radioMac. WTP (Wireless Termination Point), defined in RFC 5415 denotes an AP.

🔖 Usecases

Runnable examples are available:

List Operation

Usecase 1: List Associating APs

example/list_aps/main.go lists APs managed by the controller.

Click to show example

❯ go run example/list_aps/main.go

Successfully connected! Found 2 APs

AP Name           | MAC Address         | IP Address       | Status
------------------|---------------------|------------------|-----------------
TEST-AP01         | aa:bb:cc:dd:ee:01   | 192.168.1.11   | registered
TEST-AP02         | aa:bb:cc:dd:ee:02   | 192.168.1.12   | registered

Usecase 2: List Associating Clients

example/list_clients/main.go lists clients associating to wireless networks.

Click to show example

❯ go run example/list_clients/main.go

Successfully connected! Found 17 clients

MAC Address           | IP Address
----------------------|----------------
aa:bb:cc:dd:ee:a1     | 192.168.1.101
aa:bb:cc:dd:ee:a2     | 192.168.1.102
aa:bb:cc:dd:ee:a3     | 192.168.1.103
aa:bb:cc:dd:ee:a4     | 192.168.1.104
<snip>

Usecase 3: List WLANs and BSSIDs

example/list_wlans/main.go lists WLANs and their BSSIDs.

Click to show example

❯ go run example/list_wlans/main.go

Successfully connected! Found 7 WLANs across all APs

AP Name           | AP MAC Address    | Slot | WLAN | BSSID             | SSID
------------------|-------------------|------|------|-------------------|-------------------------
TEST-AP01         | aa:bb:cc:dd:ee:01 |    0 |    1 | aa:bb:cc:dd:ee:b1 | test-wlan
TEST-AP01         | aa:bb:cc:dd:ee:01 |    1 |    2 | aa:bb:cc:dd:ee:b2 | test-psk
TEST-AP01         | aa:bb:cc:dd:ee:01 |    1 |    4 | aa:bb:cc:dd:ee:b3 | test-tls
<snip>

Usecase 4: List AP Neighbors

example/list_neighbors/main.go lists neighboring APs detected by the APs.

Click to show example

❯ go run example/list_neighbors/main.go

Successfully connected! Found 11 AP neighbors

AP Name           | Slot | Neighbor BSSID    | Neighbor SSID          | RSSI  | Channel | Last Heard At
------------------|------|-------------------|------------------------|-------|---------|--------------------------
TEST-AP01         |    0 | aa:bb:cc:dd:ee:f1 | test-rogue-01         |   -20 |      11 | 2024-01-15 10:40:00
TEST-AP01         |    0 | aa:bb:cc:dd:ee:f2 | test-rogue-02         |   -62 |       4 | 2024-01-15 10:41:00
TEST-AP01         |    1 | aa:bb:cc:dd:ee:f3 | test-rogue-03         |   -64 |      36 | 2024-01-15 10:42:00
<snip>

Destructive Operation

Usecase 1: Reset an AP

example/reset_ap/main.go resets a specified AP by its MAC address.

Click to show example

❯ go run example/reset_ap/main.go

=== Access Point Reset Tool ===
WARNING: This tool will restart access points causing service interruption!
Use only in controlled environments with proper authorization.

Target Controller: wnc1.example.internal
Enter AP MAC address (format: xx:xx:xx:xx:xx:xx or xx-xx-xx-xx-xx-xx): aa:bb:cc:dd:ee:01
Target AP MAC: aa:bb:cc:dd:ee:01
This will restart the specified Access Point(s). Type 'YES' to confirm: YES

✓ WNC client created successfully
Executing AP reset for MAC aa:bb:cc:dd:ee:01
WARNING: AP will become unavailable and disconnect all clients during restart...

✓ AP reset command sent successfully for MAC: aa:bb:cc:dd:ee:01
Note: AP is now restarting and will be temporarily unavailable
Clients will need to reconnect after AP restart completes

Usecase 2: Reload a Controller

example/reload_controller/main.go reloads the entire wireless controller.

Click to show example

❯ go run ./example/reload_controller/main.go

=== WNC Controller Reload Tool ===
WARNING: This tool will restart the wireless controller!
Use only in controlled environments with proper authorization.

Target Controller: wnc1.example.internal

This will restart the WNC controller. Type 'YES' to confirm: YES

✓ WNC client created successfully
Executing controller reload with reason: Manual reload via CLI tool at 2024-01-15T10:30:00+09:00
WARNING: Controller will become unavailable during restart...

✓ Controller reload command sent successfully
Note: Controller is now restarting and will be temporarily unavailable
Wait for controller to complete restart before attempting reconnection

Usecase 3: Save the Configuration

example/save_config/main.go copies the running configuration to the startup configuration.

Click to show example

❯ go run example/save_config/main.go

=== WNC Configuration Save Tool ===
WARNING: This tool overwrites the startup configuration and cannot be undone!
Use only in controlled environments with proper authorization.

Target Controller: wnc1.example.internal

This will overwrite the startup configuration. Type 'YES' to confirm: YES

✓ WNC client created successfully
Executing configuration save...

✓ Save running-config successful

📦 Used By

• cisco-wnc-exporter - Prometheus exporter for Cisco C9800 Wireless Network Controller metrics (v0.11.1)
• cisco-wnc-cli - A CLI tool for Cisco C9800 Wireless Network Controller (v0.11.1)

🤝 Contributing

Please read the Contribution Guide before submitting PRs and issues and also see the following documents:

• 📋 Make Command Reference — Make targets and the usage
• 📜 Scripts Reference — Per-script usage and sample outputs
• 🧪 Testing Guide — How to run unit and integration tests

🙏 Acknowledgments

I launched this project with the help of GitHub Copilot Coding Agent, and I am grateful to the global developer community for their contributions to open source projects and public repositories.

📄 License

MIT

Documentation

Overview

Package wnc provides a unified Go SDK for the Cisco Catalyst C9800 Wireless LAN Controller RESTCONF API.

This SDK enables developers to communicate with Cisco Catalyst 9800 controllers in an idiomatic, robust, and maintainable way using Go. It provides access to wireless controller configuration, operational data, and management functions through domain-specific service interfaces.

Index

• Constants
• Variables
• func GetDataInto[T any](ctx context.Context, c *Client, path string, opts ...GetOption) (*T, error)
• type APIError
• type Client
  • func NewClient(host, token string, opts ...Option) (*Client, error)
  • func (c *Client) AFC() afc.Service
  • func (c *Client) AP() ap.Service
  • func (c *Client) APF() apf.Service
  • func (c *Client) AWIPS() awips.Service
  • func (c *Client) BLE() ble.Service
  • func (c *Client) CTS() cts.Service
  • func (c *Client) Client() client.Service
  • func (c *Client) CloseIdleConnections()
  • func (c *Client) Controller() controller.Service
  • func (c *Client) DeleteData(ctx context.Context, path string) ([]byte, error)
  • func (c *Client) Dot11() dot11.Service
  • func (c *Client) Dot15() dot15.Service
  • func (c *Client) Fabric() fabric.Service
  • func (c *Client) Flex() flex.Service
  • func (c *Client) General() general.Service
  • func (c *Client) Geolocation() geolocation.Service
  • func (c *Client) GetData(ctx context.Context, path string, opts ...GetOption) ([]byte, error)
  • func (c *Client) Hyperlocation() hyperlocation.Service
  • func (c *Client) LISP() lisp.Service
  • func (c *Client) Location() location.Service
  • func (c *Client) MDNS() mdns.Service
  • func (c *Client) Mcast() mcast.Service
  • func (c *Client) Mesh() mesh.Service
  • func (c *Client) Mobility() mobility.Service
  • func (c *Client) NMSP() nmsp.Service
  • func (c *Client) PatchData(ctx context.Context, path string, payload any) ([]byte, error)
  • func (c *Client) PolicyTag() *wlan.PolicyTagService
  • func (c *Client) PostData(ctx context.Context, path string, payload any) ([]byte, error)
  • func (c *Client) PostRPC(ctx context.Context, path string, payload any) ([]byte, error)
  • func (c *Client) PutData(ctx context.Context, path string, payload any) ([]byte, error)
  • func (c *Client) RF() rf.Service
  • func (c *Client) RFID() rfid.Service
  • func (c *Client) RFTag() *rf.RFTagService
  • func (c *Client) RRM() rrm.Service
  • func (c *Client) Radio() radio.Service
  • func (c *Client) Request(ctx context.Context, method, path string, payload any) (*Response, error)
  • func (c *Client) Rogue() rogue.Service
  • func (c *Client) Site() site.Service
  • func (c *Client) SiteTag() *site.SiteTagService
  • func (c *Client) Spaces() spaces.Service
  • func (c *Client) URWB() urwb.Service
  • func (c *Client) WAT() wat.Service
  • func (c *Client) WLAN() wlan.Service
• type DefaultsMode
• type GetOption
  • func WithDefaults(mode DefaultsMode) GetOption
  • func WithDepth(levels int) GetOption
  • func WithFields(expression string) GetOption
• type Option
  • func WithClientCertificate(cert tls.Certificate) Option
  • func WithInsecureSkipVerify(skip bool) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithProxy(fn func(*http.Request) (*url.URL, error)) Option
  • func WithResponseHeaderTimeout(d time.Duration) Option
  • func WithRootCAs(pool *x509.CertPool) Option
  • func WithTLSHandshakeTimeout(d time.Duration) Option
  • func WithTimeout(d time.Duration) Option
  • func WithUserAgent(ua string) Option
• type Response

Constants

const (
	// DefaultTimeout is the default whole-request timeout (re-export of core.DefaultTimeout).
	DefaultTimeout = core.DefaultTimeout
	// DefaultResponseHeaderTimeout is the default budget for the response headers, five seconds,
	// which WithTimeout does not lift; raise it with WithResponseHeaderTimeout.
	DefaultResponseHeaderTimeout = core.DefaultResponseHeaderTimeout
	// DefaultTLSHandshakeTimeout is the default budget for the TLS handshake, five seconds, which
	// WithTimeout does not lift; raise it with WithTLSHandshakeTimeout.
	DefaultTLSHandshakeTimeout = core.DefaultTLSHandshakeTimeout
)

Default request budgets. A request is bounded by all three, and WithTimeout sets only the first.

const (
	// ReportAll materializes the leaves in force at their schema default.
	ReportAll = core.DefaultsReportAll
	// Explicit returns the leaves a client set, including any set to their schema default.
	Explicit = core.DefaultsExplicit
)

Variables

var (
	ErrAuthenticationFailed = core.ErrAuthenticationFailed
	ErrAccessForbidden      = core.ErrAccessForbidden
	ErrResourceNotFound     = core.ErrResourceNotFound
	ErrInvalidConfiguration = core.ErrInvalidConfiguration
	ErrRequestTimeout       = core.ErrRequestTimeout
)

Error sentinels re-exported for consumer side error handling with errors.Is.

Functions

func GetDataInto

func GetDataInto[T any](ctx context.Context, c *Client, path string, opts ...GetOption) (*T, error)

GetDataInto reads a RESTCONF data path this package has no typed accessor for and decodes it into T, applying the envelope check every typed accessor gets: the response must carry exactly one top-level key, module-qualified and naming the node the path asked for, and T must declare a field for that key. GetData leaves all of that to the caller.

T is the envelope type, so it must be a struct whose outermost tag is the module-qualified node name — the shape every Cisco…Data type in this module's service packages has. A map or any other non-struct is refused, because the check asks whether T can consume the key rather than trusting it to. The check is top-level only: a tag below the top naming a node the response does not carry still decodes to nothing.

It is a function rather than a method on Client because a generic method, which this toolchain does accept, may not be declared in an interface and is invisible to reflect — so a consumer could neither put this behind a seam of its own nor reach it by reflection.

Types

type APIError

type APIError = core.APIError

APIError is returned for HTTP error responses (type alias to preserve instanceof semantics with errors.As).

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents the unified WNC API client with access to all domain services. This provides a single-import approach to accessing all wireless controller functionality.

func NewClient

func NewClient(host, token string, opts ...Option) (*Client, error)

NewClient creates a new unified WNC client with the specified host, token, and options. This is the main entry point for all wireless controller operations.

host is an authority and nothing else — "wnc1.example.internal" or "192.0.2.10:443". A scheme, a path, a query, a fragment, userinfo or an IPv6 zone id is refused with ErrInvalidConfiguration rather than concatenated into a URL that reads another node.

func (*Client) AFC

func (c *Client) AFC() afc.Service

AFC returns the Automated Frequency Coordination service.

func (*Client) AP

func (c *Client) AP() ap.Service

AP returns the Access Point service.

func (*Client) APF

func (c *Client) APF() apf.Service

APF returns the Application Policy Framework service.

func (*Client) AWIPS

func (c *Client) AWIPS() awips.Service

AWIPS returns the Automated Wireless Intrusion Prevention System service.

func (*Client) BLE

func (c *Client) BLE() ble.Service

BLE returns the Bluetooth Low Energy service.

func (*Client) CTS

func (c *Client) CTS() cts.Service

CTS returns the Cisco TrustSec service.

func (*Client) Client

func (c *Client) Client() client.Service

Client returns the wireless client service.

func (*Client) CloseIdleConnections

func (c *Client) CloseIdleConnections()

CloseIdleConnections closes the pooled connections that have no request on them, releasing the sockets a long-lived process would otherwise hold open after its last read. A connection in use is left alone and the client stays usable afterwards: the next request dials again.

func (*Client) Controller

func (c *Client) Controller() controller.Service

Controller returns the controller management service.

func (*Client) DeleteData

func (c *Client) DeleteData(ctx context.Context, path string) ([]byte, error)

DeleteData removes a node at a RESTCONF data path (RFC 8040 4.7).

func (*Client) Dot11

func (c *Client) Dot11() dot11.Service

Dot11 returns the 802.11 wireless standard service.

func (*Client) Dot15

func (c *Client) Dot15() dot15.Service

Dot15 returns the 802.15 standard service.

func (*Client) Fabric

func (c *Client) Fabric() fabric.Service

Fabric returns the Fabric service.

func (*Client) Flex

func (c *Client) Flex() flex.Service

Flex returns the FlexConnect service.

func (*Client) General

func (c *Client) General() general.Service

General returns the general controller service.

func (*Client) Geolocation

func (c *Client) Geolocation() geolocation.Service

Geolocation returns the geolocation service.

func (*Client) GetData

func (c *Client) GetData(ctx context.Context, path string, opts ...GetOption) ([]byte, error)

GetData reads a RESTCONF data path this package has no typed accessor for and returns the body as received. The /restconf/data prefix is optional and GetOption values apply as they do to a typed read.

Three things the body does not say for itself. The response carries exactly one top-level key, the module-qualified name of the node requested, so check that key rather than trusting a struct tag: a tag naming a key the controller did not send decodes to nothing and reports success. A node holding nothing answers with no body, so the slice is non-nil and empty with a nil error — check the length before decoding. The path is sent as given, so a caller keying into a list escapes the key itself, an unescaped "#" or "?" ending the path early and reading a different node without error.

func (*Client) Hyperlocation

func (c *Client) Hyperlocation() hyperlocation.Service

Hyperlocation returns the hyperlocation service.

func (*Client) LISP

func (c *Client) LISP() lisp.Service

LISP returns the LISP service.

func (*Client) Location

func (c *Client) Location() location.Service

Location returns the location services service.

func (*Client) MDNS

func (c *Client) MDNS() mdns.Service

MDNS returns the multicast DNS service.

func (*Client) Mcast

func (c *Client) Mcast() mcast.Service

Mcast returns the multicast service.

func (*Client) Mesh

func (c *Client) Mesh() mesh.Service

Mesh returns the mesh networking service.

func (*Client) Mobility

func (c *Client) Mobility() mobility.Service

Mobility returns the mobility management service.

func (*Client) NMSP

func (c *Client) NMSP() nmsp.Service

NMSP returns the Network Mobility Services Protocol service.

func (*Client) PatchData

func (c *Client) PatchData(ctx context.Context, path string, payload any) ([]byte, error)

PatchData merges a payload into a node at a RESTCONF data path. This package sends application/yang-data+json, so the edit is the plain patch of RFC 8040 4.6.1: a leaf absent from the payload is left alone, and no payload deletes anything.

A typed struct cannot clear a leaf, because encoding/json drops a zero field carrying omitempty before the payload is built, and its absence then means "leave alone". Send the leaf as bytes to set it to its zero, and DeleteData to remove it.

func (*Client) PolicyTag

func (c *Client) PolicyTag() *wlan.PolicyTagService

PolicyTag returns the Policy Tag service for policy tag management operations. This provides direct access to policy tag CRUD operations without going through WLAN service.

func (*Client) PostData

func (c *Client) PostData(ctx context.Context, path string, payload any) ([]byte, error)

PostData creates a node under a RESTCONF data path (RFC 8040 4.4).

func (*Client) PostRPC

func (c *Client) PostRPC(ctx context.Context, path string, payload any) ([]byte, error)

PostRPC invokes an operation on a RESTCONF operations path (RFC 8040 3.6 and 4.4.2). The path is the RPC name, module-qualified as the controller publishes it, with or without the /restconf/operations prefix, and the payload is normally an object under a single "input" key.

func (*Client) PutData

func (c *Client) PutData(ctx context.Context, path string, payload any) ([]byte, error)

PutData replaces a node at a RESTCONF data path (RFC 8040 4.5). A typed struct carrying omitempty marshals fewer leaves than it decoded, so replacing a node with one removes the rest.

func (*Client) RF

func (c *Client) RF() rf.Service

RF returns the Radio Frequency management service.

func (*Client) RFID

func (c *Client) RFID() rfid.Service

RFID returns the RFID service.

func (*Client) RFTag

func (c *Client) RFTag() *rf.RFTagService

RFTag returns the RF Tag service for RF tag management operations. This provides direct access to RF tag CRUD operations without going through RF service.

func (*Client) RRM

func (c *Client) RRM() rrm.Service

RRM returns the Radio Resource Management service.

func (*Client) Radio

func (c *Client) Radio() radio.Service

Radio returns the radio management service.

func (*Client) Request

func (c *Client) Request(ctx context.Context, method, path string, payload any) (*Response, error)

Request performs a request with the given method on the path as the caller wrote it, for whatever the verb methods above cannot express: a method RESTCONF gains later, a bodiless probe such as HEAD, or a query parameter this package has no option for.

A path already under /restconf/operations is sent to the operations root and anything else to the data root, which passes a /restconf/data-prefixed path through and prefixes a bare one.

On the data root the method is sent as given and is checked against neither the path nor the payload; the one value rejected is the empty string, which net/http reads as GET. The operations root takes POST alone, and another method there is refused rather than replaced: this package would send POST regardless, invoking the operation instead of doing what was asked.

This is the one method here that returns the status as well as the body, because it is the one with no fixed verb: 201, 204 and an empty 200 all answer with no body, so the body alone cannot say whether the node held nothing, was created or was replaced. The Response is non-nil exactly when the error is nil, and a status of 400 or above arrives as an *APIError rather than in it.

func (*Client) Rogue

func (c *Client) Rogue() rogue.Service

Rogue returns the rogue access point detection service.

func (*Client) Site

func (c *Client) Site() site.Service

Site returns the site management service.

func (*Client) SiteTag

func (c *Client) SiteTag() *site.SiteTagService

SiteTag returns the Site Tag service for site tag management operations. This provides direct access to site tag CRUD operations without going through Site service.

func (*Client) Spaces

func (c *Client) Spaces() spaces.Service

Spaces returns the Cisco Spaces integration service. EXPERIMENTAL: Requires IOS-XE 17.15.1+.

func (*Client) URWB

func (c *Client) URWB() urwb.Service

URWB returns the Ultra Reliable Wireless Backhaul service. EXPERIMENTAL: Requires IOS-XE 17.18.1+.

func (*Client) WAT

func (c *Client) WAT() wat.Service

WAT returns the Wireless Application Templates service. EXPERIMENTAL: Requires IOS-XE 17.18.1+.

func (*Client) WLAN

func (c *Client) WLAN() wlan.Service

WLAN returns the WLAN configuration service.

type DefaultsMode

type DefaultsMode = core.DefaultsMode

DefaultsMode selects the RFC 6243 retrieval mode for WithDefaults.

type GetOption

type GetOption = core.GetOption

GetOption customizes a single GET request (re-export of internal core.GetOption).

func WithDefaults

func WithDefaults(mode DefaultsMode) GetOption

WithDefaults requests the given with-defaults retrieval mode (RFC 8040 4.8.9). Scope it to the container that needs it: on a whole-container read the added leaves accumulate across every nested container.

func WithDepth

func WithDepth(levels int) GetOption

WithDepth limits the answer to an RFC 8040 4.8.2 subtree depth (re-export wrapper). A node the limit cuts is absent exactly as a pruned leaf is, so an absent leaf still decodes to a zero value; bound the depth to what the caller reads.

func WithFields

func WithFields(expression string) GetOption

WithFields limits the answer to an RFC 8040 4.8.3 fields expression (re-export wrapper). A pruned leaf is absent, and an absent leaf decodes to a zero value, so prune only the fields the caller reads.

type Option

type Option = core.Option

Option is a functional option for configuring the unified client (re-export of internal core.Option). This allows end users to supply options without importing the internal/core package.

func WithClientCertificate

func WithClientCertificate(cert tls.Certificate) Option

WithClientCertificate presents cert to the controller (re-export wrapper), for a deployment that authenticates the client with mTLS as well as with the Authorization header.

func WithInsecureSkipVerify

func WithInsecureSkipVerify(skip bool) Option

WithInsecureSkipVerify controls TLS certificate verification (lab/testing only).

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets a custom slog.Logger. Unset, the client logs to slog.Default(), so pass WithLogger(slog.New(slog.DiscardHandler)) where the SDK should write nothing.

func WithProxy

func WithProxy(fn func(*http.Request) (*url.URL, error)) Option

WithProxy routes requests through the proxy the resolver returns (re-export wrapper).

func WithResponseHeaderTimeout

func WithResponseHeaderTimeout(d time.Duration) Option

WithResponseHeaderTimeout bounds the wait for the response headers (re-export wrapper).

func WithRootCAs

func WithRootCAs(pool *x509.CertPool) Option

WithRootCAs verifies the controller's certificate against pool instead of the host's roots (re-export wrapper). Prefer it to WithInsecureSkipVerify where the controller presents a certificate from a private CA: the certificate is then verified rather than unverified.

func WithTLSHandshakeTimeout

func WithTLSHandshakeTimeout(d time.Duration) Option

WithTLSHandshakeTimeout bounds the TLS handshake (re-export wrapper).

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the whole-request timeout (re-export wrapper). It lifts neither DefaultResponseHeaderTimeout nor DefaultTLSHandshakeTimeout, so a caller that raises this alone is still capped at five seconds for the headers, which is when a busy controller is slowest. Raise those with WithResponseHeaderTimeout and WithTLSHandshakeTimeout.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets a custom User-Agent header value.

type Response

type Response = core.Response

Response is what Request returned: the controller's status and the body as it sent it (re-export of internal core.Response). An alias rather than a distinct type, so a caller can name it in a variable, a struct field or a test double.