package com.codename1.call

System call integration: making a call this app carries look, to the operating system and to the user, like a call the phone itself placed.

That means the lock-screen call UI, the ringtone that plays while the app is not running, the entry in the system call log, the audio session the OS hands over and takes back, and the caller’s name shown for an incoming number the address book has never seen.

What this is not. Codename One does not carry the voice. There is no codec, no signalling and no WebRTC here, and none is planned: those are the app’s, and there are good libraries for them. What was missing was everything around the media – and without it an app could not ring at all while backgrounded, which is why a Codename One app could not previously be a calling app no matter how good its audio was.

The sub-packages are the opt-in

They are separate packages rather than one because referencing a package is the only opt-in there is. The build server decides what native machinery an app gets by scanning bytecode for these prefixes, and it has no way to express an exclusion.

com.codename1.call.session – report calls and receive the user’s answer, hold, mute and keypad actions. The place to start.
com.codename1.call.voip – ring when the app is not running, from a VoIP push. Costs the voip background mode, which Apple rejects an app for carrying without a working call implementation.
com.codename1.call.directory – name and block numbers the app knows about, for calls that have nothing to do with this app. Deliberately not a superset of the other two: a caller-ID app must not have to carry telephony permissions it never uses.

This package itself holds only what they share: CallError, CallException, CallHandle, CallHandleType, CallId, CallState, CallDirection, CallEndReason and CallAvailability. Referencing it alone costs nothing.

How this relates to what was already here

com.codename1.ui.Display#dial(String) hands a number to the system dialer and forgets about it; it places a cellular call and this app is not part of it. Nothing here replaces that, and an app that only wants to let the user phone somebody should keep using it.

com.codename1.ui.Display#isInCall() is a lifecycle heuristic and always was – on iOS it reports whether the app was interrupted, not whether a call exists. Calls is the real answer where it is available.

Types

`enum CallAvailability`	Whether the app may ring a call right now.
`enum CallDirection`	Which way a call was placed.
`enum CallEndReason`	Why a call ended.
`enum CallError`	Typed error codes carried by every `CallException` thrown through the failure path of the `com.codename1.call` APIs.
`class CallException`	Thrown through the failure path of every `AsyncResource` returned by the `com.codename1.call` APIs, and passed to the failure callbacks of the session and directory listeners.
`class CallHandle`	Who is on the other end: an address plus what kind of address it is.
`enum CallHandleType`	What kind of address a `CallHandle` holds.
`class CallId`	Canonical form of the identifier that names one call everywhere: in this API, in CallKit, in Telecom, and in the VoIP push payload a server sends.
`enum CallState`	Where a call is in its life.