java/com/fairphone/common/Core.java

/*
 * Copyright 2019 Fairphone B.V.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.fairphone.common;

import android.annotation.NonNull;
import android.annotation.Nullable;
import android.annotation.StringDef;
import android.util.Log;
import android.util.Pair;
import com.fairphone.common.crash.Crash;

import java.lang.annotation.Retention;
import java.util.List;

import static java.lang.annotation.RetentionPolicy.SOURCE;

/**
 * Provide an interface extending Android's framework.
 *
 * This entry point exposes additional framework APIs for communicating with Fairphone's
 * applications.
 */
public abstract class Core {

    /**
     * Available logcat buffers to log.
     *
     * Default: main,system,crash
     */
    public static final String LOGCAT_ALL = "all";
    public static final String LOGCAT_CRASH = "crash";
    public static final String LOGCAT_DEFAULT = "default";
    public static final String LOGCAT_EVENTS = "events";
    public static final String LOGCAT_MAIN = "main";
    public static final String LOGCAT_RADIO = "radio";
    public static final String LOGCAT_SYSTEM = "system";
    @Retention(SOURCE)
    @StringDef({
            LOGCAT_ALL,
            LOGCAT_CRASH,
            LOGCAT_DEFAULT,
            LOGCAT_EVENTS,
            LOGCAT_MAIN,
            LOGCAT_RADIO,
            LOGCAT_SYSTEM
    })
    public @interface LogcatBuffer {}

    /**
     * Identifier used for distinguishing the different modules.
     *
     * Modules in this case are classified as user removable/swappable hardware.
     */
    public static final String BATTERY_MODULE = "battery_module";
    public static final String BOTTOM_MODULE = "bottom_module";
    public static final String CAMERA_MODULE = "camera_module";
    public static final String CORE_MODULE = "core_module";
    public static final String DISPLAY_MODULE = "display_module";
    public static final String SPEAKER_MODULE = "speaker_module";
    public static final String TOP_MODULE = "top_module";
    @Retention(SOURCE)
    @StringDef({
            BATTERY_MODULE,
            BOTTOM_MODULE,
            CAMERA_MODULE,
            CORE_MODULE,
            DISPLAY_MODULE,
            SPEAKER_MODULE,
            TOP_MODULE
    })
    public @interface ModuleName {}

    /**
     * Identifier used for distinguishing the different components.
     */
    public static final String BASEBAND_PROCESSOR = "baseband_processor";
    public static final String CPU = "cpu";
    public static final String FINGERPRINT = "fingerprint";
    public static final String FRONT_CAMERA = "front_camera";
    public static final String MEMORY = "memory";
    public static final String NFC = "nfc";
    public static final String REAR_CAMERA = "rear_camera";
    @Retention(SOURCE)
    @StringDef({
            BASEBAND_PROCESSOR,
            CPU,
            FINGERPRINT,
            FRONT_CAMERA,
            MEMORY,
            NFC,
            REAR_CAMERA
    })
    public @interface ComponentName {}

    static final String TAG = Core.class.getSimpleName();

    private static final int LIBRARY_VERSION = 0;

    private static Core sInstance;

    @NonNull
    public static Core getInstance() {
        if (sInstance == null) {
            Log.i(TAG, "Instantiating Fairphone's framework interface");
            sInstance = new CoreImpl();
        }
        return sInstance;
    }

    /**
     * Get this interface's version number.
     *
     * @return The installed library version.
     */
    public final int getVersion() {
        return LIBRARY_VERSION;
    }

    /**
     * Start logcat logging.
     *
     * Logcat has access to different buffers when logging. By default these are main, system and
     * crash. The full list of buffer types can be found in {@code LogcatBuffer}.
     *
     * Starting logcat from here will persist selected logs and make them available across reboots.
     * These logs will be provided when obtaining crash information.
     *
     * @param bufferNames Variable length arguments for {@code LogcatBuffer}s to log.
     */
    public abstract void logcatStart(@NonNull @LogcatBuffer String... bufferNames);

    /**
     * Stop logcat logging.
     */
    public abstract void logcatStop();

    /**
     * Retrieve all known crashes.
     *
     * Calling this function obtains all crash information stored by the device. Once called, this
     * information stored on the system is removed.
     *
     * @return A list of all crashes known to the device.
     */
    public abstract List<Crash> getCrashes();

    /**
     * Get the cumulative system uptime since the last recorded system crash.
     *
     * This value represents data used to calculate the Mean Time Between Failures for the system.
     * It is reset back to 0 on fatal errors that cause the device to reboot. It is the ongoing
     * value to provide additional statistics for devices that do not crash.
     *
     * @return The cumulative system uptime in milliseconds since the last crash causing a device
     *         reboot. {@code -1L} if there was an error.
     */
    public abstract long getUptimeSinceLastSystemCrash();

    /**
     * Get the cumulative system uptime since the last recorded modem crash.
     *
     * This value represents data used to calculate the Mean Time Between Failures for the modem.
     * It is reset back to 0 on fatal errors that cause the modem to reboot. It is the ongoing
     * value to provide additional statistics for modems that do not crash.
     *
     * @return The cumulative system uptime in milliseconds since the last crash causing a modem
     *         reboot. {@code -1L} if there was an error.
     */
    public abstract long getUptimeSinceLastModemCrash();

    /**
     * Get a list of available user replaceable modules.
     *
     * @return A list {@code ModuleName}s.
     */
    @NonNull
    public abstract List<String> getModuleList();

    /**
     * Get a list of available components.
     *
     * @return A list {@code ComponentName}s.
     */
    @NonNull
    public abstract List<String> getComponentList();

    /**
     * Get the identifier for a module.
     *
     * Module identifiers will be used as user facing strings to identify modules in the device.
     * They will also be used when packing up crash information to help diagnose issues relating to
     * specific hardware.
     *
     * @param module The {@code ModuleName} to get the id for.
     * @return The module identifier if available. An empty string indicates there is no available
     *         identifier for the module. {@code null} represents any issue getting the module id.
     */
    @Nullable
    public abstract String getModuleId(@NonNull @ModuleName String module);

    /**
     * Get additional information related to a module.
     *
     * This additional information will be used to provide the user with information related to the
     * specific module.
     *
     * @param module The {@code ModuleName} to get the information for.
     * @return Additional information related to the module. An empty string indicates there is no
     *         additional information available. {@code null} represents any issue getting the
     *         module information.
     */
    @Nullable
    public abstract String getModuleInfo(@NonNull @ModuleName String module);

    /**
     * Get the identifier for a component.
     *
     * Component identifiers will be used as user facing strings to identify components in the
     * device. They will also be used when packing up crash information to help diagnose issues
     * relating to specific hardware.
     *
     * @param component The {@code ComponentName} to get the id for.
     * @return The component identifier if available. An empty string indicates there is no
     *         available identifier for the component. {@code null} represents any issue getting the
     *         component id.
     */
    @Nullable
    public abstract String getComponentId(@NonNull @ComponentName String component);

    /**
     * Get the identifier and information for a component.
     *
     * This additional information will be used to provide the user with information related to the
     * specific component.
     *
     * @param component The {@code ComponentName} to get the information for.
     * @return Additional information related to the component. An empty string indicates there is
     *         no additional information available. {@code null} represents any issue getting the
     *         component information.
     */
    @Nullable
    public abstract String getComponentInfo(@NonNull @ComponentName String component);
}