| /* |
| * Copyright (C) 2016 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.net.wifi.nan; |
| |
| import libcore.io.Memory; |
| |
| import java.nio.BufferOverflowException; |
| import java.nio.ByteOrder; |
| import java.util.Iterator; |
| |
| /** |
| * Utility class to construct and parse byte arrays using the TLV format - |
| * Type/Length/Value format. The utilities accept a configuration of the size of |
| * the Type field and the Length field. A Type field size of 0 is allowed - |
| * allowing usage for LV (no T) array formats. |
| * |
| * @hide PROPOSED_NAN_API |
| */ |
| public class TlvBufferUtils { |
| private TlvBufferUtils() { |
| // no reason to ever create this class |
| } |
| |
| /** |
| * Utility class to construct byte arrays using the TLV format - |
| * Type/Length/Value. |
| * <p> |
| * A constructor is created specifying the size of the Type (T) and Length |
| * (L) fields. A specification of zero size T field is allowed - resulting |
| * in LV type format. |
| * <p> |
| * The byte array is either provided (using |
| * {@link TlvConstructor#wrap(byte[])}) or allocated (using |
| * {@link TlvConstructor#allocate(int)}). |
| * <p> |
| * Values are added to the structure using the {@code TlvConstructor.put*()} |
| * methods. |
| * <p> |
| * The final byte array is obtained using {@link TlvConstructor#getArray()} |
| * and {@link TlvConstructor#getActualLength()} methods. |
| */ |
| public static class TlvConstructor { |
| private int mTypeSize; |
| private int mLengthSize; |
| |
| private byte[] mArray; |
| private int mArrayLength; |
| private int mPosition; |
| |
| /** |
| * Define a TLV constructor with the specified size of the Type (T) and |
| * Length (L) fields. |
| * |
| * @param typeSize Number of bytes used for the Type (T) field. Values |
| * of 0, 1, or 2 bytes are allowed. A specification of 0 |
| * bytes implies that the field being constructed has the LV |
| * format rather than the TLV format. |
| * @param lengthSize Number of bytes used for the Length (L) field. |
| * Values of 1 or 2 bytes are allowed. |
| */ |
| public TlvConstructor(int typeSize, int lengthSize) { |
| if (typeSize < 0 || typeSize > 2 || lengthSize <= 0 || lengthSize > 2) { |
| throw new IllegalArgumentException( |
| "Invalid sizes - typeSize=" + typeSize + ", lengthSize=" + lengthSize); |
| } |
| mTypeSize = typeSize; |
| mLengthSize = lengthSize; |
| } |
| |
| /** |
| * Set the byte array to be used to construct the TLV. |
| * |
| * @param array Byte array to be formatted. |
| * @return The constructor to facilitate chaining |
| * {@code ctr.putXXX(..).putXXX(..)}. |
| */ |
| public TlvConstructor wrap(byte[] array) { |
| mArray = array; |
| mArrayLength = array.length; |
| return this; |
| } |
| |
| /** |
| * Allocates a new byte array to be used ot construct a TLV. |
| * |
| * @param capacity The size of the byte array to be allocated. |
| * @return The constructor to facilitate chaining |
| * {@code ctr.putXXX(..).putXXX(..)}. |
| */ |
| public TlvConstructor allocate(int capacity) { |
| mArray = new byte[capacity]; |
| mArrayLength = capacity; |
| return this; |
| } |
| |
| /** |
| * Copies a byte into the TLV with the indicated type. For an LV |
| * formatted structure (i.e. typeLength=0 in {@link TlvConstructor |
| * TlvConstructor(int, int)} ) the type field is ignored. |
| * |
| * @param type The value to be placed into the Type field. |
| * @param b The byte to be inserted into the structure. |
| * @return The constructor to facilitate chaining |
| * {@code ctr.putXXX(..).putXXX(..)}. |
| */ |
| public TlvConstructor putByte(int type, byte b) { |
| checkLength(1); |
| addHeader(type, 1); |
| mArray[mPosition++] = b; |
| return this; |
| } |
| |
| /** |
| * Copies a byte array into the TLV with the indicated type. For an LV |
| * formatted structure (i.e. typeLength=0 in {@link TlvConstructor |
| * TlvConstructor(int, int)} ) the type field is ignored. |
| * |
| * @param type The value to be placed into the Type field. |
| * @param array The array to be copied into the TLV structure. |
| * @param offset Start copying from the array at the specified offset. |
| * @param length Copy the specified number (length) of bytes from the |
| * array. |
| * @return The constructor to facilitate chaining |
| * {@code ctr.putXXX(..).putXXX(..)}. |
| */ |
| public TlvConstructor putByteArray(int type, byte[] array, int offset, int length) { |
| checkLength(length); |
| addHeader(type, length); |
| System.arraycopy(array, offset, mArray, mPosition, length); |
| mPosition += length; |
| return this; |
| } |
| |
| /** |
| * Copies a byte array into the TLV with the indicated type. For an LV |
| * formatted structure (i.e. typeLength=0 in {@link TlvConstructor |
| * TlvConstructor(int, int)} ) the type field is ignored. |
| * |
| * @param type The value to be placed into the Type field. |
| * @param array The array to be copied (in full) into the TLV structure. |
| * @return The constructor to facilitate chaining |
| * {@code ctr.putXXX(..).putXXX(..)}. |
| */ |
| public TlvConstructor putByteArray(int type, byte[] array) { |
| return putByteArray(type, array, 0, array.length); |
| } |
| |
| /** |
| * Places a zero length element (i.e. Length field = 0) into the TLV. |
| * For an LV formatted structure (i.e. typeLength=0 in |
| * {@link TlvConstructor TlvConstructor(int, int)} ) the type field is |
| * ignored. |
| * |
| * @param type The value to be placed into the Type field. |
| * @return The constructor to facilitate chaining |
| * {@code ctr.putXXX(..).putXXX(..)}. |
| */ |
| public TlvConstructor putZeroLengthElement(int type) { |
| checkLength(0); |
| addHeader(type, 0); |
| return this; |
| } |
| |
| /** |
| * Copies short into the TLV with the indicated type. For an LV |
| * formatted structure (i.e. typeLength=0 in {@link TlvConstructor |
| * TlvConstructor(int, int)} ) the type field is ignored. |
| * |
| * @param type The value to be placed into the Type field. |
| * @param data The short to be inserted into the structure. |
| * @return The constructor to facilitate chaining |
| * {@code ctr.putXXX(..).putXXX(..)}. |
| */ |
| public TlvConstructor putShort(int type, short data) { |
| checkLength(2); |
| addHeader(type, 2); |
| Memory.pokeShort(mArray, mPosition, data, ByteOrder.BIG_ENDIAN); |
| mPosition += 2; |
| return this; |
| } |
| |
| /** |
| * Copies integer into the TLV with the indicated type. For an LV |
| * formatted structure (i.e. typeLength=0 in {@link TlvConstructor |
| * TlvConstructor(int, int)} ) the type field is ignored. |
| * |
| * @param type The value to be placed into the Type field. |
| * @param data The integer to be inserted into the structure. |
| * @return The constructor to facilitate chaining |
| * {@code ctr.putXXX(..).putXXX(..)}. |
| */ |
| public TlvConstructor putInt(int type, int data) { |
| checkLength(4); |
| addHeader(type, 4); |
| Memory.pokeInt(mArray, mPosition, data, ByteOrder.BIG_ENDIAN); |
| mPosition += 4; |
| return this; |
| } |
| |
| /** |
| * Copies a String's byte representation into the TLV with the indicated |
| * type. For an LV formatted structure (i.e. typeLength=0 in |
| * {@link TlvConstructor TlvConstructor(int, int)} ) the type field is |
| * ignored. |
| * |
| * @param type The value to be placed into the Type field. |
| * @param data The string whose bytes are to be inserted into the |
| * structure. |
| * @return The constructor to facilitate chaining |
| * {@code ctr.putXXX(..).putXXX(..)}. |
| */ |
| public TlvConstructor putString(int type, String data) { |
| return putByteArray(type, data.getBytes(), 0, data.length()); |
| } |
| |
| /** |
| * Returns the constructed TLV formatted byte-array. Note that the |
| * returned array is the fully wrapped ( |
| * {@link TlvConstructor#wrap(byte[])}) or allocated ( |
| * {@link TlvConstructor#allocate(int)}) array - which isn't necessarily |
| * the actual size of the formatted data. Use |
| * {@link TlvConstructor#getActualLength()} to obtain the size of the |
| * formatted data. |
| * |
| * @return The byte array containing the TLV formatted structure. |
| */ |
| public byte[] getArray() { |
| return mArray; |
| } |
| |
| /** |
| * Returns the size of the TLV formatted portion of the wrapped or |
| * allocated byte array. The array itself is returned with |
| * {@link TlvConstructor#getArray()}. |
| * |
| * @return The size of the TLV formatted portion of the byte array. |
| */ |
| public int getActualLength() { |
| return mPosition; |
| } |
| |
| private void checkLength(int dataLength) { |
| if (mPosition + mTypeSize + mLengthSize + dataLength > mArrayLength) { |
| throw new BufferOverflowException(); |
| } |
| } |
| |
| private void addHeader(int type, int length) { |
| if (mTypeSize == 1) { |
| mArray[mPosition] = (byte) type; |
| } else if (mTypeSize == 2) { |
| Memory.pokeShort(mArray, mPosition, (short) type, ByteOrder.BIG_ENDIAN); |
| } |
| mPosition += mTypeSize; |
| |
| if (mLengthSize == 1) { |
| mArray[mPosition] = (byte) length; |
| } else if (mLengthSize == 2) { |
| Memory.pokeShort(mArray, mPosition, (short) length, ByteOrder.BIG_ENDIAN); |
| } |
| mPosition += mLengthSize; |
| } |
| } |
| |
| /** |
| * Utility class used when iterating over a TLV formatted byte-array. Use |
| * {@link TlvIterable} to iterate over array. A {@link TlvElement} |
| * represents each entry in a TLV formatted byte-array. |
| */ |
| public static class TlvElement { |
| /** |
| * The Type (T) field of the current TLV element. Note that for LV |
| * formatted byte-arrays (i.e. TLV whose Type/T size is 0) the value of |
| * this field is undefined. |
| */ |
| public int mType; |
| |
| /** |
| * The Length (L) field of the current TLV element. |
| */ |
| public int mLength; |
| |
| /** |
| * The Value (V) field - a raw byte array representing the current TLV |
| * element where the entry starts at {@link TlvElement#mOffset}. |
| */ |
| public byte[] mRefArray; |
| |
| /** |
| * The offset to be used into {@link TlvElement#mRefArray} to access the |
| * raw data representing the current TLV element. |
| */ |
| public int mOffset; |
| |
| private TlvElement(int type, int length, byte[] refArray, int offset) { |
| mType = type; |
| mLength = length; |
| mRefArray = refArray; |
| mOffset = offset; |
| } |
| |
| /** |
| * Utility function to return a byte representation of a TLV element of |
| * length 1. Note: an attempt to call this function on a TLV item whose |
| * {@link TlvElement#mLength} is != 1 will result in an exception. |
| * |
| * @return byte representation of current TLV element. |
| */ |
| public byte getByte() { |
| if (mLength != 1) { |
| throw new IllegalArgumentException( |
| "Accesing a byte from a TLV element of length " + mLength); |
| } |
| return mRefArray[mOffset]; |
| } |
| |
| /** |
| * Utility function to return a short representation of a TLV element of |
| * length 2. Note: an attempt to call this function on a TLV item whose |
| * {@link TlvElement#mLength} is != 2 will result in an exception. |
| * |
| * @return short representation of current TLV element. |
| */ |
| public short getShort() { |
| if (mLength != 2) { |
| throw new IllegalArgumentException( |
| "Accesing a short from a TLV element of length " + mLength); |
| } |
| return Memory.peekShort(mRefArray, mOffset, ByteOrder.BIG_ENDIAN); |
| } |
| |
| /** |
| * Utility function to return an integer representation of a TLV element |
| * of length 4. Note: an attempt to call this function on a TLV item |
| * whose {@link TlvElement#mLength} is != 4 will result in an exception. |
| * |
| * @return integer representation of current TLV element. |
| */ |
| public int getInt() { |
| if (mLength != 4) { |
| throw new IllegalArgumentException( |
| "Accesing an int from a TLV element of length " + mLength); |
| } |
| return Memory.peekInt(mRefArray, mOffset, ByteOrder.BIG_ENDIAN); |
| } |
| |
| /** |
| * Utility function to return a String representation of a TLV element. |
| * |
| * @return String repersentation of the current TLV element. |
| */ |
| public String getString() { |
| return new String(mRefArray, mOffset, mLength); |
| } |
| } |
| |
| /** |
| * Utility class to iterate over a TLV formatted byte-array. |
| */ |
| public static class TlvIterable implements Iterable<TlvElement> { |
| private int mTypeSize; |
| private int mLengthSize; |
| private byte[] mArray; |
| private int mArrayLength; |
| |
| /** |
| * Constructs a TlvIterable object - specifying the format of the TLV |
| * (the sizes of the Type and Length fields), and the byte array whose |
| * data is to be parsed. |
| * |
| * @param typeSize Number of bytes used for the Type (T) field. Valid |
| * values are 0 (i.e. indicating the format is LV rather than |
| * TLV), 1, and 2 bytes. |
| * @param lengthSize Number of bytes sued for the Length (L) field. |
| * Values values are 1 or 2 bytes. |
| * @param array The TLV formatted byte-array to parse. |
| * @param length The number of bytes of the array to be used in the |
| * parsing. |
| */ |
| public TlvIterable(int typeSize, int lengthSize, byte[] array, int length) { |
| if (typeSize < 0 || typeSize > 2 || lengthSize <= 0 || lengthSize > 2) { |
| throw new IllegalArgumentException( |
| "Invalid sizes - typeSize=" + typeSize + ", lengthSize=" + lengthSize); |
| } |
| mTypeSize = typeSize; |
| mLengthSize = lengthSize; |
| mArray = array; |
| mArrayLength = length; |
| } |
| |
| /** |
| * Prints out a parsed representation of the TLV-formatted byte array. |
| * Whenever possible bytes, shorts, and integer are printed out (for |
| * fields whose length is 1, 2, or 4 respectively). |
| */ |
| @Override |
| public String toString() { |
| StringBuilder builder = new StringBuilder(); |
| |
| builder.append("["); |
| boolean first = true; |
| for (TlvElement tlv : this) { |
| if (!first) { |
| builder.append(","); |
| } |
| first = false; |
| builder.append(" ("); |
| if (mTypeSize != 0) { |
| builder.append("T=" + tlv.mType + ","); |
| } |
| builder.append("L=" + tlv.mLength + ") "); |
| if (tlv.mLength == 0) { |
| builder.append("<null>"); |
| } else if (tlv.mLength == 1) { |
| builder.append(tlv.getByte()); |
| } else if (tlv.mLength == 2) { |
| builder.append(tlv.getShort()); |
| } else if (tlv.mLength == 4) { |
| builder.append(tlv.getInt()); |
| } else { |
| builder.append("<bytes>"); |
| } |
| if (tlv.mLength != 0) { |
| builder.append(" (S='" + tlv.getString() + "')"); |
| } |
| } |
| builder.append("]"); |
| |
| return builder.toString(); |
| } |
| |
| /** |
| * Returns an iterator to step through a TLV formatted byte-array. The |
| * individual elements returned by the iterator are {@link TlvElement}. |
| */ |
| @Override |
| public Iterator<TlvElement> iterator() { |
| return new Iterator<TlvElement>() { |
| private int mOffset = 0; |
| |
| @Override |
| public boolean hasNext() { |
| return mOffset < mArrayLength; |
| } |
| |
| @Override |
| public TlvElement next() { |
| int type = 0; |
| if (mTypeSize == 1) { |
| type = mArray[mOffset]; |
| } else if (mTypeSize == 2) { |
| type = Memory.peekShort(mArray, mOffset, ByteOrder.BIG_ENDIAN); |
| } |
| mOffset += mTypeSize; |
| |
| int length = 0; |
| if (mLengthSize == 1) { |
| length = mArray[mOffset]; |
| } else if (mLengthSize == 2) { |
| length = Memory.peekShort(mArray, mOffset, ByteOrder.BIG_ENDIAN); |
| } |
| mOffset += mLengthSize; |
| |
| TlvElement tlv = new TlvElement(type, length, mArray, mOffset); |
| mOffset += length; |
| return tlv; |
| } |
| |
| @Override |
| public void remove() { |
| throw new UnsupportedOperationException(); |
| } |
| }; |
| } |
| } |
| } |