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