API

This page documents the public Core API surface and how V3 maps to the legacy API in this codebase.

Core (legacy / V1)

• Located at connections/core.h and implemented in connections/core.cc.
• Key operations:
  • Advertising / Discovery: StartAdvertising, StopAdvertising, StartDiscovery, StopDiscovery.
  • Connection lifecycle: RequestConnection, AcceptConnection, RejectConnection, DisconnectFromEndpoint, StopAllEndpoints.
  • Payloads: SendPayload, CancelPayload.
  • Bandwidth upgrade: InitiateBandwidthUpgrade(endpoint_id).
  • Misc: SetCustomSavePath, GetLocalEndpointId, Dump().

V3 API

• Exposed as StartAdvertisingV3, StartDiscoveryV3, RequestConnectionV3, AcceptConnectionV3, etc. and uses V3-specific types:
  • v3::AdvertisingOptions, v3::DiscoveryOptions, v3::ConnectionListener, v3::ConnectionsDevice / NearbyDevice.
• V3 provides richer structures (e.g. v3::BandwidthInfo) and strongly-typed device representations.

V3 -> V1 mapping (how it works in core.cc)

• The V3 methods convert v3 options/objects into the legacy AdvertisingOptions/DiscoveryOptions and ConnectionRequestInfo and then call the V1 implementation (e.g. StartAdvertisingV3 constructs an old AdvertisingOptions then calls router_->StartAdvertising). See Core::StartAdvertisingV3 and Core::StartDiscoveryV3.
• Because V3 currently bridges to the legacy routing stack, the code contains compatibility glue. The Core header warns: "Do NOT mix with the V1 APIs above" for safety; calling both styles in one process can produce undefined behavior.

What about V2?

• The codebase contains references to core_v2 in comments (e.g. some internal headers mention cpp/core_v2/core.h), but in this repository the first-class APIs are V1 (legacy) and V3. There is no complete core_v2 directory in nearby_latest—it appears to be a referenced or historical intermediate.

Usage patterns and examples (high level)

1. Advertising & discovery: call StartAdvertising(...) on one device and StartDiscovery(...) on another with matching service_id.
2. Connection: the scanner receives an endpoint -> call RequestConnection(endpoint_id, ...); the advertiser receives OnConnectionInitiated and calls AcceptConnection(endpoint_id, payload_listener).
3. Once accepted, use SendPayload to send files/streams/bytes.
4. To improve throughput, call InitiateBandwidthUpgrade(endpoint_id) to attempt a BWU via BwuManager.

References

• connections/core.h, connections/core.cc
• connections/implementation/service_controller_router.* (routing/mapping)
• connections/v3/* for V3 data structures

Notes & cautions

• Prefer V3 for new integrations where possible, but note the code currently bridges V3 to the legacy routing stack.
• Do not mix V1 and V3 calls within the same Core usage pattern unless you understand the bridging and lifetime semantics.