/*
 * Copyright (C) 2017 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.tetheroffload.control@1.0;

import ITetheringOffloadCallback;


/**
 * Interface used to control the lifecycle of tethering offload
 */
interface IOffloadControl {
  /**
   * Indicates intent to start offload for tethering in immediate future.
   *
   * This API must be called exactly once the first time that Tethering is requested by
   * the user.
   *
   * If this API is called multiple times without first calling stopOffload, then the subsequent
   * calls must fail without changing the state of the server.
   *
   * If for some reason, the hardware is currently unable to support offload, this call must fail.
   *
   * @param cb Assuming success, this callback must provide unsolicited updates of offload status.
   *           It is assumed to be valid until stopOffload is called.
   *
   * @return success true if initialization is successful, false otherwise
   * @return errMsg a human readable string if eror has occured.
   *
   * Remarks: Initializing offload does not imply that any upstreams or downstreams have yet been,
   * or even will be, chosen.  This API is symmetrical with stopOffload.
   */
  @entry
  @callflow(next={"*"})
  initOffload(ITetheringOffloadCallback cb) generates (bool success, string errMsg);

  /**
   * Indicate desire to tear down all tethering offload.
   *
   * Called after tethering is no longer requested by the user. Any remaining offload must
   * be subsequently torn down by the management process.  Upon success, the callback registered
   * in initOffload must be released, and offload must be stopped.
   *
   * @return success true if offload is stopped, false otherwise
   * @return errMsg a human readable string if eror has occured.
   *
   * Remarks: Statistics must be reset by this API.
   */
  @exit
  stopOffload() generates (bool success, string errMsg);

  /**
   * Instruct management process not to forward traffic destined to or from the specified prefixes.
   *
   * This API may only be called after initOffload and before stopOffload.
   *
   * @param prefixes List containing fully specified prefixes. For e.g. 192.168.1.12/24
                     or 2001:4860:0684:0:0:0:0:0:1002/64
   *
   * @return success true if success, false otherwise
   * @return errMsg a human readable string if eror has occured.
   *
   * Remarks: This list overrides any previously specified list
   */
  setLocalPrefixes(vec<string> prefixes) generates (bool success, string errMsg);

  /**
   * Query offloaded traffic statistics forwarded to an upstream address.
   *
   * Return statistics that have transpired since the last query.  This would include
   * statistics from all offloaded downstream tether interfaces that have been forwarded to this
   * upstream interface.  After returning the statistics, the counters are reset to zero.
   *
   * Only offloaded statistics must be returned by this API, software stats must not be
   * returned.
   *
   * @param upstream Upstream interface on which traffic exited/entered
   *
   * @return rxBytes values depicting the received bytes
   * @return txBytes values depicting the transmitted bytes
   */
  getForwardedStats(string upstream) generates (uint64_t rxBytes, uint64_t txBytes);

  /**
   * Instruct hardware to stop forwarding traffic and send a callback after limit bytes have been
   * transferred in either direction on this upstream interface.
   *
   * The limit must be applied to all traffic on the given upstream interface.  This
   * includes hardware forwarded traffic, software forwarded traffic, and AP-originated traffic.
   * IPv4 and IPv6 traffic both count towards the same limit.  IP headers are included in the
   * byte count limit, but, link-layer headers are not.
   *
   * This API may only be called while offload is occurring on this upstream.  The hardware
   * management process is not expected to cache the value and apply the quota once offload is
   * started.  This cache is not expected, because the limit value would likely become stale over
   * time and would not reflect any new traffic that has occurred.
   *
   * This limit must replace any previous limit.  It may be interpreted as "tell me when
   * <limit> bytes have been transferred (in either direction) on <upstream>, starting
   * now and counting from zero."
   *
   * Once the limit is reached, the callback registered in initOffload must be called to indicate
   * this event and all offload must be stopped.  If offload is desired again, the hardware
   * management process must be completely reprogrammed by calling setUpstreamParameters and
   * addDownstream again.  Note that it is not necessary to call initOffload again to resume offload
   * if stopOffload was not called by the client.
   *
   * @param upstream Upstream interface name that limit must apply to
   * @param limit    Bytes limit that can occur before action must be taken
   *
   * @return success true if limit is applied, false otherwise
   * @return errMsg a human readable string if eror has occured.
   */
  setDataLimit(string upstream, uint64_t limit) generates (bool success, string errMsg);

