1/*
2 * Copyright (C) 2017 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 */
16package com.android.server.usb.descriptors.report;
17
18import android.hardware.usb.UsbDeviceConnection;
19
20/**
21 * @hide
22 * Defines a class for generating report data in a variety of potential formats.
23 */
24public abstract class ReportCanvas {
25    private static final String TAG = "ReportCanvas";
26
27    private final UsbDeviceConnection mConnection;
28
29    /**
30     * Constructor.
31     * @param connection    The USB connection object used to retrieve strings
32     * from the USB device.
33     */
34    public ReportCanvas(UsbDeviceConnection connection) {
35        mConnection = connection;
36    }
37
38    /**
39     * @returns the UsbDeviceConnection member (mConnection).
40     */
41    public UsbDeviceConnection getConnection() {
42        return mConnection;
43    }
44
45    /**
46     * Writes a plain string to the output.
47     */
48    public abstract void write(String text);
49
50    /**
51     * Opens a "header" formatted section in the output.
52     * @param level Specifies the logical level of the header.
53     */
54    public abstract void openHeader(int level);
55
56    /**
57     * Closes a "header" formatted section in the output.
58     * @param level Specifies the logical level of the header.
59     */
60    public abstract void closeHeader(int level);
61
62    /**
63     * Writes a "header" formatted string to the output.
64     * @param level Specifies the logical level of the header.
65     * @param text  Specifies the text to display in the header.
66     */
67    public void writeHeader(int level, String text) {
68        openHeader(level);
69        write(text);
70        closeHeader(level);
71    }
72
73    /**
74     * Opens a paragraph construct in the output.
75     * @param emphasis Specifies whether the text in the paragraph should
76     * be displayed with "emphasis" formatting.
77     */
78    public abstract void openParagraph(boolean emphasis);
79
80    /**
81     * Closes a paragraph construct in the output.
82     */
83    public abstract void closeParagraph();
84
85    /**
86     * Writes a paragraph construct to the output.
87     * @param text  The text to display with "paragraph" formatting.
88     * @param emphasis Specifies whether the text in the paragraph should
89     * be displayed with "emphasis" formatting.
90     */
91    public abstract void writeParagraph(String text, boolean emphasis);
92
93    /**
94     * Opens a "list" formatted section in the output.
95     */
96    public abstract void openList();
97
98    /**
99     * Closes a "list" formatted section in the output.
100     */
101    public abstract void closeList();
102
103    /**
104     * Opens a "list item" formatted section in the output.
105     */
106    public abstract void openListItem();
107
108    /**
109     * Closes a "list item" formatted section in the output.
110     */
111    public abstract void closeListItem();
112
113    /**
114     * Writes a "list item" formatted section in the output.
115     * @param text  Specifies the text of the list item.
116     */
117    public void writeListItem(String text) {
118        openListItem();
119        write(text);
120        closeListItem();
121    }
122
123    /*
124     * Data Formating Helpers
125     */
126    /**
127     * Generates a hex representation of the specified byte value.
128     * @param value The value to format.
129     */
130    //TODO Look into renaming the "getHexString()" functions to be more
131    // representative of the types they handle.
132    public static String getHexString(byte value) {
133        return "0x" + Integer.toHexString(((int) value) & 0xFF).toUpperCase();
134    }
135
136    /**
137     * Generates a string representing a USB Binary-Coded Decimal value.
138     * @param valueBCD The value to format.
139     */
140    public static String getBCDString(int valueBCD) {
141        int major = (valueBCD >> 8) & 0x0F;
142        int minor = (valueBCD >> 4) & 0x0F;
143        int subminor = valueBCD & 0x0F;
144
145        return "" + major + "." + minor + subminor;
146    }
147
148    /**
149     * Generates a hex representation of the specified 16-bit integer value.
150     * @param value The value to format.
151     */
152    //TODO Look into renaming the "getHexString()" functions to be more
153    // representative of the types they handle.
154    public static String getHexString(int value) {
155        int intValue = value & 0xFFFF;
156        return "0x" + Integer.toHexString(intValue).toUpperCase();
157    }
158
159    /**
160     * Writes out the specified byte array to the provided StringBuilder.
161     * @param rawData   The byte values.
162     * @param builder The StringBuilder to write text into.
163     */
164    public void dumpHexArray(byte[] rawData, StringBuilder builder) {
165        if (rawData != null) {
166            // Assume the type and Length and perhaps sub-type have been displayed
167            openParagraph(false);
168            for (int index = 0; index < rawData.length; index++) {
169                builder.append(getHexString(rawData[index]) + " ");
170            }
171            closeParagraph();
172        }
173    }
174}
175