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