3
* Copyright 2007 Edgard Lima <edgard.lima@indt.org.br>
5
* Permission is hereby granted, free of charge, to any person obtaining a
6
* copy of this software and associated documentation files (the "Software"),
7
* to deal in the Software without restriction, including without limitation
8
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
9
* and/or sell copies of the Software, and to permit persons to whom the
10
* Software is furnished to do so, subject to the following conditions:
12
* The above copyright notice and this permission notice shall be included in
13
* all copies or substantial portions of the Software.
15
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21
* DEALINGS IN THE SOFTWARE.
23
* Alternatively, the contents of this file may be used under the
24
* GNU Lesser General Public License Version 2.1 (the "LGPL"), in
25
* which case the following provisions apply instead of the ones
28
* This library is free software; you can redistribute it and/or
29
* modify it under the terms of the GNU Library General Public
30
* License as published by the Free Software Foundation; either
31
* version 2 of the License, or (at your option) any later version.
33
* This library is distributed in the hope that it will be useful,
34
* but WITHOUT ANY WARRANTY; without even the implied warranty of
35
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
36
* Library General Public License for more details.
38
* You should have received a copy of the GNU Library General Public
39
* License along with this library; if not, write to the
40
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
41
* Boston, MA 02111-1307, USA.
46
* @short_description: This module provides high-level functions to parse files
48
* This module find out the stream type (JPEG or PNG), and provide functions to
49
* the caller to know where are the metadata chunks and where should it be
50
* written, as well, it gives the caller the metedata chunk to be written and
51
* also gets a metadata chunk and wraps it according the strem type
56
* #metadata_init must be called before any other function in this module and
57
* must be paired with a call to #metadata_dispose. #metadata_parse is used to
58
* parse the stream (find the metadata chunks and the place it should be
59
* written to. And #metadata_lazy_update is used by muxers to wrap the metadata
60
* chunk according the stream type specification. Actually after indentify the
61
* stream type, the real jog of parsing is delivered to speciallized module.
62
* See, #metadata[mux/parse][jpeg/png].[c/h] files.
66
* Last reviewed on 2008-01-24 (0.10.15)
78
* static helper functions declaration
81
static MetadataParsingReturn
82
metadata_parse_none (MetaData * meta_data, const guint8 * data,
83
guint32 * data_size, guint8 ** next_start, guint32 * next_size);
86
* extern functions implementations
91
* @meta_data: [in] metadata handler to be inited
92
* @options: [in] which types of metadata will be processed (EXIF, IPTC and/or
93
* XMP) and how it will be handled (DEMUXING or MUXING). Look at #MetaOptions
94
* to see the available options.
96
* Init metadata handle.
97
* This function must be called before any other function from this module.
98
* This function must not be called twice without call to #metadata_dispose
100
* @see_also: #metadata_dispose #metadata_parse
106
metadata_init (MetaData ** meta_data, const MetaOptions options)
109
if (meta_data == NULL)
112
metadata_dispose (meta_data);
114
(*meta_data) = g_new (MetaData, 1);
116
(*meta_data)->state = STATE_NULL;
117
(*meta_data)->img_type = IMG_NONE;
118
(*meta_data)->options = options;
119
(*meta_data)->offset_orig = 0;
120
(*meta_data)->exif_adapter = NULL;
121
(*meta_data)->iptc_adapter = NULL;
122
(*meta_data)->xmp_adapter = NULL;
124
if ((*meta_data)->options & META_OPT_DEMUX) {
125
/* when parsing we will probably strip only 3 chunk (exif, iptc and xmp)
126
so we use 4 just in case there is more than one chunk of them.
127
But this is just for convinience, 'cause the chunk_array increases
129
metadata_chunk_array_init (&(*meta_data)->strip_chunks, 4);
130
/* at most 1 chunk will be injected (JPEG JFIF) */
131
metadata_chunk_array_init (&(*meta_data)->inject_chunks, 1);
133
/* at most 1 chunk will be striped (JPEG JFIF) */
134
metadata_chunk_array_init (&(*meta_data)->strip_chunks, 1);
135
/* at most 3 chunk will be injected (EXIF, IPTC, XMP) */
136
metadata_chunk_array_init (&(*meta_data)->inject_chunks, 3);
143
* @meta_data: [in] metadata handler to be freed
145
* Call this function to free any resource allocated by #metadata_init
146
* @see_also: #metadata_init
152
metadata_dispose (MetaData ** meta_data)
155
if (meta_data == NULL || (*meta_data) == NULL)
158
switch ((*meta_data)->img_type) {
160
if (G_LIKELY ((*meta_data)->options & META_OPT_DEMUX))
161
metadataparse_jpeg_dispose (&(*meta_data)->format_data.jpeg_parse);
163
metadatamux_jpeg_dispose (&(*meta_data)->format_data.jpeg_mux);
166
if (G_LIKELY ((*meta_data)->options & META_OPT_DEMUX))
167
metadataparse_png_dispose (&(*meta_data)->format_data.png_parse);
169
metadatamux_png_dispose (&(*meta_data)->format_data.png_mux);
176
metadata_chunk_array_free (&(*meta_data)->strip_chunks);
177
metadata_chunk_array_free (&(*meta_data)->inject_chunks);
179
if ((*meta_data)->xmp_adapter) {
180
gst_object_unref ((*meta_data)->xmp_adapter);
181
(*meta_data)->xmp_adapter = NULL;
184
if ((*meta_data)->iptc_adapter) {
185
gst_object_unref ((*meta_data)->iptc_adapter);
186
(*meta_data)->iptc_adapter = NULL;
189
if ((*meta_data)->exif_adapter) {
190
gst_object_unref ((*meta_data)->exif_adapter);
191
(*meta_data)->exif_adapter = NULL;
202
* @meta_data: [in] metadata handle
203
* @buf: [in] data to be parsed
204
* @buf_size: [in] size of @buf in bytes
205
* @next_offset: [out] number of bytes to jump from the begining of @buf in
206
* the next call. i.e, 0 (zero) mean that in the next call this function @buf
207
* must have the same data (probably resized, see @next_size)
208
* @next_size: [out] number of minimal bytes in @buf for the next call to this
211
* This function is used to parse the stream step-by-step incrementaly, which
212
* means, discover the stream type and find the metadata chunks
213
* (#META_OPT_DEMUX), or point out where metadata chunks should be written
214
* (#META_OPT_MUX). It is important to notice that there could be both strip
215
* and inject chunks in both demuxing and muxing modes.
216
* @see_also: #metadata_init #META_DATA_STRIP_CHUNKS #META_DATA_INJECT_CHUNKS
220
* <listitem><para>%META_PARSING_ERROR
222
* <listitem><para>%META_PARSING_DONE if parse has finished. Now strip and
223
* inject chunks has been found
225
* <listitem><para>%META_PARSING_NEED_MORE_DATA if this function should be
226
* called again (look @next_offset and @next_size)
231
MetadataParsingReturn
232
metadata_parse (MetaData * meta_data, const guint8 * buf,
233
guint32 buf_size, guint32 * next_offset, guint32 * next_size)
236
int ret = META_PARSING_DONE;
238
guint8 *next_start = (guint8 *) buf;
240
if (meta_data->state == STATE_NULL) {
242
metadata_parse_none (meta_data, buf, &buf_size, &next_start, next_size);
243
if (ret == META_PARSING_DONE)
244
meta_data->state = STATE_READING;
249
switch (meta_data->img_type) {
251
if (G_LIKELY (meta_data->options & META_OPT_DEMUX))
253
metadataparse_jpeg_parse (&meta_data->format_data.jpeg_parse,
254
(guint8 *) buf, &buf_size, meta_data->offset_orig, &next_start,
258
metadatamux_jpeg_parse (&meta_data->format_data.jpeg_mux,
259
(guint8 *) buf, &buf_size, meta_data->offset_orig, &next_start,
263
if (G_LIKELY (meta_data->options & META_OPT_DEMUX))
265
metadataparse_png_parse (&meta_data->format_data.png_parse,
266
(guint8 *) buf, &buf_size, meta_data->offset_orig, &next_start,
270
metadatamux_png_parse (&meta_data->format_data.png_mux,
271
(guint8 *) buf, &buf_size, meta_data->offset_orig, &next_start,
276
ret = META_PARSING_ERROR;
281
*next_offset = next_start - buf;
282
meta_data->offset_orig += *next_offset;
286
if (ret == META_PARSING_DONE) {
287
meta_data->state = STATE_DONE;
294
* metadata_lazy_update:
295
* @meta_data: [in] metata handle
297
* This function must be called after #metadata_parse and after the element
298
* has modified the segments (chunks)
299
* Data written to #META_DATA_INJECT_CHUNKS will be properly wrapped
300
* This function is really importante in case o muxing 'cause:
301
* 1- 'cause gives the oportunity to muxers to wrapper new segments with
303
* ex: in case of JPEG it can wrap the EXIF chunk (created using tags) with
304
* chunk id and chunk size
305
* 2- 'cause gives the oportunity to muxer to decide if some chunks should
306
* still be striped/injected
307
* ex: if there is no EXIF chunk to be inserted, the muxer decides to not
309
* @see_also: #metadata_parse #META_DATA_INJECT_CHUNKS
315
metadata_lazy_update (MetaData * meta_data)
317
switch (meta_data->img_type) {
319
if (G_LIKELY (meta_data->options & META_OPT_DEMUX))
320
metadataparse_jpeg_lazy_update (&meta_data->format_data.jpeg_parse);
322
metadatamux_jpeg_lazy_update (&meta_data->format_data.jpeg_mux);
325
if (G_LIKELY (meta_data->options & META_OPT_DEMUX))
326
metadataparse_png_lazy_update (&meta_data->format_data.png_parse);
328
metadatamux_png_lazy_update (&meta_data->format_data.png_mux);
339
* static helper functions implementation
343
* metadata_parse_none:
344
* @meta_data: [in] metata handle
345
* @buf: [in] data to be parsed
346
* @buf_size: [in] size of @buf in bytes
347
* @next_offset: [out] number of bytes to jump from the begining of @buf in
348
* the next call. i.e, 0 (zero) mean that in the next call this function @buf
349
* must have the same data (probably resized, see @next_size)
350
* @next_size: [out] number of minimal bytes in @buf for the next call to this
353
* Parse the fisrt bytes of the stream to identify the stream type
354
* @see_also: metadata_parse
358
* <listitem><para>%META_PARSING_ERROR none of the alloed strem types (JPEG,
359
* PNG) has been identified
361
* <listitem><para>%META_PARSING_DONE if the stream type has been identified
363
* <listitem><para>%META_PARSING_NEED_MORE_DATA if this function should be
364
* called again (look @next_offset and @next_size)
368
static MetadataParsingReturn
369
metadata_parse_none (MetaData * meta_data, const guint8 * buf,
370
guint32 * buf_size, guint8 ** next_start, guint32 * next_size)
373
int ret = META_PARSING_ERROR;
374
GstAdapter **exif = NULL;
375
GstAdapter **iptc = NULL;
376
GstAdapter **xmp = NULL;
378
*next_start = (guint8 *) buf;
380
meta_data->img_type = IMG_NONE;
383
* Be sure of add checking for more types in order from the
384
* less to more bytes need to detect the stream type.
387
/* we need at least 3 bytes to see if it is JPEG */
390
ret = META_PARSING_NEED_MORE_DATA;
394
if (meta_data->options & META_OPT_EXIF)
395
exif = &meta_data->exif_adapter;
396
if (meta_data->options & META_OPT_IPTC)
397
iptc = &meta_data->iptc_adapter;
398
if (meta_data->options & META_OPT_XMP)
399
xmp = &meta_data->xmp_adapter;
401
if (buf[0] == 0xFF && buf[1] == 0xD8 && buf[2] == 0xFF) {
402
if (G_LIKELY (meta_data->options & META_OPT_DEMUX))
403
metadataparse_jpeg_init (&meta_data->format_data.jpeg_parse, exif, iptc,
404
xmp, &meta_data->strip_chunks, &meta_data->inject_chunks,
405
meta_data->options & META_OPT_PARSE_ONLY);
407
metadatamux_jpeg_init (&meta_data->format_data.jpeg_mux,
408
&meta_data->strip_chunks, &meta_data->inject_chunks);
409
ret = META_PARSING_DONE;
410
meta_data->img_type = IMG_JPEG;
414
/* we need at least 8 bytes to see if it is PNG */
417
ret = META_PARSING_NEED_MORE_DATA;
421
if (buf[0] == 0x89 && buf[1] == 0x50 && buf[2] == 0x4E && buf[3] == 0x47 &&
422
buf[4] == 0x0D && buf[5] == 0x0A && buf[6] == 0x1A && buf[7] == 0x0A) {
423
if (G_LIKELY (meta_data->options & META_OPT_DEMUX))
424
metadataparse_png_init (&meta_data->format_data.png_parse, exif, iptc,
425
xmp, &meta_data->strip_chunks, &meta_data->inject_chunks,
426
meta_data->options & META_OPT_PARSE_ONLY);
428
metadatamux_png_init (&meta_data->format_data.png_mux,
429
&meta_data->strip_chunks, &meta_data->inject_chunks);
430
ret = META_PARSING_DONE;
431
meta_data->img_type = IMG_PNG;