docs: specify possibility of a NULL return

[platform/upstream/gstreamer.git] / subprojects / gstreamer / gst / gstbuffer.h

diff --git a/subprojects/gstreamer/gst/gstbuffer.h b/subprojects/gstreamer/gst/gstbuffer.h
index ee352d9..6a8b84f 100644 (file)
--- a/subprojects/gstreamer/gst/gstbuffer.h
+++ b/subprojects/gstreamer/gst/gstbuffer.h
@@ -198,7 +198,9 @@ typedef struct _GstBufferPool GstBufferPool;
  * @GST_BUFFER_FLAG_CORRUPTED:     the buffer data is corrupted.
  * @GST_BUFFER_FLAG_MARKER:        the buffer contains a media specific marker. for
  *                                 video this is the end of a frame boundary, for audio
- *                                 this is the start of a talkspurt.
+ *                                 this is the start of a talkspurt. for RTP
+ *                                 packets this matches the marker flag in the
+ *                                 RTP packet header.
  * @GST_BUFFER_FLAG_HEADER:        the buffer contains header information that is
  *                                 needed to decode the following data.
  * @GST_BUFFER_FLAG_GAP:           the buffer has been created to fill a gap in the
@@ -565,8 +567,8 @@ gboolean        gst_buffer_copy_into            (GstBuffer *dest, GstBuffer *src
  * that it returns. Don't access the argument after calling this function unless
  * you have an additional reference to it.
  *
- * Returns: (transfer full): a writable buffer which may or may not be the
- *     same as @buf
+ * Returns: (transfer full) (nullable): a writable buffer (which may or may not be the
+ *     same as @buf) or %NULL if copying is required but not possible.
  */
 #define         gst_buffer_make_writable(buf)   GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf)))
 
@@ -748,10 +750,18 @@ typedef struct _GstReferenceTimestampMeta GstReferenceTimestampMeta;
  * captured.
  *
  * The reference is stored as a #GstCaps in @reference. Examples of valid
- * references would be `timestamp/x-drivername-stream` for timestamps that are locally
- * generated by some driver named `drivername` when generating the stream,
- * e.g. based on a frame counter, or `timestamp/x-ntp, host=pool.ntp.org,
- * port=123` for timestamps based on a specific NTP server.
+ * references would be
+ *
+ *  * `timestamp/x-drivername-stream`: for timestamps that are locally
+ *    generated by some driver named `drivername` when generating the stream,
+ *    e.g. based on a frame counter
+ *  * `timestamp/x-ntp, host=pool.ntp.org, port=123`: for timestamps based on a
+ *    specific NTP server. Note that the host/port parameters might not always
+ *    be given.
+ *  * `timestamp/x-ptp, version=IEEE1588-2008, domain=1`: for timestamps based
+ *    on a given PTP clock.
+ *  * `timestamp/x-unix`: for timestamps based on the UNIX epoch according to
+ *    the local clock.
  *
  * Since: 1.14
  */
@@ -788,6 +798,42 @@ G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBuffer, gst_buffer_unref)
 
 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBufferPool, gst_object_unref)
 
+/**
+ * GstBufferMapInfo: (skip):
+ *
+ * Alias for #GstMapInfo to be used with g_auto():
+ * ```c
+ * void my_func(GstBuffer *buf)
+ * {
+ *   g_auto(GstBufferMapInfo) map = GST_MAP_INFO_INIT;
+ *   if (!gst_buffer_map(buf, &map, GST_MAP_READWRITE))
+ *     return;
+ *   ...
+ *   // No need to call gst_buffer_unmap()
+ * }
+ * ```
+ *
+ * #GstMapInfo cannot be used with g_auto() because it is ambiguous whether it
+ * needs to be unmapped using gst_buffer_unmap() or gst_memory_unmap().
+ *
+ * See also #GstMemoryMapInfo.
+ *
+ * Since: 1.22
+ */
+typedef GstMapInfo GstBufferMapInfo;
+
+static inline void _gst_buffer_map_info_clear(GstBufferMapInfo *info)
+{
+  /* we need to check for NULL, it is possible that we tried to map a buffer
+   * without memory and we should be able to unmap that fine */
+  if (G_LIKELY (info->memory)) {
+    gst_memory_unmap (info->memory, info);
+    gst_memory_unref (info->memory);
+  }
+}
+
+G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GstBufferMapInfo, _gst_buffer_map_info_clear)
+
 G_END_DECLS
 
 #endif /* __GST_BUFFER_H__ */