gst/gstpromise.h

   1 /* GStreamer
   2  * Copyright (C) 2017 Matthew Waters <matthew@centricular.com>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  17  * Boston, MA 02110-1301, USA.
  18  */
  19
  20 #ifndef __GST_PROMISE_H__
  21 #define __GST_PROMISE_H__
  22
  23 #include <gst/gst.h>
  24
  25 G_BEGIN_DECLS
  26
  27 GST_EXPORT
  28 GType gst_promise_get_type(void);
  29 #define GST_TYPE_PROMISE            (gst_promise_get_type())
  30 #define GST_PROMISE(obj)            ((GstPromise *) obj)
  31
  32 typedef struct _GstPromise GstPromise;
  33
  34 /**
  35  * GstPromiseResult:
  36  * @GST_PROMISE_RESULT_PENDING: Initial state. Waiting for transition to any
  37  *      other state.
  38  * @GST_PROMISE_RESULT_INTERRUPTED: Interrupted by the consumer as it doesn't
  39  *      want the value anymore.
  40  * @GST_PROMISE_RESULT_REPLIED: A producer marked a reply
  41  * @GST_PROMISE_RESULT_EXPIRED: The promise expired (the carrying object
  42  *      lost all refs) and the promise will never be fulfilled.
  43  *
  44  * The result of a #GstPromise
  45  */
  46 typedef enum
  47 {
  48   GST_PROMISE_RESULT_PENDING,
  49   GST_PROMISE_RESULT_INTERRUPTED,
  50   GST_PROMISE_RESULT_REPLIED,
  51   GST_PROMISE_RESULT_EXPIRED,
  52 } GstPromiseResult;
  53
  54 /**
  55  * GstPromiseChangeFunc:
  56  * @promise: a #GstPromise
  57  * @user_data: (closure): user data
  58  */
  59 typedef void (*GstPromiseChangeFunc) (GstPromise * promise, gpointer user_data);
  60
  61 /**
  62  * GstPromise:
  63  * @parent: parent #GstMiniObject
  64  */
  65 struct _GstPromise
  66 {
  67   GstMiniObject         parent;
  68 };
  69
  70 GST_EXPORT
  71 GstPromise *            gst_promise_new                     (void);
  72 GST_EXPORT
  73 GstPromise *            gst_promise_new_with_change_func    (GstPromiseChangeFunc func,
  74                                                              gpointer user_data,
  75                                                              GDestroyNotify notify);
  76
  77 GST_EXPORT
  78 GstPromiseResult        gst_promise_wait                    (GstPromise * promise);
  79 GST_EXPORT
  80 void                    gst_promise_reply                   (GstPromise * promise,
  81                                                              GstStructure * s);
  82 GST_EXPORT
  83 void                    gst_promise_interrupt               (GstPromise * promise);
  84 GST_EXPORT
  85 void                    gst_promise_expire                  (GstPromise * promise);
  86
  87 GST_EXPORT
  88 const GstStructure *    gst_promise_get_reply               (GstPromise * promise);
  89
  90 /**
  91  * gst_promise_ref:
  92  * @promise: a #GstPromise.
  93  *
  94  * Increases the refcount of the given @promise by one.
  95  *
  96  * Returns: (transfer full): @promise
  97  */
  98 static inline GstPromise *
  99 gst_promise_ref (GstPromise * promise)
 100 {
 101   return (GstPromise *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (promise));
 102 }
 103
 104 /**
 105  * gst_promise_unref:
 106  * @promise: (transfer full): a #GstPromise.
 107  *
 108  * Decreases the refcount of the promise. If the refcount reaches 0, the
 109  * promise will be freed.
 110  */
 111 static inline void
 112 gst_promise_unref (GstPromise * promise)
 113 {
 114   gst_mini_object_unref (GST_MINI_OBJECT_CAST (promise));
 115 }
 116
 117 G_END_DECLS
 118
 119 #endif /* __GST_PROMISE_H__ */