Discovery and Advertising

This page explains how advertising and discovery are implemented and wired into the Core API.

API entry points (Core)

• Core::StartAdvertising(...) / Core::StopAdvertising(...)
• Core::StartDiscovery(...) / Core::StopDiscovery(...)
• V3 variants: StartAdvertisingV3, StartDiscoveryV3 which accept richer v3::AdvertisingOptions and v3::DiscoveryOptions types.

Routing and responsibilities

• Core delegates to ServiceControllerRouter (connections/implementation/service_controller_router.*).
• Router serializes requests on a single-threaded executor and forwards them to a ServiceController implementation (often OfflineServiceController).
• The ServiceController starts/stops PCP handlers which manage medium lifecycle (advertising/scanning/accept loops) and forward endpoint events to EndpointManager.

Advertising / Discovery options

• AdvertisingOptions and DiscoveryOptions (and their V3 counterparts) control:
  • Strategy (how endpoints are grouped/connected)
  • Enabled/allowed mediums (bluetooth, ble, web_rtc, wifi_lan, wifi_hotspot, wifi_direct, awdl)
  • auto_upgrade_bandwidth
  • power level (low/high)
  • enable_bluetooth_listening, enable_webrtc_listening
  • use_stable_endpoint_id / force_new_endpoint_id
  • fast_advertisement_service_uuid for BLE fast/extended

V3 -> V1 mapping

• StartAdvertisingV3 and StartDiscoveryV3 convert V3 options into the legacy AdvertisingOptions / DiscoveryOptions then call the old StartAdvertising/StartDiscovery paths. See Core::StartAdvertisingV3 and Core::StartDiscoveryV3 in connections/core.cc.

Out-of-band discovery and injection

• Core::InjectEndpoint(...) can be used to inject an endpoint into discovery when is_out_of_band_connection == true.
  • Meaning: the endpoint was discovered by an out-of-band mechanism (not by scanning medium advertisements) and is being injected into the discovery callback path using externally-provided metadata (OutOfBandConnectionMetadata). Common out-of-band sources include NFC taps, QR codes, cloud pairing, or manual entry of a Bluetooth MAC or service credentials.
  • Usage: callers set is_out_of_band_connection in DiscoveryOptions/ConnectionOptions when they expect to inject endpoints rather than rely on medium scanning. Core::InjectEndpoint(service_id, metadata, callback) delivers the discovery callback (DiscoveryListener::endpoint_found_cb) for the provided metadata so the app can act as if the endpoint was discovered normally.
• The router currently limits injection to Bluetooth in ServiceControllerRouter::InjectEndpoint (it validates that metadata.medium == Medium::BLUETOOTH and that remote_bluetooth_mac_address has length 6). The router also checks that metadata.endpoint_id and metadata.endpoint_info are well-formed and that the client is actively discovering (client->IsDiscovering()); on success it calls GetServiceController()->InjectEndpoint(...).

Medium-specific discovery mechanisms

• BLE: advertising (legacy/extended) and scanning via platform BLE APIs.

  • Note: Android advertises BLE packets using resolvable LE random addresses (one-per-advertisement) which allows advertising both Fast and Extended advertisements concurrently with different random addresses. Linux does not generally support per-advertisement LE random addresses and typically advertises from the same adapter MAC; registering both legacy (Fast) and extended adverts on the same MAC causes them to be interleaved intermittently. This can cause other devices to miss one or both adverts if their scanners assume a stable advertising address, so the Linux implementation prefers BLE Extended advertising instead of running both adverts on the same MAC.

• Wi‑Fi LAN: uses mDNS / NsdServiceInfo to advertise and discover services.

• Other mediums have their own discovery/advertising primitives (see Mediums.md).

References in code

• connections/core.h, connections/core.cc
• connections/implementation/service_controller_router.*
• connections/implementation/mediums/* (per-medium advertising & scanning code)