commonMain.com.huawei.hilink.c2c.integration.helper.api.DeviceConversion.kt Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of helper-jvm Show documentation
The helper library streamlines the HiLink C2C integration and exposes a simple API.
There is a newer version: 1.3.2
package com.huawei.hilink.c2c.integration.helper.api

/**
 * Protocol conversion for a given prodId.
 * Typically one prodId corresponds to one device model.
 *
 * Handles translation between the HiLink cloud standard to the partner
 * system's standard across representations of device states / information / commands.
 *
 * @param prodId product id defined for the device model(s) in HiLink console. Must be exactly 4 characters long.
 */
public abstract class DeviceConversion(public val prodId: String) {
    /**
     * Called when HiLink cloud wants to modify device state for a given device.
     * This happens when end-user uses AI Life to control the device.
     *
     * @param userInfo object containing an access token and a huaweiId of the user.
     * If you're implementing [CentralAccessTokenCheck], it will also contain the id of the authorized user.
     * @param deviceId the id, in the partner's system, of the device to execute the command on
     * @param serviceId the id of a deviceService, which is to be altered.
     * For example it could be "brightness" for a lamp device
     * @param dataJson raw json with a "type" property which holds deviceService ID, for polymorphic deserialization.
     * The format is the same as required for [DeviceServiceSnapshot.serviceDataJson].
     * @param consumer a callback allowing you to return the resulting [CommandResult] object
     * In addition, two functions related to authorization are available: [AuthResultConsumer.onUnauthorized] and
     * [AuthResultConsumer.onIllegalAccess].
     * Please check [AuthResultConsumer]'s documentation for a detailed description of the difference between the two.
     */
    public abstract fun executeCommand(
        userInfo: UserInfo,
        deviceId: String,
        serviceId: String,
        dataJson: String,
        consumer: CommandResultConsumer
    )

    /**
     * Called when HiLink cloud needs to learn about the device: what it's called,
     * what deviceServices it provides (what features it has, that can be controlled by user or represent information
     * to be shown to the user in Ai Life)
     *
     * @param userInfo object containing an access token and a huaweiId of the user.
     * If you're implementing [CentralAccessTokenCheck], it will also contain the id of the authorized user.
     * @param deviceId id of the device to gather information about.
     * @param consumer a callback allowing you to return the [DeviceInformation], contains [ResultConsumer.onSuccess] and
     * [ResultConsumer.onError] functions.
     * In addition, two functions related to authorization are available: [AuthResultConsumer.onUnauthorized] and
     * [AuthResultConsumer.onIllegalAccess].
     * Please check [AuthResultConsumer]'s documentation for a detailed description of the difference between the two.
     */
    public abstract fun discover(userInfo: UserInfo, deviceId: String, consumer: ResultConsumer)

    /**
     * Called when HiLink cloud needs to obtain the current state of the device.
     * It includes the data of the deviceServices (features of the device)
     * For example a lamp device might have a "brightness" service, in such a case, the
     * level of brightness set at the moment should be returned within a [DeviceSnapshot] object.
     *
     * @param userInfo object containing an access token and a huaweiId of the user.
     * If you're implementing [CentralAccessTokenCheck], it will also contain the id of the authorized user.
     * @param deviceId id of the device to gather information about.
     * @param consumer a callback allowing you to return the [DeviceSnapshot], contains [ResultConsumer.onSuccess] and
     * [ResultConsumer.onError] functions.
     * In addition, two functions related to authorization are available: [AuthResultConsumer.onUnauthorized] and
     * [AuthResultConsumer.onIllegalAccess].
     * Please check [AuthResultConsumer]'s documentation for a detailed description of the difference between the two.
     */
    public abstract fun snapshot(userInfo: UserInfo, deviceId: String, consumer: ResultConsumer)
}