Calling a Phone Number

The DialNumber RPC allows you make a phone call via the user's phone. In order to dial a phone number you must be sure that the device is connected via Bluetooth (even if your device is also connected using a USB cord) for this request to work. If the phone is not connected via Bluetooth, you will receive a result of REJECTED from the module.

Checking Your App's Permissions

DialNumber is an RPC that is usually restricted by OEMs. As a result, a module may reject your request if your app does not have the correct permissions. Your SDL app may also be restricted to only being allowed to making a phone call when your app is open (i.e. the hmiLevel is non-NONE) or when it is the currently active app (i.e. the hmiLevel is FULL).

UUID listenerId = sdlManager.getPermissionManager().addListener(Arrays.asList(new PermissionElement(FunctionID.DIAL_NUMBER, null)), PermissionManager.PERMISSION_GROUP_TYPE_ANY, new OnPermissionChangeListener() {
    @Override
    public void onPermissionsChange(@NonNull Map<FunctionID, PermissionStatus> allowedPermissions, int permissionGroupStatus) {
        if (permissionGroupStatus != PermissionManager.PERMISSION_GROUP_TYPE_ALL_ALLOWED) {
            // Your app does not have permission to send the `DialNumber` request for its current HMI level
            return;
        }

        // Your app has permission to send the `DialNumber` request for its current HMI level
    }
});

Checking if the Module Supports Calling a Phone Number

Since making a phone call is a newer feature, there is a possibility that some legacy modules will reject your request because the module does not support the DialNumber request. Once you have successfully connected to the module, you can check the module's capabilities via the sdlManager.getSystemCapabilityManager as shown in the example below. Please note that you only need to check once if the module supports calling a phone number, however you must wait to perform this check until you know that the SDL app has been opened (i.e. the hmiLevel is non-NONE).

Note

If you discover that the module does not support calling a phone number or that your app does not have the right permissions, you should disable any buttons, voice commands, menu items, etc. in your app that would send the DialNumber request.

private void isDialNumberSupported(final OnCapabilitySupportedListener capabilitySupportedListener) {
    // Check if the module has phone capabilities
    if (!sdlManager.getSystemCapabilityManager().isCapabilitySupported(SystemCapabilityType.PHONE_CALL)) {
        capabilitySupportedListener.onCapabilitySupported(false);
        return;
    }

    // Legacy modules (pre-RPC Spec v4.5) do not support system capabilities, so for versions less than 4.5 we will assume `DialNumber` is supported if `isCapabilitySupported()` returns true
    SdlMsgVersion sdlMsgVersion = sdlManager.getRegisterAppInterfaceResponse().getSdlMsgVersion();
    if (sdlMsgVersion == null) {
        capabilitySupportedListener.onCapabilitySupported(true);
        return;
    }
    Version rpcSpecVersion = new Version(sdlMsgVersion);
    if (rpcSpecVersion.isNewerThan(new Version(4, 5, 0)) < 0) {
        capabilitySupportedListener.onCapabilitySupported(true);
        return;
    }

    // Retrieve the phone capability
    sdlManager.getSystemCapabilityManager().getCapability(SystemCapabilityType.PHONE_CALL, new OnSystemCapabilityListener() {
        @Override
        public void onCapabilityRetrieved(Object capability) {
            PhoneCapability phoneCapability = (PhoneCapability) capability;
            capabilitySupportedListener.onCapabilitySupported(phoneCapability != null ? phoneCapability.getDialNumberEnabled() : false);
        }

        @Override
        public void onError(String info) {
            capabilitySupportedListener.onError(info);
        }
    }, false);
}

public interface OnCapabilitySupportedListener {
    void onCapabilitySupported(Boolean supported);
    void onError(String info);
}

Sending a DialNumber Request

Once you know that the module supports dialing a phone number and that your SDL app has permission to send the DialNumber request, you can create and send the request.

Note

DialNumber strips all characters except for 0-9, *, #, ,, ;, and +.

DialNumber dialNumber = new DialNumber()
    .setNumber("1238675309");
dialNumber.setOnRPCResponseListener(new OnRPCResponseListener() {
    @Override
    public void onResponse(int correlationId, RPCResponse response) {
        Result result = response.getResultCode();
        if(result.equals(Result.SUCCESS)){
            // `DialNumber` successfully sent
        }else if(result.equals(Result.REJECTED)){
            // `DialNumber` was rejected. Either the call was sent and cancelled or there is no device connected
        }else if(result.equals(Result.DISALLOWED)){
            // Your app is not allowed to use `DialNumber`
        }
    }
});

sdlManager.sendRPC(dialNumber);

Dial Number Responses

The DialNumber request has three possible responses that you should expect:

SUCCESS - The request was successfully sent, and a phone call was initiated by the user.
REJECTED - This can mean either:
- The user rejected the request to make the phone call.
- The phone is not connected to the module via Bluetooth.
DISALLOWED - Your app does not have permission to use the DialNumber request.

View on GitHub.com

Previous Section Next Section