1 /* 2 * Copyright (C) 2019 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.google.android.exoplayer2.extractor.mkv; 17 18 import androidx.annotation.IntDef; 19 import com.google.android.exoplayer2.ParserException; 20 import com.google.android.exoplayer2.extractor.ExtractorInput; 21 import java.io.IOException; 22 import java.lang.annotation.Documented; 23 import java.lang.annotation.Retention; 24 import java.lang.annotation.RetentionPolicy; 25 26 /** Defines EBML element IDs/types and processes events. */ 27 public interface EbmlProcessor { 28 29 /** 30 * EBML element types. One of {@link #ELEMENT_TYPE_UNKNOWN}, {@link #ELEMENT_TYPE_MASTER}, {@link 31 * #ELEMENT_TYPE_UNSIGNED_INT}, {@link #ELEMENT_TYPE_STRING}, {@link #ELEMENT_TYPE_BINARY} or 32 * {@link #ELEMENT_TYPE_FLOAT}. 33 */ 34 @Documented 35 @Retention(RetentionPolicy.SOURCE) 36 @IntDef({ 37 ELEMENT_TYPE_UNKNOWN, 38 ELEMENT_TYPE_MASTER, 39 ELEMENT_TYPE_UNSIGNED_INT, 40 ELEMENT_TYPE_STRING, 41 ELEMENT_TYPE_BINARY, 42 ELEMENT_TYPE_FLOAT 43 }) 44 @interface ElementType {} 45 /** Type for unknown elements. */ 46 int ELEMENT_TYPE_UNKNOWN = 0; 47 /** Type for elements that contain child elements. */ 48 int ELEMENT_TYPE_MASTER = 1; 49 /** Type for integer value elements of up to 8 bytes. */ 50 int ELEMENT_TYPE_UNSIGNED_INT = 2; 51 /** Type for string elements. */ 52 int ELEMENT_TYPE_STRING = 3; 53 /** Type for binary elements. */ 54 int ELEMENT_TYPE_BINARY = 4; 55 /** Type for IEEE floating point value elements of either 4 or 8 bytes. */ 56 int ELEMENT_TYPE_FLOAT = 5; 57 58 /** 59 * Maps an element ID to a corresponding type. 60 * 61 * <p>If {@link #ELEMENT_TYPE_UNKNOWN} is returned then the element is skipped. Note that all 62 * children of a skipped element are also skipped. 63 * 64 * @param id The element ID to map. 65 * @return One of {@link #ELEMENT_TYPE_UNKNOWN}, {@link #ELEMENT_TYPE_MASTER}, {@link 66 * #ELEMENT_TYPE_UNSIGNED_INT}, {@link #ELEMENT_TYPE_STRING}, {@link #ELEMENT_TYPE_BINARY} and 67 * {@link #ELEMENT_TYPE_FLOAT}. 68 */ 69 @ElementType getElementType(int id)70 int getElementType(int id); 71 72 /** 73 * Checks if the given id is that of a level 1 element. 74 * 75 * @param id The element ID. 76 * @return Whether the given id is that of a level 1 element. 77 */ isLevel1Element(int id)78 boolean isLevel1Element(int id); 79 80 /** 81 * Called when the start of a master element is encountered. 82 * <p> 83 * Following events should be considered as taking place within this element until a matching call 84 * to {@link #endMasterElement(int)} is made. 85 * <p> 86 * Note that it is possible for another master element of the same element ID to be nested within 87 * itself. 88 * 89 * @param id The element ID. 90 * @param contentPosition The position of the start of the element's content in the stream. 91 * @param contentSize The size of the element's content in bytes. 92 * @throws ParserException If a parsing error occurs. 93 */ startMasterElement(int id, long contentPosition, long contentSize)94 void startMasterElement(int id, long contentPosition, long contentSize) throws ParserException; 95 96 /** 97 * Called when the end of a master element is encountered. 98 * 99 * @param id The element ID. 100 * @throws ParserException If a parsing error occurs. 101 */ endMasterElement(int id)102 void endMasterElement(int id) throws ParserException; 103 104 /** 105 * Called when an integer element is encountered. 106 * 107 * @param id The element ID. 108 * @param value The integer value that the element contains. 109 * @throws ParserException If a parsing error occurs. 110 */ integerElement(int id, long value)111 void integerElement(int id, long value) throws ParserException; 112 113 /** 114 * Called when a float element is encountered. 115 * 116 * @param id The element ID. 117 * @param value The float value that the element contains 118 * @throws ParserException If a parsing error occurs. 119 */ floatElement(int id, double value)120 void floatElement(int id, double value) throws ParserException; 121 122 /** 123 * Called when a string element is encountered. 124 * 125 * @param id The element ID. 126 * @param value The string value that the element contains. 127 * @throws ParserException If a parsing error occurs. 128 */ stringElement(int id, String value)129 void stringElement(int id, String value) throws ParserException; 130 131 /** 132 * Called when a binary element is encountered. 133 * 134 * <p>The element header (containing the element ID and content size) will already have been read. 135 * Implementations are required to consume the whole remainder of the element, which is {@code 136 * contentSize} bytes in length, before returning. Implementations are permitted to fail (by 137 * throwing an exception) having partially consumed the data, however if they do this, they must 138 * consume the remainder of the content when called again. 139 * 140 * @param id The element ID. 141 * @param contentsSize The element's content size. 142 * @param input The {@link ExtractorInput} from which data should be read. 143 * @throws ParserException If a parsing error occurs. 144 * @throws IOException If an error occurs reading from the input. 145 */ binaryElement(int id, int contentsSize, ExtractorInput input)146 void binaryElement(int id, int contentsSize, ExtractorInput input) throws IOException; 147 } 148