1/*
2 * Copyright (C) 2014 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;
23
24import com.android.internal.util.Preconditions;
25
26/**
27 * A class representing a configuration on a {@link UsbDevice}.
28 * A USB configuration can have one or more interfaces, each one providing a different
29 * piece of functionality, separate from the other interfaces.
30 * An interface will have one or more {@link UsbEndpoint}s, which are the
31 * channels by which the host transfers data with the device.
32 *
33 * <div class="special reference">
34 * <h3>Developer Guides</h3>
35 * <p>For more information about communicating with USB hardware, read the
36 * <a href="{@docRoot}guide/topics/usb/index.html">USB</a> developer guide.</p>
37 * </div>
38 */
39public class UsbConfiguration implements Parcelable {
40
41    private final int mId;
42    private final @Nullable String mName;
43    private final int mAttributes;
44    private final int mMaxPower;
45
46    /** All interfaces for this config, only null during creation */
47    private @Nullable Parcelable[] mInterfaces;
48
49    /**
50     * Mask for "self-powered" bit in the configuration's attributes.
51     */
52    private static final int ATTR_SELF_POWERED = 1 << 6;
53
54    /**
55     * Mask for "remote wakeup" bit in the configuration's attributes.
56     */
57    private static final int ATTR_REMOTE_WAKEUP = 1 << 5;
58
59    /**
60     * UsbConfiguration should only be instantiated by UsbService implementation
61     * @hide
62     */
63    public UsbConfiguration(int id, @Nullable String name, int attributes, int maxPower) {
64        mId = id;
65        mName = name;
66        mAttributes = attributes;
67        mMaxPower = maxPower;
68    }
69
70    /**
71     * Returns the configuration's ID field.
72     * This is an integer that uniquely identifies the configuration on the device.
73     *
74     * @return the configuration's ID
75     */
76    public int getId() {
77        return mId;
78    }
79
80    /**
81     * Returns the configuration's name.
82     *
83     * @return the configuration's name, or {@code null} if the property could not be read
84     */
85    public @Nullable String getName() {
86        return mName;
87    }
88
89    /**
90     * Returns the self-powered attribute value configuration's attributes field.
91     * This attribute indicates that the device has a power source other than the USB connection.
92     *
93     * @return the configuration's self-powered attribute
94     */
95    public boolean isSelfPowered() {
96        return (mAttributes & ATTR_SELF_POWERED) != 0;
97    }
98
99    /**
100     * Returns the remote-wakeup attribute value configuration's attributes field.
101     * This attributes that the device may signal the host to wake from suspend.
102     *
103     * @return the configuration's remote-wakeup attribute
104     */
105    public boolean isRemoteWakeup() {
106        return (mAttributes & ATTR_REMOTE_WAKEUP) != 0;
107    }
108
109    /**
110     * Returns the attributes of this configuration
111     *
112     * @return the configuration's attributes
113     *
114     * @hide
115     */
116    public int getAttributes() {
117        return mAttributes;
118    }
119
120    /**
121     * Returns the configuration's max power consumption, in milliamps.
122     *
123     * @return the configuration's max power
124     */
125    public int getMaxPower() {
126        return mMaxPower * 2;
127    }
128
129    /**
130     * Returns the number of {@link UsbInterface}s this configuration contains.
131     *
132     * @return the number of endpoints
133     */
134    public int getInterfaceCount() {
135        return mInterfaces.length;
136    }
137
138    /**
139     * Returns the {@link UsbInterface} at the given index.
140     *
141     * @return the interface
142     */
143    public @NonNull UsbInterface getInterface(int index) {
144        return (UsbInterface)mInterfaces[index];
145    }
146
147    /**
148     * Only used by UsbService implementation
149     * @hide
150     */
151    public void setInterfaces(@NonNull Parcelable[] interfaces) {
152        mInterfaces = Preconditions.checkArrayElementsNotNull(interfaces, "interfaces");
153    }
154
155    @Override
156    public String toString() {
157        StringBuilder builder = new StringBuilder("UsbConfiguration[mId=" + mId +
158                ",mName=" + mName + ",mAttributes=" + mAttributes +
159                ",mMaxPower=" + mMaxPower + ",mInterfaces=[");
160        for (int i = 0; i < mInterfaces.length; i++) {
161            builder.append("\n");
162            builder.append(mInterfaces[i].toString());
163        }
164        builder.append("]");
165        return builder.toString();
166    }
167
168    public static final Parcelable.Creator<UsbConfiguration> CREATOR =
169        new Parcelable.Creator<UsbConfiguration>() {
170        public UsbConfiguration createFromParcel(Parcel in) {
171            int id = in.readInt();
172            String name = in.readString();
173            int attributes = in.readInt();
174            int maxPower = in.readInt();
175            Parcelable[] interfaces = in.readParcelableArray(UsbInterface.class.getClassLoader());
176            UsbConfiguration configuration = new UsbConfiguration(id, name, attributes, maxPower);
177            configuration.setInterfaces(interfaces);
178            return configuration;
179        }
180
181        public UsbConfiguration[] newArray(int size) {
182            return new UsbConfiguration[size];
183        }
184    };
185
186    public int describeContents() {
187        return 0;
188    }
189
190    public void writeToParcel(Parcel parcel, int flags) {
191        parcel.writeInt(mId);
192        parcel.writeString(mName);
193        parcel.writeInt(mAttributes);
194        parcel.writeInt(mMaxPower);
195        parcel.writeParcelableArray(mInterfaces, 0);
196   }
197}
198