Metadata.java revision b2c693919be966f179080a9ec70a7a82dbf57627 
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                                      // Keep in sync with kAny in MediaPlayerService.cpp
60
61    // TODO: Should we use numbers compatible with the metadata retriever?
62    public static final int TITLE = 1;           // String
63    public static final int COMMENT = 2;         // String
64    public static final int COPYRIGHT = 3;       // String
65    public static final int ALBUM = 4;           // String
66    public static final int ARTIST = 5;          // String
67    public static final int AUTHOR = 6;          // String
68    public static final int COMPOSER = 7;        // String
69    public static final int GENRE = 8;           // String
70    public static final int DATE = 9;            // Date
71    public static final int DURATION = 10;       // Integer(millisec)
72    public static final int CD_TRACK_NUM = 11;   // Integer 1-based
73    public static final int CD_TRACK_MAX = 12;   // Integer
74    public static final int RATING = 13;         // String
75    public static final int ALBUM_ART = 14;      // byte[]
76    public static final int VIDEO_FRAME = 15;    // Bitmap
77    public static final int CAPTION = 16;        // TimedText
78
79    public static final int BIT_RATE = 17;       // Integer, Aggregate rate of
80                                                 // all the streams in bps.
81
82    public static final int AUDIO_BIT_RATE = 18; // Integer, bps
83    public static final int VIDEO_BIT_RATE = 19; // Integer, bps
84    public static final int AUDIO_SAMPLE_RATE = 20; // Integer, Hz
85    public static final int VIDEO_FRAME_RATE = 21;  // Integer, Hz
86
87    // See RFC2046 and RFC4281.
88    public static final int MIME_TYPE = 22;      // String
89    public static final int AUDIO_CODEC = 23;    // String
90    public static final int VIDEO_CODEC = 24;    // String
91
92    public static final int VIDEO_HEIGHT = 25;   // Integer
93    public static final int VIDEO_WIDTH = 26;    // Integer
94    public static final int NUM_TRACKS = 27;     // Integer
95    public static final int DRM_CRIPPLED = 28;   // Boolean
96    public static final int LAST_SYSTEM = 29;
97    public static final int FIRST_CUSTOM = 8092;
98
99    // Shorthands to set the MediaPlayer's metadata filter.
100    public static final Set<Integer> MATCH_NONE = Collections.EMPTY_SET;
101    public static final Set<Integer> MATCH_ALL = Collections.singleton(ANY);
102
103    /**
104     * Helper class to hold a pair (time, text). Can be used to implement caption.
105     */
106    public class TimedText {
107        private Date mTime;
108        private String mText;
109        public TimedText(final Date time, final String text) {
110            mTime = time;
111            mText = text;
112        }
113        public String toString() {
114            StringBuilder res = new StringBuilder(80);
115            res.append(mTime).append(":").append(mText);
116            return res.toString();
117        }
118    }
119
120    /* package */ Metadata() {}
121
122    /**
123     * @return the number of element in this metadata set.
124     */
125    public int size() {
126        // FIXME: Implement.
127        return 0;
128    }
129
130    /**
131     * @return an iterator over the keys.
132     */
133    public Iterator<Integer> iterator() {
134        // FIXME: Implement.
135        return new java.util.HashSet<Integer>().iterator();
136    }
137
138    /**
139     * @return true if a value is present for the given key.
140     */
141    public boolean has(final int key) {
142        if (key <= ANY) {
143            throw new IllegalArgumentException("Invalid key: " + key);
144        }
145        if (LAST_SYSTEM <= key && key < FIRST_CUSTOM) {
146            throw new IllegalArgumentException("Key in reserved range: " + key);
147        }
148        // FIXME: Implement.
149        return true;
150    }
151
152    // Accessors
153    public String getString(final int key) {
154        // FIXME: Implement.
155        return new String();
156    }
157
158    public int getInt(final int key) {
159        // FIXME: Implement.
160        return 0;
161    }
162
163    public long getLong(final int key) {
164        // FIXME: Implement.
165        return 0;
166    }
167
168    public double getDouble(final int key) {
169        // FIXME: Implement.
170        return 0.0;
171    }
172
173    public byte[] getByteArray(final int key) {
174        return new byte[0];
175    }
176
177    public Bitmap getBitmap(final int key) {
178        // FIXME: Implement.
179        return null;
180    }
181
182    public Date getDate(final int key) {
183        // FIXME: Implement.
184        return new Date();
185    }
186
187    public TimedText getTimedText(final int key) {
188        // FIXME: Implement.
189        return new TimedText(new Date(0), "<missing>");
190    }
191}
192