SmartDeviceLink - JavaScript Suite Guides

The SendLocation RPC gives you the ability to send a GPS location to the active navigation app on the module.

When using the SendLocation RPC, you will not have access to any information about how the user interacted with this location, only if the request was successfully sent. The request will be handled by the module from that point on using the active navigation system.

Checking Your App's Permissions

The SendLocation RPC is 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 send a location 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).

const permissionElements = [];
permissionElements.push(new SDL.manager.permission.PermissionElement(SDL.rpc.enums.FunctionID.SendLocation, null));

const listenerId = sdlManager.getPermissionManager().addListener(permissionElements, SDL.manager.permission.enums.PermissionGroupType.ANY, function (allowedPermissions, permissionGroupStatus) {
    if (permissionGroupStatus != SDL.manager.permission.enums.PermissionGroupStatus.ALLOWED) {
        // Your app does not have permission to send the `SendLocation` request for its current HMI level
        return;
    }

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

Checking if the Module Supports Sending a Location

Since some modules will not support sending a location, 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 sending a location, 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 sending a location 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 SendLocation request.

async function isSendLocationSupported() {
    // Check if the module has navigation capabilities
    if (!sdlManager.getSystemCapabilityManager().isCapabilitySupported(SDL.rpc.enums.SystemCapabilityType.NAVIGATION)) {
        return false;
    }

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

    // Retrieve the navigation capability
    let isNavigationSupported = false;
    const navCapability = await sdlManager.getSystemCapabilityManager().updateCapability(SDL.rpc.enums.SystemCapabilityType.NAVIGATION)
        .catch(error => {
            throw error;
        });
    if (navCapability !== null) {
        isNavigationSupported = navCapability.getSendLocationEnabled();
    }

    return isNavigationSupported;
}

Using Send Location

To use the SendLocation request, you must at minimum include the longitude and latitude of the location.

const sendLocation = new SDL.rpc.messages.SendLocation()
    .setLatitudeDegrees(42.877737)
    .setLongitudeDegrees(-97.380967)
    .setLocationName('The Center')
    .setLocationDescription('Center of the United States');

const address = new SDL.rpc.structs.OasisAddress()
    .setSubThoroughfare('900')
    .setThoroughfare('Whiting Dr')
    .setLocality('Yankton')
    .setAdministrativeArea('SD')
    .setPostalCode('57078')
    .setCountryCode('US-SD')
    .setCountryName('United States');

sendLocation.setAddress(address);


// sdl_javascript_suite v1.1+
const response = await sdlManager.sendRpcResolve(sendLocation);

// Monitor response
const result = response.getResultCode();
if (result === SDL.rpc.enums.Result.SUCCESS) {
    // SendLocation was successfully sent.
} else if (result === SDL.rpc.enums.Result.INVALID_DATA) {
    // The request you sent contains invalid data and was rejected.
} else if (result === SDL.rpc.enums.Result.DISALLOWED) {
    // Your app does not have permission to use SendLocation.
}
// thrown exceptions should be caught by a parent function via .catch()


// Pre sdl_javascript_suite v1.1
const response = await sdlManager.sendRpc(sendLocation).catch(error => error);

const result = response.getResultCode();
if (result === SDL.rpc.enums.Result.SUCCESS) {
    // `SendLocation` was successfully sent
} else if (result === SDL.rpc.enums.Result.INVALID_DATA) {
    // `SendLocation` was rejected. The request contained invalid data
} else if (result === SDL.rpc.enums.Result.DISALLOWED) {
    // Your app is not allowed to use `SendLocation`
}

Checking the Result of Send Location

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

SUCCESS - Successfully sent.
INVALID_DATA - The request contains invalid data and was rejected.
DISALLOWED - Your app does not have permission to use the SendLocation request.

View on GitHub.com

Previous Section Next Section

Setting the Navigation Destination

Checking Your App's Permissions

Checking if the Module Supports Sending a Location

Note

Using Send Location

Checking the Result of Send Location