Skip to content

Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.

8.2 KB
Raw Blame

Calls service (protocol v0)

Status: draft. Builds on protocol v0; breaking changes are allowed until v1. License: CC BY 4.0.

A phone tells its PCs about its calls: who's calling, when it's answered, and when it ends. A PC can answer, decline or silence a ringing call, hang up, mute, switch to the speaker, hold, press keypad keys and change the volume of the call in progress, browse recent calls, and ask the phone to call a number. The call's audio stays on the phone; this service carries no sound.

1. Capabilities

ID Offered by Meaning
call.state phone Reports its calls (needs the phone permission)
call.control phone Answers, declines, silences and hangs up calls, and changes their volume, when a PC asks
call.incall phone Also mutes, switches to the speaker, holds and presses keys on the call in progress, and reports those controls
call.log phone Lists recent calls (needs the call log permission)
call.dial phone Places a call (or opens the dialer with the number filled in) when a PC asks
call.sims phone Lists the SIMs it calls with, and places a call on the one a PC picks
call.show PC Shows calls, recent calls and the dialer, and wants call.log.changed

A phone reports calls and answers call requests only for PCs that offer call.show, and only while both devices allow it (the calls device toggle, on by default, on each side).

2. Messages

On the control stream.

t = "call.state"            b = {
  id:        text,      // The phone's ID for this call: 1 to 64 bytes, the same in each of its messages
  state:     "ringing" | "active" | "ended",
  ? incoming: bool,     // Default true; false for calls the phone's user made
  ? number:  text,      // At most 256 bytes, when the phone knows it
  ? name:    text,      // The contact's name, when the number is a contact
  ? photo:   bytes,     // The contact's photo, a JPEG of at most 64 KiB, with "ringing"
  ? missed:  bool,      // With "ended": it rang and nobody answered (default false)
  ? since:   int,       // With "active": when it was answered, in Unix milliseconds
  ? controls: {         // With "active", from a phone offering call.incall
      ? muted:    bool,     // The phone's microphone is muted
      ? speaker:  bool,     // The sound is on the speaker
      ? held:     bool,     // The call is on hold
      ? can_hold: bool,     // The call can be held
    },
}
t = "call.action"  id = n   b = {
  id:      text,
  action:  "answer" | "decline" | "silence"
         | "mute" | "unmute" | "speaker" | "earpiece" | "hold" | "unhold"
         | "dtmf" | "volume_up" | "volume_down",
  ? digit: text,        // With "dtmf": one of 0 to 9, * and #
}
t = "ok"           re = n

t = "call.log"          id = n   b = { ? before: int, limit: uint }          // 1 to 100
t = "call.log"          re = n   b = { entries: [ call_entry ] }             // newest first

t = "call.log.changed"           b = {}                                      // phone → PC

t = "call.dial"         id = n   b = { number: text, ? sim: text }       // sim: an id from call.sims
t = "ok"                re = n

t = "call.sims"         id = n   b = {}
t = "call.sims"         re = n   b = { sims: [ { id: text, label: text } ], ? default: text }

call_entry = {
  id:        text,
  number:    text,      // Who called, or who was called ("" when withheld)
  ? name:    text,      // The contact's name, when the number is a contact
  direction: "incoming" | "outgoing" | "missed" | "rejected",
  date:      int,       // When the call started, in Unix milliseconds
  duration:  uint,      // Seconds on the call (0 when missed or not answered)
  ? photo:   bytes,     // The contact's photo, a JPEG of at most 16 KiB
}

2.1 call.state

Sent when a call starts ringing (and again when the phone learns more, such as the number), when it's answered, whenever its controls change, and when it ends. Not answered. A PC that connects during a call gets its latest call.state right away.

controls is there only while the phone can change them: a PC shows mute, speaker, hold and the keypad only then.

A call that was declined, on the phone or from a PC, ends without missed.

2.2 call.action

  • answer: answers the ringing call; the conversation happens on the phone.
  • decline: declines the ringing call, or hangs up the active one.
  • silence: stops the phone ringing; the call still rings for the caller.
  • volume_up, volume_down: the active call's volume (call.control).
  • mute, unmute, speaker, earpiece, hold, unhold: as named, on the active call (call.incall). The new state comes back in call.state.
  • dtmf: plays the keypad tone digit on the active call (call.incall).

Errors: NOT_FOUND when id isn't the call in progress, or the action doesn't fit its state (answer and silence need it ringing; the others, except decline, need it active); DENIED when calls are off for the PC; UNSUPPORTED for an unknown action, a dtmf without a valid digit, or when the phone doesn't offer the capability the action needs.

2.3 call.log and call.log.changed

call.log pages back through the phone's recent calls, newest first: before is the oldest date already shown. A phone answers with fewer items than limit when the answer wouldn't fit in a frame (v0 §3), dropping the oldest.

The phone sends call.log.changed to connected PCs that offer call.show when its call log changes (debounced). PCs then ask again for what they show.

Errors: DENIED when calls are off for the PC, UNSUPPORTED when the phone doesn't offer call.log.

2.4 call.dial

call.dial asks the phone to call number (1 to 256 bytes, not blank). With CALL_PHONE permission the phone places the call directly (Intent.ACTION_CALL); if that permission isn't granted, it opens the dialer (Intent.ACTION_DIAL) with the number filled in. Once the call starts, the phone reports it through call.state, so the PC's call card and in-call controls work as for any call.

With sim (an id from call.sims, 1 to 64 bytes), a phone that offers call.sims places the call on that SIM, or on its default if the SIM is gone; phones from before sim ignore it. A PC sends sim only to a phone that offers call.sims.

Errors: DENIED when calls are off for the PC, UNSUPPORTED when the phone doesn't offer call.dial, INTERNAL when the phone couldn't start the call.

2.4.1 call.sims

call.sims asks which SIMs (and calling apps, such as a SIP account) the phone places calls with: at most 8, each with an id that stays the same while the SIM is in and a label as Android shows it ("SIM 1 · Airtel"), and default when the phone calls with one without asking. A phone set to ask each time has no default, and Android would ask on the phone, where nobody at the PC sees it, so the PC picks one: the user's choice for that phone, else the first. With one SIM there's nothing to pick.

Errors: DENIED when calls are off for the PC, UNSUPPORTED when the phone doesn't offer call.sims.

2.5 On Android

call.control needs the phone permission and the permission to answer calls. call.log needs the call log permission. call.dial uses CALL_PHONE to place the call directly, or opens the dialer when CALL_PHONE isn't granted. call.sims needs CALL_PHONE and READ_PHONE_STATE: it lists TelecomManager.getCallCapablePhoneAccounts() and calls with EXTRA_PHONE_ACCOUNT_HANDLE. call.incall needs Android 12 or later and the MANAGE_ONGOING_CALLS app-op, which lets Telecom bind NectarLink's in-call service as a calling companion without it being the phone app. Apps can't grant that app-op to themselves; NectarLink's Elevated mode (Wireless debugging) grants it through the shell when it starts.

Not in this service:

  • Recording calls. Android doesn't let apps other than the phone's own record call audio (capturing the voice call stream needs a privileged permission), so NectarLink doesn't offer it.
  • Talking through the PC. Carrying the call's audio to the PC's microphone and speakers is planned as a Bluetooth hands-free (HFP) link from the PC to the phone, as for a headset; it isn't part of this service.

3. Privacy

Numbers, names and photos are never logged (v0 §11).