nearby/sharing/linux/QUICK_REFERENCE.md

Nearby Sharing Linux - Quick Reference

Quick Start

Build

bazel build //sharing/linux:simple_example
bazel build //sharing/linux:nearby_sharing_app

Run Simple Example

# Terminal 1 (Receiver)
./bazel-bin/sharing/linux/simple_example receiver

# Terminal 2 (Sender)
./bazel-bin/sharing/linux/simple_example sender "Hello World!"

Run Full App

./bazel-bin/sharing/linux/nearby_sharing_app [device_name]

API Cheat Sheet

Include Headers

#include "sharing/linux/nearby_sharing_service_linux.h"
#include "sharing/attachment_container.h"
#include "sharing/file_attachment.h"
#include "sharing/text_attachment.h"
#include "sharing/share_target.h"
#include "sharing/transfer_metadata.h"

Create Service

using namespace nearby::sharing::linux;
NearbySharingServiceLinux service("DeviceName");

Implement Callbacks

// Transfer updates
class MyCallback : public TransferUpdateCallback {
  void OnTransferUpdate(const ShareTarget& target,
                       const AttachmentContainer& attachments,
                       const TransferMetadata& metadata) override {
    // Handle status changes
  }
};

// Device discovery
class MyDiscovery : public ShareTargetDiscoveredCallback {
  void OnShareTargetDiscovered(const ShareTarget& target) override { }
  void OnShareTargetLost(const ShareTarget& target) override { }
  void OnShareTargetUpdated(const ShareTarget& target) override { }
};

Register to Receive

service.RegisterReceiveSurface(
    &transfer_callback,
    NearbySharingService::ReceiveSurfaceState::kForeground,
    Advertisement::BlockedVendorId::kNone,
    [](auto status) { /* callback */ });

Register to Send

service.RegisterSendSurface(
    &transfer_callback,
    &discovery_callback,
    NearbySharingService::SendSurfaceState::kForeground,
    Advertisement::BlockedVendorId::kNone,
    false, // disable_wifi_hotspot
    [](auto status) { /* callback */ });

Send File

auto container = std::make_unique<AttachmentContainer>();
container->AddFileAttachment(FileAttachment(FilePath("/path/to/file")));
service.SendAttachments(target_id, std::move(container), [](auto) {});

Send Text

auto container = std::make_unique<AttachmentContainer>();
container->AddTextAttachment(TextAttachment(
    TextAttachment::Type::TEXT, "message", std::nullopt, std::nullopt));
service.SendAttachments(target_id, std::move(container), [](auto) {});

Accept/Reject/Cancel

service.Accept(target_id, [](auto status) {});
service.Reject(target_id, [](auto status) {});
service.Cancel(target_id, [](auto status) {});

Check Status

bool scanning = service.IsScanning();
bool transferring = service.IsTransferring();
bool bt_present = service.IsBluetoothPresent();
bool bt_powered = service.IsBluetoothPowered();

Shutdown

service.Shutdown([](auto status) {});

Transfer Statuses

Status	Meaning	Action
kConnecting	Establishing connection	Wait
kAwaitingLocalConfirmation	Need to accept/reject	Call Accept() or Reject()
kAwaitingRemoteAcceptance	Waiting for remote	Wait
kInProgress	Transferring data	Show progress
kComplete	Success	Access attachments
kFailed	Error occurred	Check logs
kRejected	User rejected	Retry or cancel
kCancelled	Transfer cancelled	Cleanup
kTimedOut	Connection timeout	Retry

Status Codes

Code	Meaning
kOk	Success
kError	General error
kOutOfOrderApiCall	API called incorrectly
kTransferAlreadyInProgress	Can't start new transfer
kNoAvailableConnectionMedium	No Bluetooth/WiFi
kInvalidArgument	Bad parameters

Common Patterns

Auto-Accept Pattern

