1 /* 2 * Copyright (C) 2021 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 com.android.car; 18 19 import android.annotation.Nullable; 20 import android.car.builtin.util.Slogf; 21 import android.hardware.automotive.vehicle.SubscribeOptions; 22 import android.os.RemoteException; 23 import android.os.ServiceSpecificException; 24 25 import com.android.car.hal.HalClientCallback; 26 import com.android.car.hal.HalPropConfig; 27 import com.android.car.hal.HalPropValue; 28 import com.android.car.hal.HalPropValueBuilder; 29 30 import java.io.FileDescriptor; 31 import java.util.ArrayList; 32 33 /** 34 * VehicleStub represents an IVehicle service interface in either AIDL or legacy HIDL version. It 35 * exposes common interface so that the client does not need to care about which version the 36 * underlying IVehicle service is in. 37 */ 38 public abstract class VehicleStub { 39 /** 40 * SubscriptionClient represents a client that could subscribe/unsubscribe to properties. 41 */ 42 public interface SubscriptionClient { 43 /** 44 * Subscribes to a property. 45 * 46 * @param options The list of subscribe options. 47 * @throws RemoteException if the remote operation fails. 48 * @throws ServiceSpecificException if VHAL returns service specific error. 49 */ subscribe(SubscribeOptions[] options)50 void subscribe(SubscribeOptions[] options) throws RemoteException, ServiceSpecificException; 51 52 /** 53 * Unsubscribes from a property. 54 * 55 * @param prop The ID for the property to unsubscribe. 56 * @throws RemoteException if the remote operation fails. 57 * @throws ServiceSpecificException if VHAL returns service specific error. 58 */ unsubscribe(int prop)59 void unsubscribe(int prop) throws RemoteException, ServiceSpecificException; 60 } 61 62 /** 63 * Checks whether we are connected to AIDL VHAL: {@code true} or HIDL VHAL: {@code false}. 64 */ isAidlVhal()65 public abstract boolean isAidlVhal(); 66 67 /** 68 * Creates a new VehicleStub to connect to Vehicle HAL. 69 * 70 * Create a new VehicleStub to connect to Vehicle HAL according to which backend (AIDL or HIDL) 71 * is available. This function will throw {@link IllegalStateException} if no vehicle HAL is 72 * available. 73 * 74 * @return a vehicle stub to connect to Vehicle HAL. 75 */ newVehicleStub()76 public static VehicleStub newVehicleStub() throws IllegalStateException { 77 VehicleStub stub = new AidlVehicleStub(); 78 if (stub.isValid()) { 79 return stub; 80 } 81 82 Slogf.i(CarLog.TAG_SERVICE, "No AIDL vehicle HAL found, fall back to HIDL version"); 83 84 stub = new HidlVehicleStub(); 85 86 if (!stub.isValid()) { 87 throw new IllegalStateException("Vehicle HAL service is not available."); 88 } 89 90 return stub; 91 } 92 93 /** 94 * Gets a HalPropValueBuilder that could be used to build a HalPropValue. 95 * 96 * @return a builder to build HalPropValue. 97 */ getHalPropValueBuilder()98 public abstract HalPropValueBuilder getHalPropValueBuilder(); 99 100 /** 101 * Returns whether this vehicle stub is connecting to a valid vehicle HAL. 102 * 103 * @return Whether this vehicle stub is connecting to a valid vehicle HAL. 104 */ isValid()105 public abstract boolean isValid(); 106 107 /** 108 * Gets the interface descriptor for the connecting vehicle HAL. 109 * 110 * @return the interface descriptor. 111 * @throws IllegalStateException If unable to get the descriptor. 112 */ getInterfaceDescriptor()113 public abstract String getInterfaceDescriptor() throws IllegalStateException; 114 115 /** 116 * Registers a death recipient that would be called when vehicle HAL died. 117 * 118 * @param recipient A death recipient. 119 * @throws IllegalStateException If unable to register the death recipient. 120 */ linkToDeath(IVehicleDeathRecipient recipient)121 public abstract void linkToDeath(IVehicleDeathRecipient recipient) throws IllegalStateException; 122 123 /** 124 * Unlinks a previously linked death recipient. 125 * 126 * @param recipient A previously linked death recipient. 127 */ unlinkToDeath(IVehicleDeathRecipient recipient)128 public abstract void unlinkToDeath(IVehicleDeathRecipient recipient); 129 130 /** 131 * Gets all property configs. 132 * 133 * @return All the property configs. 134 * @throws RemoteException if the remote operation fails. 135 * @throws ServiceSpecificException if VHAL returns service specific error. 136 */ getAllPropConfigs()137 public abstract HalPropConfig[] getAllPropConfigs() 138 throws RemoteException, ServiceSpecificException; 139 140 /** 141 * Gets a new {@code SubscriptionClient} that could be used to subscribe/unsubscribe. 142 * 143 * @param callback A callback that could be used to receive events. 144 * @return a {@code SubscriptionClient} that could be used to subscribe/unsubscribe. 145 */ newSubscriptionClient(HalClientCallback callback)146 public abstract SubscriptionClient newSubscriptionClient(HalClientCallback callback); 147 148 /** 149 * Gets a property. 150 * 151 * @param requestedPropValue The property to get. 152 * @return The vehicle property value. 153 * @throws RemoteException if the remote operation fails. 154 * @throws ServiceSpecificException if VHAL returns service specific error. 155 */ 156 @Nullable get(HalPropValue requestedPropValue)157 public abstract HalPropValue get(HalPropValue requestedPropValue) 158 throws RemoteException, ServiceSpecificException; 159 160 /** 161 * Sets a property. 162 * 163 * @param propValue The property to set. 164 * @throws RemoteException if the remote operation fails. 165 * @throws ServiceSpecificException if VHAL returns service specific error. 166 */ set(HalPropValue propValue)167 public abstract void set(HalPropValue propValue) 168 throws RemoteException, ServiceSpecificException; 169 170 /** 171 * Dump VHAL debug information. 172 * 173 * Additional arguments could also be provided through {@link args} to debug VHAL. 174 * 175 * @param fd The file descriptor to print output. 176 * @param args Optional additional arguments for the debug command. Can be empty. 177 * @throws RemoteException if the remote operation fails. 178 * @throws ServiceSpecificException if VHAL returns service specific error. 179 */ dump(FileDescriptor fd, ArrayList<String> args)180 public abstract void dump(FileDescriptor fd, ArrayList<String> args) 181 throws RemoteException, ServiceSpecificException; 182 } 183