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.os.ParcelFileDescriptor; 32 33 import android.net.thread.ChannelMaxPower; 34 import com.android.server.thread.openthread.BorderRouterConfigurationParcel; 35 import com.android.server.thread.openthread.IChannelMasksReceiver; 36 import com.android.server.thread.openthread.Ipv6AddressInfo; 37 import com.android.server.thread.openthread.IOtStatusReceiver; 38 import com.android.server.thread.openthread.IOtDaemonCallback; 39 import com.android.server.thread.openthread.INsdPublisher; 40 import com.android.server.thread.openthread.MeshcopTxtAttributes; 41 42 /** 43 * The OpenThread daemon service which provides access to the core Thread stack for 44 * system_server. 45 */ 46 oneway interface IOtDaemon { 47 /** 48 * The Thread tunnel interface name. This interface MUST be created before 49 * starting this {@link IOtDaemon} service. 50 */ 51 const String TUN_IF_NAME = "thread-wpan"; 52 53 /** Thread radio is disabled. */ 54 const int OT_STATE_DISABLED = 0; 55 /** Thread radio is enabled. */ 56 const int OT_STATE_ENABLED = 1; 57 /** Thread radio is being disabled. */ 58 const int OT_STATE_DISABLING = 2; 59 60 enum ErrorCode { 61 // Converts to ThreadNetworkException#ERROR_FAILED_PRECONDITION 62 OT_ERROR_FAILED_PRECONDITION = -3, 63 // Converts to ThreadNetworkException#ERROR_THREAD_DISABLED 64 OT_ERROR_THREAD_DISABLED = -2, 65 // Converts to ThreadNetworkException#ERROR_UNSUPPORTED_CHANNEL 66 // TODO: Add this error code to OpenThread and make sure `otDatasetSetActiveTlvs()` returns 67 // this error code when an unsupported channel is provided 68 OT_ERROR_UNSUPPORTED_CHANNEL = -1, 69 70 // The error code below MUST be consistent with openthread/include/openthread/error.h 71 // TODO: add a unit test to make sure that values are always match 72 73 OT_ERROR_NO_BUFS = 3, 74 OT_ERROR_BUSY = 5, 75 OT_ERROR_PARSE = 6, 76 OT_ERROR_ABORT = 11, 77 OT_ERROR_NOT_IMPLEMENTED = 12, 78 OT_ERROR_INVALID_STATE = 13, 79 OT_ERROR_RESPONSE_TIMEOUT = 28, 80 OT_ERROR_REASSEMBLY_TIMEOUT = 30, 81 OT_ERROR_REJECTED = 37, 82 } 83 84 /** 85 * Initializes this service. 86 * 87 * <p>This API MUST be called before all other APIs of this interface. 88 * 89 * @param tunFd the Thread tunnel interface FD which can be used to transmit/receive 90 * packets to/from Thread PAN 91 * @param enabled the Thead enabled state from Persistent Settings 92 * @param nsdPublisher the INsdPublisher which can be used for mDNS advertisement/discovery 93 * on AIL by {@link NsdManager} 94 * @param meshcopTxts the MeshCoP TXT values set by the system_server to override the default 95 * ones 96 * @param callback the callback for receiving OtDaemonState changes 97 * @param countryCode 2 bytes country code (as defined in ISO 3166) to set 98 */ initialize( in ParcelFileDescriptor tunFd, in boolean enabled, in INsdPublisher nsdPublisher, in MeshcopTxtAttributes meshcopTxts, in IOtDaemonCallback callback, in String countryCode)99 void initialize( 100 in ParcelFileDescriptor tunFd, 101 in boolean enabled, 102 in INsdPublisher nsdPublisher, 103 in MeshcopTxtAttributes meshcopTxts, 104 in IOtDaemonCallback callback, 105 in String countryCode); 106 107 /** Terminates the ot-daemon process. */ terminate()108 void terminate(); 109 110 /** 111 * Enables/disables Thread. 112 * 113 * When disables Thread, it will first detach from the network without erasing the 114 * active dataset, and then disable Thread radios. 115 * 116 * If called with same Thread enabled state as current state, the method succeeds with 117 * no-op. 118 * 119 * @sa android.net.thread.ThreadNetworkController#setThreadEnabled 120 */ setThreadEnabled(in boolean enabled, in IOtStatusReceiver receiver)121 void setThreadEnabled(in boolean enabled, in IOtStatusReceiver receiver); 122 123 /** 124 * Registers a callback to receive OpenThread daemon state changes. 125 * 126 * @param callback invoked immediately after this method or any time a state is changed 127 * @param listenerId specifies the the ID which will be sent back in callbacks of {@link 128 * IOtDaemonCallback} 129 */ registerStateCallback(in IOtDaemonCallback callback, long listenerId)130 void registerStateCallback(in IOtDaemonCallback callback, long listenerId); 131 132 /** 133 * Joins this device to the network specified by {@code activeOpDatasetTlvs}. 134 * 135 * @sa android.net.thread.ThreadNetworkController#join 136 */ join(in byte[] activeOpDatasetTlvs, in IOtStatusReceiver receiver)137 void join(in byte[] activeOpDatasetTlvs, in IOtStatusReceiver receiver); 138 139 /** 140 * Leaves from the current network. 141 * 142 * 1. It returns success immediately if this device has already left or disabled 143 * 2. Else if there is already an onging {@code leave} request, no action will be taken but 144 * the {@code receiver} will be invoked after the previous request is completed 145 * 3. Otherwise, OTBR sends Address Release Notification (i.e. ADDR_REL.ntf) to gracefully 146 * detach from the current network and it takes 1 second to finish 147 * 4. The Operational Dataset will be removed from persistent storage 148 * 149 * @sa android.net.thread.ThreadNetworkController#leave 150 */ leave(in IOtStatusReceiver receiver)151 void leave(in IOtStatusReceiver receiver); 152 153 /** Migrates to the new network specified by {@code pendingOpDatasetTlvs}. 154 * 155 * @sa android.net.thread.ThreadNetworkController#scheduleMigration 156 */ scheduleMigration( in byte[] pendingOpDatasetTlvs, in IOtStatusReceiver receiver)157 void scheduleMigration( 158 in byte[] pendingOpDatasetTlvs, in IOtStatusReceiver receiver); 159 160 /** 161 * Sets the country code. 162 * 163 * @param countryCode 2 bytes country code (as defined in ISO 3166) to set. 164 * @param receiver the receiver to receive result of this operation 165 */ setCountryCode(in String countryCode, in IOtStatusReceiver receiver)166 oneway void setCountryCode(in String countryCode, in IOtStatusReceiver receiver); 167 168 /** 169 * Configures the Border Router features. 170 * 171 * @param brConfig the border router's configuration 172 * @param receiver the status receiver 173 * 174 */ configureBorderRouter( in BorderRouterConfigurationParcel brConfig, in IOtStatusReceiver receiver)175 oneway void configureBorderRouter( 176 in BorderRouterConfigurationParcel brConfig, in IOtStatusReceiver receiver); 177 178 /** 179 * Gets the supported and preferred channel masks. 180 * 181 * @param receiver the receiver to receive result of this operation 182 */ getChannelMasks(in IChannelMasksReceiver receiver)183 void getChannelMasks(in IChannelMasksReceiver receiver); 184 185 /** 186 * Sets the max power of each channel 187 * 188 * @param channelMaxPowers an array of {@code ChannelMaxPower}. 189 * @param receiver the receiver to the receive result of this operation. 190 */ setChannelMaxPowers(in ChannelMaxPower[] channelMaxPowers, in IOtStatusReceiver receiver)191 void setChannelMaxPowers(in ChannelMaxPower[] channelMaxPowers, in IOtStatusReceiver receiver); 192 193 // TODO: add Border Router APIs 194 } 195