class AutoAccept : public TransferUpdateCallback {
  void OnTransferUpdate(...) override {
    if (metadata.status() == Status::kAwaitingLocalConfirmation) {
      service_->Accept(target.id, [](auto) {});
    }
  }
};

Progress Tracking Pattern

void OnTransferUpdate(...) override {
  if (metadata.status() == Status::kInProgress) {
    int percent = metadata.progress() * 100;
    uint64_t bytes = metadata.transferred_bytes();
    std::cout << percent << "% (" << bytes << " bytes)" << std::endl;
  }
}

Device Selection Pattern

std::vector<ShareTarget> devices;

void OnShareTargetDiscovered(const ShareTarget& target) override {
  devices.push_back(target);
  std::cout << devices.size() << ". " << target.device_name << std::endl;
}

void SendToDevice(size_t index) {
  if (index < devices.size()) {
    SendFile(devices[index].id, file_path);
  }
}

Error Handling Pattern

service.SendAttachments(target_id, container,
    [](NearbySharingService::StatusCodes status) {
      if (status != StatusCodes::kOk) {
        std::cerr << "Error: " 
                 << NearbySharingService::StatusCodeToString(status) 
                 << std::endl;
        return;
      }
      std::cout << "Transfer initiated" << std::endl;
    });

Debugging Tips

Enable Verbose Logging

// Set environment variable
export NEARBY_LOGS=VERBOSE

Check Bluetooth

if (!service.IsBluetoothPresent()) {
  std::cout << "No Bluetooth adapter found" << std::endl;
}
if (!service.IsBluetoothPowered()) {
  std::cout << "Bluetooth is off" << std::endl;
}

Dump Service State

std::cout << service.Dump() << std::endl;
// Output: "NearbySharingServiceLinux advertising=true scanning=false ..."

Monitor Callbacks

void OnTransferUpdate(...) override {
  std::cout << "[Transfer] " << target.device_name 
           << " - " << TransferMetadata::StatusToString(metadata.status())
           << " - " << (metadata.progress() * 100) << "%" << std::endl;
}

File Locations

• Service: sharing/linux/nearby_sharing_service_linux.{h,cc}
• Simple Example: sharing/linux/simple_example.cc
• Full App: sharing/linux/nearby_sharing_app.cc
• README: sharing/linux/README.md
• Implementation Guide: sharing/linux/IMPLEMENTATION_GUIDE.md
• BUILD: sharing/linux/BUILD

Common Issues

"No devices found"

• Ensure receiver is running and advertising
• Check Bluetooth is enabled on both devices
• Verify devices are within range (~10m)
• Try restarting Bluetooth

"Transfer failed"

• Check file permissions
• Verify disk space
• Ensure stable connection
• Check firewall settings

"Invalid argument"

• Verify target_id is valid
• Ensure container has attachments
• Check surface is registered

Callback not called

• Verify callback lifetime (must outlive service)
• Check registration was successful
• Ensure main thread/event loop is running

Example Workflows

Send File Workflow

1. Create service
2. Create callbacks
3. RegisterSendSurface (foreground)
4. Wait for OnShareTargetDiscovered
5. Create AttachmentContainer
6. Add FileAttachment
7. SendAttachments(target_id, container)
8. Wait for kComplete in OnTransferUpdate

Receive File Workflow

1. Create service
2. Create callback
3. RegisterReceiveSurface (foreground)
4. Wait for kAwaitingLocalConfirmation
5. Call Accept(target_id)
6. Wait for kInProgress updates
7. Wait for kComplete
8. Access files from AttachmentContainer

Performance Notes

• Scanning: Consumes battery, stop when not needed
• Advertising: Minimal impact
• Transfer: WiFi Direct faster than Bluetooth
• File Size: Large files (>100MB) benefit from WiFi
• Small Files: Bluetooth sufficient for <10MB

Links

• README.md - Overview and features
• IMPLEMENTATION_GUIDE.md - Detailed architecture
• nearby_sharing_service.h - Base interface