1 /* 2 * Copyright (c) 2023, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 package com.android.server.thread.openthread; 30 31 import android.net.thread.ChannelMaxPower; 32 import android.os.ParcelFileDescriptor; 33 import com.android.server.thread.openthread.IChannelMasksReceiver; 34 import com.android.server.thread.openthread.INsdPublisher; 35 import com.android.server.thread.openthread.IOtDaemonCallback; 36 import com.android.server.thread.openthread.IOtOutputReceiver; 37 import com.android.server.thread.openthread.IOtStatusReceiver; 38 import com.android.server.thread.openthread.InfraLinkState; 39 import com.android.server.thread.openthread.Ipv6AddressInfo; 40 import com.android.server.thread.openthread.MeshcopTxtAttributes; 41 import com.android.server.thread.openthread.OtDaemonConfiguration; 42 43 /** 44 * The OpenThread daemon service which provides access to the core Thread stack for 45 * system_server. 46 */ 47 oneway interface IOtDaemon { 48 /** 49 * The Thread tunnel interface name. This interface MUST be created before 50 * starting this {@link IOtDaemon} service. 51 */ 52 const String TUN_IF_NAME = "thread-wpan"; 53 54 /** Thread radio is disabled. */ 55 const int OT_STATE_DISABLED = 0; 56 /** Thread radio is enabled. */ 57 const int OT_STATE_ENABLED = 1; 58 /** Thread radio is being disabled. */ 59 const int OT_STATE_DISABLING = 2; 60 61 /** The ephemeral key is disabled. */ 62 const int OT_EPHEMERAL_KEY_DISABLED = 0; 63 /** The ephemeral key is enabled. */ 64 const int OT_EPHEMERAL_KEY_ENABLED = 1; 65 /** The ephemeral key is in use. */ 66 const int OT_EPHEMERAL_KEY_IN_USE = 2; 67 68 enum ErrorCode { 69 // Converts to ThreadNetworkException#ERROR_FAILED_PRECONDITION 70 OT_ERROR_FAILED_PRECONDITION = -3, 71 // Converts to ThreadNetworkException#ERROR_THREAD_DISABLED 72 OT_ERROR_THREAD_DISABLED = -2, 73 // Converts to ThreadNetworkException#ERROR_UNSUPPORTED_CHANNEL 74 // TODO: Add this error code to OpenThread and make sure `otDatasetSetActiveTlvs()` returns 75 // this error code when an unsupported channel is provided 76 OT_ERROR_UNSUPPORTED_CHANNEL = -1, 77 78 // The error code below MUST be consistent with openthread/include/openthread/error.h 79 // TODO: add a unit test to make sure that values are always match 80 81 OT_ERROR_NO_BUFS = 3, 82 OT_ERROR_BUSY = 5, 83 OT_ERROR_PARSE = 6, 84 OT_ERROR_ABORT = 11, 85 OT_ERROR_NOT_IMPLEMENTED = 12, 86 OT_ERROR_INVALID_STATE = 13, 87 OT_ERROR_RESPONSE_TIMEOUT = 28, 88 OT_ERROR_REASSEMBLY_TIMEOUT = 30, 89 OT_ERROR_REJECTED = 37, 90 } 91 92 /** 93 * Initializes this service. 94 * 95 * <p>This API MUST be called before all other APIs of this interface. 96 * 97 * @param enabled the Thead enabled state from Persistent Settings 98 * @param configuration the Thread configuration from Persistent Settings 99 * @param tunFd the Thread tunnel interface FD which can be used to transmit/receive 100 * packets to/from Thread PAN 101 * @param nsdPublisher the INsdPublisher which can be used for mDNS advertisement/discovery 102 * on AIL by {@link NsdManager} 103 * @param meshcopTxts the MeshCoP TXT values set by the system_server to override the default 104 * ones 105 * @param countryCode 2 bytes country code (as defined in ISO 3166) to set 106 * @param trelEnabled the TREL enabled state 107 * @param callback the callback for receiving OtDaemonState changes 108 */ initialize(boolean enabled, in OtDaemonConfiguration configuration, in ParcelFileDescriptor tunFd, in INsdPublisher nsdPublisher, in MeshcopTxtAttributes meshcopTxts, in String countryCode, in boolean trelEnabled, in IOtDaemonCallback callback)109 void initialize(boolean enabled, in OtDaemonConfiguration configuration, 110 in ParcelFileDescriptor tunFd, in INsdPublisher nsdPublisher, 111 in MeshcopTxtAttributes meshcopTxts, in String countryCode, in boolean trelEnabled, 112 in IOtDaemonCallback callback); 113 114 /** Terminates the ot-daemon process. */ terminate()115 void terminate(); 116 117 /** 118 * Enables/disables Thread. 119 * 120 * When disables Thread, it will first detach from the network without erasing the 121 * active dataset, and then disable Thread radios. 122 * 123 * If called with same Thread enabled state as current state, the method succeeds with 124 * no-op. 125 * 126 * @sa android.net.thread.ThreadNetworkController#setThreadEnabled 127 */ setThreadEnabled(in boolean enabled, in IOtStatusReceiver receiver)128 void setThreadEnabled(in boolean enabled, in IOtStatusReceiver receiver); 129 130 /** 131 * Registers a callback to receive OpenThread daemon state changes. 132 * 133 * @param callback invoked immediately after this method or any time a state is changed 134 * @param listenerId specifies the the ID which will be sent back in callbacks of {@link 135 * IOtDaemonCallback} 136 */ registerStateCallback(in IOtDaemonCallback callback, long listenerId)137 void registerStateCallback(in IOtDaemonCallback callback, long listenerId); 138 139 /** 140 * Joins this device to the network specified by {@code activeOpDatasetTlvs}. 141 * 142 * @sa android.net.thread.ThreadNetworkController#join 143 */ join(in byte[] activeOpDatasetTlvs, in IOtStatusReceiver receiver)144 void join(in byte[] activeOpDatasetTlvs, in IOtStatusReceiver receiver); 145 146 /** 147 * Leaves from the current network. 148 * 149 * 1. It returns success immediately if this device has already left or disabled 150 * 2. Else if there is already an onging {@code leave} request, no action will be taken but 151 * the {@code receiver} will be invoked after the previous request is completed 152 * 3. Otherwise, OTBR sends Address Release Notification (i.e. ADDR_REL.ntf) to gracefully 153 * detach from the current network and it takes 1 second to finish 154 * 4. The Operational Dataset will be removed from persistent storage if {@code eraseDataset} 155 * is {@code true} 156 * 157 * @sa android.net.thread.ThreadNetworkController#leave 158 */ leave(boolean eraseDataset, in IOtStatusReceiver receiver)159 void leave(boolean eraseDataset, in IOtStatusReceiver receiver); 160 161 /** 162 * Migrates to the new network specified by {@code pendingOpDatasetTlvs}. 163 * 164 * @sa android.net.thread.ThreadNetworkController#scheduleMigration 165 */ scheduleMigration(in byte[] pendingOpDatasetTlvs, in IOtStatusReceiver receiver)166 void scheduleMigration(in byte[] pendingOpDatasetTlvs, in IOtStatusReceiver receiver); 167 168 /** 169 * Sets the country code. 170 * 171 * @param countryCode 2 bytes country code (as defined in ISO 3166) to set. 172 * @param receiver the receiver to receive result of this operation 173 */ setCountryCode(in String countryCode, in IOtStatusReceiver receiver)174 void setCountryCode(in String countryCode, in IOtStatusReceiver receiver); 175 176 /** 177 * Sets the configuration at ot-daemon. 178 * 179 * @param config the configuration 180 * @param receiver the status receiver 181 * 182 */ setConfiguration(in OtDaemonConfiguration config, in IOtStatusReceiver receiver)183 void setConfiguration(in OtDaemonConfiguration config, in IOtStatusReceiver receiver); 184 185 /** 186 * Sets the infrastructure network interface. 187 * 188 * @param interfaceName the infra network interface name 189 * @param icmp6Socket the ICMPv6 socket on the infrastructure network 190 * @param receiver the status receiver 191 * 192 */ setInfraLinkInterfaceName(in @ullable String interfaceName, in ParcelFileDescriptor icmp6Socket, in IOtStatusReceiver receiver)193 void setInfraLinkInterfaceName(in @nullable String interfaceName, 194 in ParcelFileDescriptor icmp6Socket, in IOtStatusReceiver receiver); 195 196 /** 197 * Sets the NAT64 prefix discovered from infrastructure link. 198 * 199 * @param nat64Prefix the NAT64 prefix discovered from the infra link 200 * @param receiver the status receiver 201 * 202 */ setInfraLinkNat64Prefix( in @ullable String nat64Prefix, in IOtStatusReceiver receiver)203 void setInfraLinkNat64Prefix( 204 in @nullable String nat64Prefix, in IOtStatusReceiver receiver); 205 206 /** 207 * Sets the NAT64 CIDR. 208 * 209 * @param nat64Cidr the NAT64 CIDR 210 * @param receiver the status receiver 211 * 212 */ setNat64Cidr(in @ullable String nat64Cidr, in IOtStatusReceiver receiver)213 void setNat64Cidr(in @nullable String nat64Cidr, in IOtStatusReceiver receiver); 214 215 /** 216 * Sets the infrastructure link DNS servers. 217 * 218 * @param dnsServers the DNS server IP addresses represented by strings 219 * @param receiver the status receiver 220 * 221 */ setInfraLinkDnsServers(in List<String> dnsServers, in IOtStatusReceiver receiver)222 void setInfraLinkDnsServers(in List<String> dnsServers, in IOtStatusReceiver receiver); 223 224 /** 225 * Gets the supported and preferred channel masks. 226 * 227 * @param receiver the receiver to receive result of this operation 228 */ getChannelMasks(in IChannelMasksReceiver receiver)229 void getChannelMasks(in IChannelMasksReceiver receiver); 230 231 /** 232 * Sets the max power of each channel 233 * 234 * @param channelMaxPowers an array of {@code ChannelMaxPower}. 235 * @param receiver the receiver to the receive result of this operation. 236 */ setChannelMaxPowers(in ChannelMaxPower[] channelMaxPowers, in IOtStatusReceiver receiver)237 void setChannelMaxPowers(in ChannelMaxPower[] channelMaxPowers, in IOtStatusReceiver receiver); 238 239 /** 240 * Runs an ot-ctl command. 241 * 242 * @param command the complete ot-ctl command string, including all arguments. Note that the 243 * "ot-ctl" prefix itself should be omitted from this string 244 * @param isInteractive indicates whether to run command in interactive mode 245 * @param receiver the callback interface to receive the command's output 246 */ runOtCtlCommand( in String command, in boolean isInteractive, in IOtOutputReceiver receiver)247 void runOtCtlCommand( 248 in String command, in boolean isInteractive, in IOtOutputReceiver receiver); 249 250 /** 251 * Activates the ephemeral key mode. 252 * 253 * @param lifetimeMillis the lifetime of the ephemeral key in milliseconds 254 * @param receiver the status receiver 255 */ activateEphemeralKeyMode(in long lifetimeMillis, in IOtStatusReceiver receiver)256 void activateEphemeralKeyMode(in long lifetimeMillis, in IOtStatusReceiver receiver); 257 258 /** 259 * Deactivates the ephemeral key mode. 260 * 261 * This will always succeed. If there are active secure sessions with the ephemeral key, the 262 * sessions will be terminated. 263 * 264 * @param receiver the status receiver 265 */ deactivateEphemeralKeyMode(in IOtStatusReceiver receiver)266 void deactivateEphemeralKeyMode(in IOtStatusReceiver receiver); 267 268 // TODO: add Border Router APIs 269 } 270