  /**
   * Instruct hardware to start forwarding traffic to the specified upstream.
   *
   * When iface, v4Addr, and v4Gw are all non-null, the management process may begin forwarding
   * any currently configured or future configured IPv4 downstreams to this upstream interface.
   *
   * If any of the previously three mentioned parameters are null, then any current IPv4 offload
   * must be stopped.
   *
   * When iface and v6Gws are both non-null, and in the case of v6Gws, are not empty, the
   * management process may begin forwarding any currently configured or future configured IPv6
   * downstreams to this upstream interface.
   *
   * If either of the two above parameters are null, or no V6 Gateways are provided, then IPv6
   * offload must be stopped.
   *
   * This API may only be called after initOffload and before stopOffload.
   *
   * @param iface  Upstream interface name.  Note that only one is needed because IPv4 and IPv6
   *               interfaces cannot be different (only known that this can occur during software
   *               xlat, which cannot be offloaded through hardware anyways).  If the iface is
   *               null, offload must be stopped.
   * @param v4Addr The local IPv4 address assigned to the provided upstream interface, i.e. the
   *               IPv4 address the packets are NATed to. For e.g. 192.168.1.12.
   * @param v4Gw   The IPv4 address of the IPv4 gateway on the upstream interface.
   *               For e.g. 192.168.1.1
   * @param v6Gws  A list of IPv6 addresses (for e.g. 2001:4860:0684:0:0:0:0:0:1002) for possible
   *               IPv6 gateways on the upstream interface.
   *
   * @return success true if success, false otherwise
   * @return errMsg a human readable string if eror has occured.
   *
   * Remarks: This overrides any previously configured parameters.
   */
  setUpstreamParameters(string iface, string v4Addr, string v4Gw, vec<string> v6Gws)
          generates (bool success, string errMsg);

  /**
   * Configure a downstream interface and prefix in the hardware management process that may be
   * forwarded.
   *
   * The prefix may be an IPv4 or an IPv6 address to signify which family can be offloaded from the
   * specified tether interface.  The list of IPv4 and IPv6 downstreams that are configured may
   * differ.
   *
   * If the given protocol, as determined by the prefix, has an upstream set,
   * the hardware may begin forwarding traffic between the upstream and any devices on the
   * downstream interface that have IP addresses within the specified prefix. Traffic from the same
   * downstream interfaces is unaffected and must be forwarded if and only if it was already
   * being forwarded.
   *
   * If no upstream is currently configured, then these downstream interface and prefixes must be
   * preserved so that offload may begin in the future when an upstream is set.
   *
   * This API does not replace any previously configured downstreams and must be explictly removed
   * by calling removeDownstream.
   *
   * This API may only be called after initOffload and before stopOffload.
   *
   * @param iface  Tether interface
   * @param prefix Downstream prefix depicting addresses that may be offloaded.
   *               For e.g. 192.168.1.12/24 or 2001:4860:0684::/64)
   *
   * @return success true if success, false otherwise
   * @return errMsg a human readable string if eror has occured.
   *
   * Remarks: The hardware management process may fail this call in a normal situation.  This can
   *          happen because the hardware cannot support the current number of prefixes, the
   *          hardware cannot support concurrent offload on multiple interfaces, the hardware
   *          cannot currently support offload on the tether interface for some reason, or any
   *          other dynamic configuration issues which may occur.  In this case,
   *          traffic must remain unaffected and must be forwarded if and only if it was already
   *          being forwarded.
   */
  addDownstream(string iface, string prefix) generates (bool success, string errMsg);

  /**
   * Remove a downstream prefix that may be forwarded from the hardware management process.
   *
   * The prefix may be an IPv4 or an IPv6 address. If it was not previously configured using
   * addDownstream, then this must be a no-op.
   *
   * This API may only be called after initOffload and before stopOffload.
   *
   * @param iface  Tether interface
   * @param prefix Downstream prefix depicting address that must no longer be offloaded
   *               For e.g. 192.168.1.12/24 or 2001:4860:0684::/64)
   *
   * @return success true if success, false otherwise
   * @return errMsg a human readable string if eror has occured.
   */
  removeDownstream(string iface, string prefix) generates (bool success, string errMsg);
};