# Class VoipPush

java.lang.Object
com.codename1.call.voip.VoipPush

public final class VoipPush extends Object

Ringing when the app is not running.

A VoIP push is a push the operating system delivers straight to the calling machinery, launching the app if it has to. It is the only way an app that is not running can make the phone ring.

    VoipPush.setListener(new VoipPushListener() {
        public void callReceived(PushedCall call) {
            if (call.isStale()) { history.addMissed(call.getHandle()); return; }
            signalling.attach(call.getSession().getCallId(), call.getData());
        }
        public void tokenChanged(String token) { server.registerVoip(token); }
    });
    VoipPush.register();

##### The payload has a fixed shape, and the server must honour it

Because the call is reported to the system before any Java runs, the native code parses the push itself. It looks for one key:

    { "cn1call": { "uuid": "6B29FC40-CA47-1067-B31D-00DD010662DA",
                   "handle": "+14155551212", "handleType": "phoneNumber",
                   "displayName": "Jane Doe", "video": false,
                   "ttl": 30, "data": "opaque, handed back untouched" } }

`uuid` and `handle` are required; the rest have defaults from the build hints. `data` is never parsed by the framework. Sending a payload without `cn1call` means the app is woken and nothing rings -- on iOS, that is the case that gets the app killed.

To retract a call that was cancelled before it was answered, send the same `uuid` with `"cancel": true`.

##### Set the listener before registering

Calls that arrived before the app was listening are held and delivered when `setListener(VoipPushListener)` installs one. An app that registers first and listens later still gets them -- the queue is drained on the first listener -- but an app that never sets a listener will find its calls timed out and ended by the platform.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `getToken()`
  The last known token, or null.
  `static boolean`
  `isSupported()`
  Whether this platform can be woken by a VoIP push.
  `static AsyncResource<String>`
  `register()`
  Registers for VoIP pushes, resolving with the token to give the application's server.
  `static void`
  `setListener(VoipPushListener l)`
  Installs the listener and immediately drains any calls that arrived before the app was listening.
  `static void`
  `unregister()`
  Stops VoIP push delivery.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### isSupported

    public static boolean isSupported()
    Whether this platform can be woken by a VoIP push.

  - ### setListener

    public static void setListener(VoipPushListener l)
    Installs the listener and immediately drains any calls that arrived before the app was listening.

  - ### register

    public static AsyncResource<String> register()

    Registers for VoIP pushes, resolving with the token to give the application's server.

    Errors with `CallError.NOT_SUPPORTED` where `isSupported()` is false, rather than resolving with a token that could never receive anything.

  - ### unregister

    public static void unregister()
    Stops VoIP push delivery.

  - ### getToken

    public static String getToken()
    The last known token, or null.