/*
 * 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 IWifiIface;
import IWifiRttControllerEventCallback;

/**
 * Interface used to perform RTT(Round trip time) operations.
 */
interface IWifiRttController {
  /**
   * Get the iface on which the RTT operations must be performed.
   *
   * @return status WifiStatus of the operation.
   *         Possible status codes:
   *         |WifiStatusCode.SUCCESS|,
   *         |WifiStatusCode.ERROR_WIFI_RTT_CONTROLLER_INVALID|
   * @return boundIface HIDL interface object representing the iface if bound
   *         to a specific iface, null otherwise
   */
  getBoundIface() generates (WifiStatus status, IWifiIface boundIface);

  /**
   * Requests notifications of significant events on this rtt controller.
   * Multiple calls to this must register multiple callbacks each of which must
   * receive all events.
   *
   * @param callback An instance of the |IWifiRttControllerEventCallback| HIDL
   *        interface object.
   * @return status WifiStatus of the operation.
   *         Possible status codes:
   *         |WifiStatusCode.SUCCESS|,
   *         |WifiStatusCode.ERROR_WIFI_IFACE_INVALID|
   */
  registerEventCallback(IWifiRttControllerEventCallback callback)
      generates (WifiStatus status);

  /**
   * API to request RTT measurement.
   *
   * @param cmdId command Id to use for this invocation.
   * @param rttConfigs Vector of |RttConfig| parameters.
   * @return status WifiStatus of the operation.
   *         Possible status codes:
   *         |WifiStatusCode.SUCCESS|,
   *         |WifiStatusCode.ERROR_WIFI_RTT_CONTROLLER_INVALID|,
   *         |WifiStatusCode.ERROR_INVALID_ARGS|,
   *         |WifiStatusCode.ERROR_NOT_AVAILABLE|,
   *         |WifiStatusCode.ERROR_UNKNOWN|
   */
  rangeRequest(CommandId cmdId, vec<RttConfig> rttConfigs)
      generates (WifiStatus status);

  /**
   * API to cancel RTT measurements.
   *
   * @param cmdId command Id corresponding to the original request.
   * @param addrs Vector of addresses for which to cancel.
   * @return status WifiStatus of the operation.
   *         Possible status codes:
   *         |WifiStatusCode.SUCCESS|,
   *         |WifiStatusCode.ERROR_WIFI_RTT_CONTROLLER_INVALID|,
   *         |WifiStatusCode.ERROR_INVALID_ARGS|,
   *         |WifiStatusCode.ERROR_NOT_AVAILABLE|,
   *         |WifiStatusCode.ERROR_UNKNOWN|
   */
  rangeCancel(CommandId cmdId, vec<MacAddress> addrs)
      generates (WifiStatus status);

  /**
   * RTT capabilities of the device.
   *
   * @return status WifiStatus of the operation.
   *         Possible status codes:
   *         |WifiStatusCode.SUCCESS|,
   *         |WifiStatusCode.ERROR_WIFI_RTT_CONTROLLER_INVALID|,
   *         |WifiStatusCode.ERROR_UNKNOWN|
   * @return capabilities Instance of |RttCapabilities|.
   */
  getCapabilities() generates (WifiStatus status, RttCapabilities capabilities);

  /**
   * API to configure the LCI(Location civic information).
   * Used in RTT Responder mode only.
   *
   * @param cmdId command Id to use for this invocation.
   * @param lci Instance of |RttLciInformation|.
   * @return status WifiStatus of the operation.
   *         Possible status codes:
   *         |WifiStatusCode.SUCCESS|,
   *         |WifiStatusCode.ERROR_WIFI_RTT_CONTROLLER_INVALID|,
   *         |WifiStatusCode.ERROR_INVALID_ARGS|,
   *         |WifiStatusCode.ERROR_NOT_AVAILABLE|,
   *         |WifiStatusCode.ERROR_UNKNOWN|
   */
  setLci(CommandId cmdId, RttLciInformation lci) generates (WifiStatus status);

  /**
   * API to configure the LCR(Location civic records).
   * Used in RTT Responder mode only.
   *
   * @param cmdId command Id to use for this invocation.
   * @param lcr Instance of |RttLcrInformation|.
   * @return status WifiStatus of the operation.
   *         Possible status codes:
   *         |WifiStatusCode.SUCCESS|,
   *         |WifiStatusCode.ERROR_WIFI_RTT_CONTROLLER_INVALID|,
   *         |WifiStatusCode.ERROR_INVALID_ARGS|,
   *         |WifiStatusCode.ERROR_NOT_AVAILABLE|,
   *         |WifiStatusCode.ERROR_UNKNOWN|
   */
  setLcr(CommandId cmdId, RttLcrInformation lcr) generates (WifiStatus status);

  /**
   * Get RTT responder information e.g. WiFi channel to enable responder on.
   *
   * @return status WifiStatus of the operation.
   *         Possible status codes:
   *         |WifiStatusCode.SUCCESS|,
   *         |WifiStatusCode.ERROR_WIFI_RTT_CONTROLLER_INVALID|,
   *         |WifiStatusCode.ERROR_NOT_AVAILABLE|,
   *         |WifiStatusCode.ERROR_UNKNOWN|
   * @return info Instance of |RttResponderInfo|.
   */
  getResponderInfo() generates (WifiStatus status, RttResponder info);

  /**
   * Enable RTT responder mode.
   *
   * @param cmdId command Id to use for this invocation.
   * @parm channelHint Hint of the channel information where RTT responder must
   *       be enabled on.
   * @param maxDurationInSeconds Timeout of responder mode.
   * @param info Instance of |RttResponderInfo|.
   * @return status WifiStatus of the operation.
   *         Possible status codes:
   *         |WifiStatusCode.SUCCESS|,
   *         |WifiStatusCode.ERROR_WIFI_RTT_CONTROLLER_INVALID|,
   *         |WifiStatusCode.ERROR_INVALID_ARGS|,
   *         |WifiStatusCode.ERROR_NOT_AVAILABLE|,
   *         |WifiStatusCode.ERROR_UNKNOWN|
   */
  enableResponder(CommandId cmdId,
                  WifiChannelInfo channelHint,
                  uint32_t maxDurationSeconds,
                  RttResponder info)
      generates (WifiStatus status);

  /**
   * Disable RTT responder mode.
   *
   * @param cmdId command Id corresponding to the original request.
   * @return status WifiStatus of the operation.
   *         Possible status codes:
   *         |WifiStatusCode.SUCCESS|,
   *         |WifiStatusCode.ERROR_WIFI_RTT_CONTROLLER_INVALID|,
   *         |WifiStatusCode.ERROR_NOT_AVAILABLE|,
   *         |WifiStatusCode.ERROR_UNKNOWN|
   */
  disableResponder(CommandId cmdId) generates (WifiStatus status);
};