TySS-Dev/nearby
1
0
Fork 0
mirror of https://github.com/kidfromjupiter/nearby.git synced 2026-09-14 14:46:12 -04:00
Code Issues Packages Projects Releases Wiki Activity
Page: API
Pages
API Bandwidth Upgrade Development Environment and Building Discovery and Advertising Feature Flags Home Mediums Testing and Implementations
Clone
3
API
kidfromjupiter edited this page 2026-01-23 08:55:39 +05:30
Table of Contents

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.