wifi/1.0/ISupplicant.hal

/*
 * Copyright 2016 The Android Open Source Project
 *
 * 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 android.hardware.wifi@1.0;

import ISupplicantCallback;
import ISupplicantIface;

/**
 * Interface exposed by the wpa_supplicant HIDL service registered
 * with the hardware service manager.
 * This is the root level object for any wpa_supplicant interactions.
 */
interface ISupplicant {
  /**
   * Debug levels for wpa_supplicant.
   * Only log messages with a level greater than the set level
   * (via |setDebugParams|) will be logged.
   */
  enum DebugLevel : uint32_t {
    EXCESSIVE = 0,
    MSGDUMP = 1,
    DEBUG = 2,
    INFO = 3,
    WARNING = 4,
    ERROR = 5
  };

  /**
   * Registers a wireless interface in wpa_supplicant.
   *
   * @param ifName Name of the network interface, e.g., wlan0
   * @return status Status of the operation.
   *         Possible status codes:
   *         |SupplicantStatusCode.SUCCESS|,
   *         |SupplicantStatusCode.FAILURE_UNKNOWN|,
   *         |SupplicantStatusCode.FAILURE_IFACE_EXISTS|
   * @return iface HIDL interface object representing the interface if
   *         successful, null otherwise.
   */
  createInterface(string ifName)
      generates (SupplicantStatus status, ISupplicantIface iface);

  /**
   * Deregisters a wireless interface from wpa_supplicant.
   *
   * @param ifName Name of the network interface, e.g., wlan0
   * @return status Status of the operation.
   *         Possible status codes:
   *         |SupplicantStatusCode.SUCCESS|,
   *         |SupplicantStatusCode.FAILURE_UNKNOWN|,
   *         |SupplicantStatusCode.FAILURE_IFACE_UNKOWN|
   */
  removeInterface(string ifName) generates (SupplicantStatus status);

  /**
   * Gets a HIDL interface object for the interface corresponding to ifName
   * which wpa_supplicant already controls.
   *
   * @param ifName Name of the network interface, e.g., wlan0
   * @return status Status of the operation.
   *         Possible status codes:
   *         |SupplicantStatusCode.SUCCESS|,
   *         |SupplicantStatusCode.FAILURE_UNKNOWN|,
   *         |SupplicantStatusCode.FAILURE_IFACE_UNKOWN|
   * @return iface HIDL interface object representing the interface if
   *         successful, null otherwise.
   */
  getInterface(string ifName)
      generates (SupplicantStatus status, ISupplicantIface iface);

  /**
   * Retrieve a list of all the interface names controlled by wpa_supplicant.
   *
   * The corresponding |ISupplicantIface| object for any interface can be
   * retrieved using |getInterface| method.
   *
   * @return status Status of the operation.
   *         Possible status codes:
   *         |SupplicantStatusCode.SUCCESS|,
   *         |SupplicantStatusCode.FAILURE_UNKNOWN|
   * @return ifNames List of all interface names controlled by wpa_supplicant.
   */
  listInterfaces() generates (SupplicantStatus status, vec<string> ifNames);

  /**
   * Register for callbacks from the wpa_supplicant service.
   *
   * These callbacks are invoked for global events that are not specific
   * to any interface or network. Registration of multiple callback
   * objects is supported. These objects must be deleted when the corresponding
   * client process is dead.
   *
   * @param callback An instance of the |ISupplicantCallback| HIDL interface
   *        object.
   * @return status Status of the operation.
   *         Possible status codes:
   *         |SupplicantStatusCode.SUCCESS|,
   *         |SupplicantStatusCode.FAILURE_UNKNOWN|
   */
  registerCallback(ISupplicantCallback callback)
      generates (SupplicantStatus status);

  /**
   * Set debug parameters for wpa_supplicant.
   *
   * @param level Debug logging level for wpa_supplicant.
   *        (one of |DebugLevel| values).
   * @param timestamp Determines whether to show timestamps in logs or
   *        not.
   * @param showKeys Determines whether to show keys in debug logs or
   *        not.
   *        CAUTION: Do not set this param in production code!
   * @return status Status of the operation.
   *         Possible status codes:
   *         |SupplicantStatusCode.SUCCESS|,
   *         |SupplicantStatusCode.FAILURE_UNKNOWN|
   */
  setDebugParams(DebugLevel level, bool showTimestamp, bool showKeys)
      generates (SupplicantStatus status);

  /**
   * Get the debug level set.
   *
   * @return level one of |DebugLevel| values.
   */
  getDebugLevel() generates (DebugLevel level);

  /**
   * Get whether the timestamps are shown in the debug logs or not.
   *
   * @return enabled true if set, false otherwise.
   */
  isDebugShowTimestampEnabled() generates (bool enabled);

  /**
   * Get whether the keys are shown in the debug logs or not.
   *
   * @return enabled true if set, false otherwise.
   */
  isDebugShowKeysEnabled() generates (bool enabled);
};