gst-libs/gst/tag/gsttagdemux.h

   1 /* GStreamer Base Class for Tag Demuxing
   2  * Copyright (C) 2005  Jan Schmidt <thaytan@mad.scientist.com>
   3  * Copyright (C) 2006  Tim-Philipp Müller <tim centricular net>
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  18  * Boston, MA 02110-1301, USA.
  19  */
  20
  21 #ifndef __GST_TAG_DEMUX_H__
  22 #define __GST_TAG_DEMUX_H__
  23
  24 #include <gst/gst.h>
  25
  26 G_BEGIN_DECLS
  27
  28 #define GST_TYPE_TAG_DEMUX            (gst_tag_demux_get_type())
  29 #define GST_TAG_DEMUX(obj)            (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_TAG_DEMUX,GstTagDemux))
  30 #define GST_TAG_DEMUX_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_TAG_DEMUX,GstTagDemuxClass))
  31 #define GST_IS_TAG_DEMUX(obj)         (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_TAG_DEMUX))
  32 #define GST_IS_TAG_DEMUX_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_TAG_DEMUX))
  33
  34 typedef struct _GstTagDemux        GstTagDemux;
  35 typedef struct _GstTagDemuxClass   GstTagDemuxClass;
  36 typedef struct _GstTagDemuxPrivate GstTagDemuxPrivate;
  37
  38 /**
  39  * GstTagDemuxResult:
  40  * @GST_TAG_DEMUX_RESULT_BROKEN_TAG: cannot parse tag, just skip it
  41  * @GST_TAG_DEMUX_RESULT_AGAIN     : call again with less or more data
  42  * @GST_TAG_DEMUX_RESULT_OK        : parsed tag successfully
  43  *
  44  * Result values from the parse_tag virtual function.
  45  */
  46 typedef enum {
  47   GST_TAG_DEMUX_RESULT_BROKEN_TAG,
  48   GST_TAG_DEMUX_RESULT_AGAIN,
  49   GST_TAG_DEMUX_RESULT_OK
  50 } GstTagDemuxResult;
  51
  52 GType gst_tag_demux_result_get_type (void);
  53 #define GST_TYPE_TAG_DEMUX_RESULT (gst_tag_demux_result_get_type())
  54
  55 /**
  56  * GstTagDemux:
  57  * @element: parent element
  58  *
  59  * Opaque #GstTagDemux structure.
  60  */
  61 struct _GstTagDemux
  62 {
  63   GstElement element;
  64
  65   /*< private >*/
  66   GstTagDemuxPrivate  *priv;
  67
  68   gpointer             reserved[GST_PADDING];
  69 };
  70
  71 /**
  72  * GstTagDemuxClass:
  73  * @parent_class: the parent class.
  74  * @min_start_size: minimum size required to identify a tag at the start and
  75  * determine its total size. Set to 0 if not interested in start tags.
  76  * Subclasses should set this in their class_init function.
  77  * @min_end_size: minimum size required to identify a tag at the end and
  78  * determine its total size. Set to 0 if not interested in end tags.
  79  * Subclasses should set this in their class_init function.
  80  * @identify_tag: identify tag and determine the size required to parse the
  81  * tag. Buffer may be larger than the specified minimum size.
  82  * Subclassed MUST override this vfunc in their class_init function.
  83  * @parse_tag: parse the tag. Buffer will be exactly of the size determined by
  84  * the identify_tag vfunc before. The parse_tag vfunc may change the size
  85  * stored in *tag_size and return GST_TAG_DEMUX_RESULT_AGAIN to request a
  86  * larger or smaller buffer. It is also permitted to adjust the tag_size to a
  87  * smaller value and then return GST_TAG_DEMUX_RESULT_OK in one go.
  88  * Subclassed MUST override the parse_tag vfunc in their class_init function.
  89  * @merge_tags: merge start and end tags. Subclasses may want to override this
  90  * vfunc to allow prioritising of start or end tag according to user
  91  * preference.  Note that both start_tags and end_tags may be NULL. By default
  92  * start tags are prefered over end tags.
  93  *
  94  * The #GstTagDemuxClass structure.  See documentation at beginning of section
  95  * for details about what subclasses need to override and do.
  96  */
  97 struct _GstTagDemuxClass
  98 {
  99   GstElementClass parent_class;
 100
 101   /* minimum size required to identify a tag at the start and determine
 102    * its total size */
 103   guint                  min_start_size;
 104
 105   /* minimum size required to identify a tag at the end and determine
 106    * its total size */
 107   guint                  min_end_size;
 108
 109   /* vtable */
 110
 111   /* identify tag and determine the size required to parse the tag */
 112   gboolean               (*identify_tag)  (GstTagDemux * demux,
 113                                            GstBuffer   * buffer,
 114                                            gboolean      start_tag,
 115                                            guint       * tag_size);
 116
 117   /* parse the tag once it is identified and its size is known */
 118   GstTagDemuxResult      (*parse_tag)     (GstTagDemux * demux,
 119                                            GstBuffer   * buffer,
 120                                            gboolean      start_tag,
 121                                            guint       * tag_size,
 122                                            GstTagList ** tags);
 123
 124   /* merge start and end tags (optional) */
 125   GstTagList *           (*merge_tags)    (GstTagDemux      * demux,
 126                                            const GstTagList * start_tags,
 127                                            const GstTagList * end_tags);
 128
 129   /*< private >*/
 130   gpointer               reserved[GST_PADDING];
 131 };
 132
 133 GType     gst_tag_demux_get_type (void);
 134
 135 G_END_DECLS
 136
 137 #endif /* __GST_TAG_DEMUX_H__ */
 138