1/*
2 * Copyright (C) 2011 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
17package android.hardware.usb;
18
19import android.annotation.NonNull;
20import android.annotation.Nullable;
21import android.os.Parcel;
22import android.os.Parcelable;
23import com.android.internal.util.Preconditions;
24
25/**
26 * A class representing a USB accessory, which is an external hardware component
27 * that communicates with an android application over USB.
28 * The accessory is the USB host and android the device side of the USB connection.
29 *
30 * <p>When the accessory connects, it reports its manufacturer and model names,
31 * the version of the accessory, and a user visible description of the accessory to the device.
32 * The manufacturer, model and version strings are used by the USB Manager to choose
33 * an appropriate application for the accessory.
34 * The accessory may optionally provide a unique serial number
35 * and a URL to for the accessory's website to the device as well.
36 *
37 * <p>An instance of this class is sent to the application via the
38 * {@link UsbManager#ACTION_USB_ACCESSORY_ATTACHED} Intent.
39 * The application can then call {@link UsbManager#openAccessory} to open a file descriptor
40 * for reading and writing data to and from the accessory.
41 *
42 * <div class="special reference">
43 * <h3>Developer Guides</h3>
44 * <p>For more information about communicating with USB hardware, read the
45 * <a href="{@docRoot}guide/topics/usb/index.html">USB</a> developer guide.</p>
46 * </div>
47 */
48public class UsbAccessory implements Parcelable {
49
50    private static final String TAG = "UsbAccessory";
51
52    private final @NonNull String mManufacturer;
53    private final @NonNull String mModel;
54    private final @Nullable String mDescription;
55    private final @Nullable String mVersion;
56    private final @Nullable String mUri;
57    private final @Nullable String mSerial;
58
59    /** @hide */
60    public static final int MANUFACTURER_STRING = 0;
61    /** @hide */
62    public static final int MODEL_STRING = 1;
63    /** @hide */
64    public static final int DESCRIPTION_STRING = 2;
65    /** @hide */
66    public static final int VERSION_STRING = 3;
67    /** @hide */
68    public static final int URI_STRING = 4;
69    /** @hide */
70    public static final int SERIAL_STRING = 5;
71
72    /**
73     * UsbAccessory should only be instantiated by UsbService implementation
74     * @hide
75     */
76    public UsbAccessory(@NonNull String manufacturer, @NonNull String model,
77            @Nullable String description, @Nullable String version, @Nullable String uri,
78            @Nullable String serial) {
79        mManufacturer = Preconditions.checkNotNull(manufacturer);
80        mModel = Preconditions.checkNotNull(model);
81        mDescription = description;
82        mVersion = version;
83        mUri = uri;
84        mSerial = serial;
85    }
86
87    /**
88     * UsbAccessory should only be instantiated by UsbService implementation
89     * @hide
90     */
91    public UsbAccessory(String[] strings) {
92        this(strings[MANUFACTURER_STRING], strings[MODEL_STRING], strings[DESCRIPTION_STRING],
93                strings[VERSION_STRING], strings[URI_STRING], strings[SERIAL_STRING]);
94    }
95
96    /**
97     * Returns the manufacturer name of the accessory.
98     *
99     * @return the accessory manufacturer
100     */
101    public @NonNull String getManufacturer() {
102        return mManufacturer;
103    }
104
105    /**
106     * Returns the model name of the accessory.
107     *
108     * @return the accessory model
109     */
110    public @NonNull String getModel() {
111        return mModel;
112    }
113
114    /**
115     * Returns a user visible description of the accessory.
116     *
117     * @return the accessory description, or {@code null} if not set
118     */
119    public @Nullable String getDescription() {
120        return mDescription;
121    }
122
123    /**
124     * Returns the version of the accessory.
125     *
126     * @return the accessory version, or {@code null} if not set
127     */
128    public @Nullable String getVersion() {
129        return mVersion;
130    }
131
132    /**
133     * Returns the URI for the accessory.
134     * This is an optional URI that might show information about the accessory
135     * or provide the option to download an application for the accessory
136     *
137     * @return the accessory URI, or {@code null} if not set
138     */
139    public @Nullable String getUri() {
140        return mUri;
141    }
142
143    /**
144     * Returns the unique serial number for the accessory.
145     * This is an optional serial number that can be used to differentiate
146     * between individual accessories of the same model and manufacturer
147     *
148     * @return the unique serial number, or {@code null} if not set
149     */
150    public @Nullable String getSerial() {
151        return mSerial;
152    }
153
154    private static boolean compare(String s1, String s2) {
155        if (s1 == null) return (s2 == null);
156        return s1.equals(s2);
157    }
158
159    @Override
160    public boolean equals(Object obj) {
161        if (obj instanceof UsbAccessory) {
162            UsbAccessory accessory = (UsbAccessory)obj;
163            return (compare(mManufacturer, accessory.getManufacturer()) &&
164                    compare(mModel, accessory.getModel()) &&
165                    compare(mDescription, accessory.getDescription()) &&
166                    compare(mVersion, accessory.getVersion()) &&
167                    compare(mUri, accessory.getUri()) &&
168                    compare(mSerial, accessory.getSerial()));
169        }
170        return false;
171    }
172
173    @Override
174    public int hashCode() {
175        return mManufacturer.hashCode() ^ mModel.hashCode() ^
176                (mDescription == null ? 0 : mDescription.hashCode()) ^
177                (mVersion == null ? 0 : mVersion.hashCode()) ^
178                (mUri == null ? 0 : mUri.hashCode()) ^ (mSerial == null ? 0 : mSerial.hashCode());
179    }
180
181    @Override
182    public String toString() {
183        return "UsbAccessory[mManufacturer=" + mManufacturer +
184                            ", mModel=" + mModel +
185                            ", mDescription=" + mDescription +
186                            ", mVersion=" + mVersion +
187                            ", mUri=" + mUri +
188                            ", mSerial=" + mSerial + "]";
189    }
190
191    public static final Parcelable.Creator<UsbAccessory> CREATOR =
192        new Parcelable.Creator<UsbAccessory>() {
193        public UsbAccessory createFromParcel(Parcel in) {
194            String manufacturer = in.readString();
195            String model = in.readString();
196            String description = in.readString();
197            String version = in.readString();
198            String uri = in.readString();
199            String serial = in.readString();
200            return new UsbAccessory(manufacturer, model, description, version, uri, serial);
201        }
202
203        public UsbAccessory[] newArray(int size) {
204            return new UsbAccessory[size];
205        }
206    };
207
208    public int describeContents() {
209        return 0;
210    }
211
212    public void writeToParcel(Parcel parcel, int flags) {
213        parcel.writeString(mManufacturer);
214        parcel.writeString(mModel);
215        parcel.writeString(mDescription);
216        parcel.writeString(mVersion);
217        parcel.writeString(mUri);
218        parcel.writeString(mSerial);
219   }
220}
221