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