1 /*
2  * Copyright (C) 2024 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.net.wifi.twt;
18 
19 import android.annotation.CallbackExecutor;
20 import android.annotation.FlaggedApi;
21 import android.annotation.NonNull;
22 import android.annotation.StringDef;
23 import android.annotation.SystemApi;
24 import android.os.Bundle;
25 
26 import com.android.wifi.flags.Flags;
27 
28 import java.lang.annotation.Retention;
29 import java.lang.annotation.RetentionPolicy;
30 import java.util.concurrent.Executor;
31 import java.util.function.Consumer;
32 
33 /**
34  * Defines a target wake time (TWT) session.
35  *
36  * @hide
37  */
38 @SystemApi
39 @FlaggedApi(Flags.FLAG_ANDROID_V_WIFI_API)
40 public interface TwtSession {
41     /**
42      * Bundle key to get average number of received packets in each wake duration
43      */
44     String TWT_STATS_KEY_INT_AVERAGE_RX_PACKET_COUNT = "key_avg_rx_pkt_count";
45     /**
46      * Bundle key to get average number of transmitted packets in each wake duration
47      */
48     String TWT_STATS_KEY_INT_AVERAGE_TX_PACKET_COUNT = "key_avg_tx_pkt_count";
49     /**
50      * Bundle key to get average bytes per received packets in each wake duration
51      */
52     String TWT_STATS_KEY_INT_AVERAGE_RX_PACKET_SIZE = "key_avg_rx_pkt_size";
53     /**
54      * Bundle key to get average bytes per transmitted packets in each wake duration
55      */
56     String TWT_STATS_KEY_INT_AVERAGE_TX_PACKET_SIZE = "key_avg_tx_pkt_size";
57     /**
58      * Bundle key to get average end of service period in microseconds
59      */
60     String TWT_STATS_KEY_INT_AVERAGE_EOSP_DURATION_MICROS = "key_avg_eosp_dur";
61     /**
62      * Bundle key to get count of early termination. Value will be -1 if not available.
63      */
64     String TWT_STATS_KEY_INT_EOSP_COUNT = "key_eosp_count";
65 
66     /** @hide */
67     @StringDef(prefix = { "TWT_STATS_KEY_"}, value = {
68             TWT_STATS_KEY_INT_AVERAGE_RX_PACKET_COUNT,
69             TWT_STATS_KEY_INT_AVERAGE_TX_PACKET_COUNT,
70             TWT_STATS_KEY_INT_AVERAGE_RX_PACKET_SIZE,
71             TWT_STATS_KEY_INT_AVERAGE_TX_PACKET_SIZE,
72             TWT_STATS_KEY_INT_AVERAGE_EOSP_DURATION_MICROS,
73             TWT_STATS_KEY_INT_EOSP_COUNT
74     })
75     @Retention(RetentionPolicy.SOURCE)
76     @interface TwtStats {}
77     /**
78      * Get TWT session wake duration in microseconds.
79      *
80      * @return wake duration in microseconds.
81      */
82     @FlaggedApi(Flags.FLAG_ANDROID_V_WIFI_API)
getWakeDurationMicros()83     int getWakeDurationMicros();
84 
85     /**
86      * Get TWT session wake interval in microseconds.
87      *
88      * @return wake interval in microseconds.
89      */
90     @FlaggedApi(Flags.FLAG_ANDROID_V_WIFI_API)
getWakeIntervalMicros()91     long getWakeIntervalMicros();
92 
93     /**
94      * Get MLO link id if the station connection is Wi-Fi 7, otherwise returns
95      * {@link android.net.wifi.MloLink#INVALID_MLO_LINK_ID}.
96      *
97      * @return MLO link id
98      */
99     @FlaggedApi(Flags.FLAG_ANDROID_V_WIFI_API)
getMloLinkId()100     int getMloLinkId();
101 
102     /**
103      * Get stats of the session.
104      *
105      * Note: If the command fails or not available, -1 will be returned for all stats values.
106      *
107      * @param executor The executor on which callback will be invoked.
108      * @param resultCallback An asynchronous callback that will return a bundle for target wake time
109      *                       stats. See {@link TwtStats} for the string keys for the bundle.
110      * @throws SecurityException if the caller does not have permission.
111      * @throws NullPointerException if the caller provided null inputs.
112      * @throws UnsupportedOperationException if the API is not supported.
113      */
114     @FlaggedApi(Flags.FLAG_ANDROID_V_WIFI_API)
getStats(@onNull @allbackExecutor Executor executor, @NonNull Consumer<Bundle> resultCallback)115     void getStats(@NonNull @CallbackExecutor Executor executor,
116             @NonNull Consumer<Bundle> resultCallback);
117 
118     /**
119      * Teardown the session. See {@link TwtSessionCallback#onTeardown(int)}. Also closes this
120      * session, relinquishing any underlying resources.
121      *
122      * @throws SecurityException if the caller does not have permission.
123      */
124     @FlaggedApi(Flags.FLAG_ANDROID_V_WIFI_API)
teardown()125     void teardown();
126 }
127