// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.wlan.policy;

using fuchsia.wlan.common;

/// The AccessPointProvider API provides a mechanism for access point
/// control and is intended to be called by applications or entities representing
/// the user (ex, Settings). This API is not intended to be called by other
/// applications to change wlan state without explicit user control.
///
/// The second aim of this API design is to eliminate the "last-caller wins"
/// paradigm by limiting the number of controlling applications.  A single caller
/// at a time is permitted to make API calls that impact wlan state.
@discoverable
closed protocol AccessPointProvider {
    /// Control channel used by a single caller to trigger wlan access point (ap) mode
    /// state changes.  The caller also provides a channel to receive wlan ap updates.
    /// Only one caller can have the control channel open at a time.  Attempts to
    /// register as a controller while there is an active control registration
    /// will result in the new caller's provided channel being closed.
    strict GetController(resource struct {
        requests server_end:AccessPointController;
        updates client_end:AccessPointStateUpdates;
    });
};

/// The AccessPointListener API provides a mechanism for callers to receive state change
/// updates about wlan access point operation.
@discoverable
closed protocol AccessPointListener {
    /// Registration for callers to receive wlan access point (ap) mode state updates.
    strict GetListener(resource struct {
        updates client_end:AccessPointStateUpdates;
    });
};

/// AccessPointControllers allow the caller to trigger wlan state changes.  This
/// includes whether the device will act as an access point and provide a wlan
/// network for other co-located devices.
closed protocol AccessPointController {
    /// Enables wlan to initiate AccessPoint operation using the provided network
    /// configuration, connectivity mode and band.
    @available(added=25)
    strict StartAccessPoint(struct {
        config NetworkConfig;
        mode ConnectivityMode;
        band OperatingBand;
    }) -> (struct {
        status RequestStatus;
    });
    @available(replaced=25)
    strict StartAccessPoint(struct {
        config NetworkConfig;
        mode ConnectivityMode;
        band OperatingBand;
    }) -> (struct {
        status fuchsia.wlan.common.RequestStatus;
    });

    /// Deactivate AccessPoint operation for a specified network configuration.
    @available(added=25)
    strict StopAccessPoint(struct {
        config NetworkConfig;
    }) -> (struct {
        status RequestStatus;
    });

    @available(replaced=25)
    strict StopAccessPoint(struct {
        config NetworkConfig;
    }) -> (struct {
        status fuchsia.wlan.common.RequestStatus;
    });

    /// Deactivates all AccessPoints currently operating on the device.
    strict StopAllAccessPoints();
};

/// AccessPoint operation status changes along with associated connection status.
closed protocol AccessPointStateUpdates {
    /// Updates registered listeners with the current summary of wlan access point
    /// operating states.  This will be called when there are changes with active
    /// access point networks - both the number of access points and their
    /// individual activity.  Registered listeners are responsible for deciding
    /// what information has changed (this is dependent on when they last
    /// acknowledged the update).
    strict OnAccessPointStateUpdate(struct {
        access_points vector<AccessPointState>:MAX;
    }) -> ();
};

/// Information about the individual operating access points.  This includes limited
/// information about any connected clients.
type AccessPointState = table {
    /// Current access point operating state
    1: state OperatingState;

    /// Requested operating connectivity mode
    2: mode ConnectivityMode;

    /// Access point operating band.
    3: band OperatingBand;

    /// Access point operating frequency (in MHz).
    4: frequency uint32;

    /// Information about connected clients
    5: clients ConnectedClientInformation;

    /// Identifying information of the access point whose state has changed.
    6: id NetworkIdentifier;
};

/// Connectivity operating mode for the access point.
type ConnectivityMode = strict enum {
    /// Allows for connectivity between co-located devices.  Local only access points do not
    /// forward traffic to other network connections.
    LOCAL_ONLY = 1;

    /// Allows for full connectivity with traffic potentially being forwarded
    /// to other network connections (ex., tethering mode).
    UNRESTRICTED = 2;
};

/// Current detailed operating state for an access point.
type OperatingState = strict enum {
    /// Access point operation failed.  Access points that enter the failed state will
    /// have one update informing registered listeners of the failure and then an
    /// additional update with the access point removed from the list.
    FAILED = 1;

    /// Access point operation is starting up.
    STARTING = 2;

    /// Access point operation is active.
    ACTIVE = 3;
};

/// Connected client information.  This is initially limited to the number of
/// connected clients.
type ConnectedClientInformation = table {
    /// Number of connected clients
    1: count uint8;
};