SmartDeviceLink - JavaSE Guides

The GetWayPoints and SubscribeWayPoints RPCs are designed to allow you to get the navigation destination(s) from the active navigation app when the user has activated in-car navigation.

Checking Your App's Permissions

Both the GetWayPoints and SubscribeWayPoints RPCs are restricted by most 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 get waypoints 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.GET_WAY_POINTS, null), new PermissionElement(FunctionID.SUBSCRIBE_WAY_POINTS, null)), PermissionManager.PERMISSION_GROUP_TYPE_ANY, new OnPermissionChangeListener() {
    @Override
    public void onPermissionsChange(@NonNull Map<FunctionID, PermissionStatus> allowedPermissions, @NonNull int permissionGroupStatus) {
        PermissionStatus getWayPointPermissionStatus = allowedPermissions.get(FunctionID.GET_WAY_POINTS);
        if (getWayPointPermissionStatus != null && getWayPointPermissionStatus.getIsRPCAllowed()) {
            // Your app has permission to send the `GetWayPoints` request for its current HMI level
        } else {
            // Your app does not have permission to send the `GetWayPoints` request for its current HMI level
        }

        PermissionStatus subscribeWayPointsPermissionStatus = allowedPermissions.get(FunctionID.SUBSCRIBE_WAY_POINTS);
        if (subscribeWayPointsPermissionStatus != null && subscribeWayPointsPermissionStatus.getIsRPCAllowed()) {
            // Your app has permission to send the `SubscribeWayPoints` request for its current HMI level
        } else {
            // Your app does not have permission to send the `SubscribeWayPoints` request for its current HMI level
        }
    }
});

Checking if the Module Supports Waypoints

Since some modules will not support getting waypoints, you should check if the module supports this feature before trying to use it. 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 getting waypoints, 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 getting navigation waypoints 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 GetWayPoints or SubscribeWayPoints requests.

private void isGetWaypointsSupported(final OnCapabilitySupportedListener capabilitySupportedListener) {
    // Check if the module has navigation capabilities
    if (!sdlManager.getSystemCapabilityManager().isCapabilitySupported(SystemCapabilityType.NAVIGATION)) {
        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 `GetWayPoints` and `SubscribeWayPoints` are 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 navigation capability
    sdlManager.getSystemCapabilityManager().getCapability(SystemCapabilityType.NAVIGATION, new OnSystemCapabilityListener() {
        @Override
        public void onCapabilityRetrieved(Object capability) {
            NavigationCapability navigationCapability = (NavigationCapability) capability;
            capabilitySupportedListener.onCapabilitySupported(navigationCapability != null ? navigationCapability.getWayPointsEnabled() : false);
        }

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

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

Subscribing to Waypoints

To subscribe to the navigation waypoints, you will have to set up your callback for whenever the waypoints are updated, then send the SubscribeWayPoints RPC.

// You can subscribe any time before SDL would send the notification (such as when you call `sdlManager.start` or at initialization of your manager)
sdlManager.addOnRPCNotificationListener(FunctionID.ON_WAY_POINT_CHANGE, new OnRPCNotificationListener() {
    @Override
    public void onNotified(RPCNotification notification) {
        OnWayPointChange onWayPointChangeNotification = (OnWayPointChange) notification;
        // Use the waypoint data
    }
});

// After SDL has started your connection, at whatever point you want to subscribe, send the subscribe RPC
SubscribeWayPoints subscribeWayPoints = new SubscribeWayPoints();
subscribeWayPoints.setOnRPCResponseListener(new OnRPCResponseListener() {
    @Override
    public void onResponse(int correlationId, RPCResponse rpcResponse) {
        if (rpcResponse.getSuccess()){
            // You are now subscribed
        } else {
            // Handle the errors
        }
    }
});

sdlManager.sendRPC(subscribeWayPoints);

Unsubscribing from Waypoints

To unsubscribe from waypoint data, you must send the UnsubscribeWayPoints RPC.

UnsubscribeWayPoints unsubscribeWayPoints = new UnsubscribeWayPoints();
unsubscribeWayPoints.setOnRPCResponseListener(new OnRPCResponseListener() {
    @Override
    public void onResponse(int correlationId, RPCResponse rpcResponse) {
        if (rpcResponse.getSuccess()){
            // You are now unsubscribed
        } else {
            // Handle the errors
        }
    }
});

sdlManager.sendRPC(unsubscribeWayPoints);

One-Time Waypoints Request

If you only need waypoint data once without an ongoing subscription, you can use GetWayPoints instead of SubscribeWayPoints.

GetWayPoints getWayPoints = new GetWayPoints();
getWayPoints.setOnRPCResponseListener(new OnRPCResponseListener() {
    @Override
    public void onResponse(int correlationId, RPCResponse rpcResponse) {
        if (rpcResponse.getSuccess()){
            GetWayPointsResponse getWayPointsResponse = (GetWayPointsResponse) rpcResponse;
            // Use the waypoint data
        } else {
            // Handle the errors
        }
    }
});

sdlManager.sendRPC(getWayPoints);

View on GitHub.com