Metadata.java revision 9193e08dc1d91401fdf1846eaad4689da3911dc1 
1/*
2 * Copyright (C) 2009 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.media;
18
19import android.graphics.Bitmap;
20import android.util.Log;
21
22import java.util.Collections;
23import java.util.Date;
24import java.util.Iterator;
25import java.util.Set;
26
27/**
28   Class to hold the media's metadata.  Metadata are used
29   for human consumption and can be embedded in the media (e.g
30   shoutcast) or available from an external source. The source can be
31   local (e.g thumbnail stored in the DB) or remote (e.g caption
32   server).
33
34   Metadata is like a Bundle. It is sparse and each key can occur at
35   most once. The key is an integer and the value is the actual metadata.
36
37   The caller is expected to know the type of the metadata and call
38   the right get* method to fetch its value.
39
40   // FIXME: unhide.
41   {@hide}
42 */
43public class Metadata
44{
45    // The metadata are keyed using integers rather than more heavy
46    // weight strings. We considered using Bundle to ship the metadata
47    // between the native layer and the java layer but dropped that
48    // option since keeping in sync a native implementation of Bundle
49    // and the java one would be too burdensome. Besides Bundle uses
50    // String for its keys.
51    // The key range [0 8192) is reserved for the system.
52    //
53    // We manually serialize the data in Parcels. For large memory
54    // blob (bitmaps, raw pictures) we use MemoryFile which allow the
55    // client to make the data purgeable once it is done with it.
56    //
57
58    public static final int ANY = 0;  // Never used for metadata returned, only for filtering.
59
60    // TODO: Should we use numbers compatible with the metadata retriever?
61    public static final int TITLE = 1;           // String
62    public static final int COMMENT = 2;         // String
63    public static final int COPYRIGHT = 3;       // String
64    public static final int ALBUM = 4;           // String
65    public static final int ARTIST = 5;          // String
66    public static final int AUTHOR = 6;          // String
67    public static final int COMPOSER = 7;        // String
68    public static final int GENRE = 8;           // String
69    public static final int DATE = 9;            // Date
70    public static final int DURATION = 10;       // Integer(millisec)
71    public static final int CD_TRACK_NUM = 11;   // Integer 1-based
72    public static final int CD_TRACK_MAX = 12;   // Integer
73    public static final int RATING = 13;         // String
74    public static final int ALBUM_ART = 14;      // byte[]
75    public static final int VIDEO_FRAME = 15;    // Bitmap
76    public static final int CAPTION = 16;        // TimedText
77
78    public static final int BIT_RATE = 17;       // Integer, Aggregate rate of
79                                                 // all the streams in bps.
80
81    public static final int AUDIO_BIT_RATE = 18; // Integer, bps
82    public static final int VIDEO_BIT_RATE = 19; // Integer, bps
83    public static final int AUDIO_SAMPLE_RATE = 20; // Integer, Hz
84    public static final int VIDEO_FRAME_RATE = 21;  // Integer, Hz
85
86    // See RFC2046 and RFC4281.
87    public static final int MIME_TYPE = 22;      // String
88    public static final int AUDIO_CODEC = 23;    // String
89    public static final int VIDEO_CODEC = 24;    // String
90
91    public static final int VIDEO_HEIGHT = 25;   // Integer
92    public static final int VIDEO_WIDTH = 26;    // Integer
93    public static final int NUM_TRACKS = 27;     // Integer
94    public static final int DRM_CRIPPLED = 28;   // Boolean
95    public static final int LAST_SYSTEM = 29;
96    public static final int FIRST_CUSTOM = 8092;
97
98    // Shorthands to set the MediaPlayer's metadata filter.
99    public static final Set<Integer> MATCH_NONE = Collections.EMPTY_SET;
100    public static final Set<Integer> MATCH_ALL = Collections.singleton(ANY);
101
102    /**
103     * Helper class to hold a pair (time, text). Can be used to implement caption.
104     */
105    public class TimedText {
106        private Date mTime;
107        private String mText;
108        public TimedText(final Date time, final String text) {
109            mTime = time;
110            mText = text;
111        }
112        public String toString() {
113            StringBuilder res = new StringBuilder(80);
114            res.append(mTime).append(":").append(mText);
115            return res.toString();
116        }
117    }
118
119    /* package */ Metadata() {}
120
121    /**
122     * @return the number of element in this metadata set.
123     */
124    public int size() {
125        // FIXME: Implement.
126        return 0;
127    }
128
129    /**
130     * @return an iterator over the keys.
131     */
132    public Iterator<Integer> iterator() {
133        // FIXME: Implement.
134        return new java.util.HashSet<Integer>().iterator();
135    }
136
137    /**
138     * @return true if a value is present for the given key.
139     */
140    public boolean has(final int key) {
141        if (key <= ANY) {
142            throw new IllegalArgumentException("Invalid key: " + key);
143        }
144        if (LAST_SYSTEM <= key && key < FIRST_CUSTOM) {
145            throw new IllegalArgumentException("Key in reserved range: " + key);
146        }
147        // FIXME: Implement.
148        return true;
149    }
150
151    // Accessors
152    public String getString(final int key) {
153        // FIXME: Implement.
154        return new String();
155    }
156
157    public int getInt(final int key) {
158        // FIXME: Implement.
159        return 0;
160    }
161
162    public long getLong(final int key) {
163        // FIXME: Implement.
164        return 0;
165    }
166
167    public double getDouble(final int key) {
168        // FIXME: Implement.
169        return 0.0;
170    }
171
172    public byte[] getByteArray(final int key) {
173        return new byte[0];
174    }
175
176    public Bitmap getBitmap(final int key) {
177        // FIXME: Implement.
178        return null;
179    }
180
181    public Date getDate(final int key) {
182        // FIXME: Implement.
183        return new Date();
184    }
185
186    public TimedText getTimedText(final int key) {
187        // FIXME: Implement.
188        return new TimedText(new Date(0), "<missing>");
189    }
190}
191