Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/3194>
*
* Creates Opus caps from the given parameters.
*
- * Returns: The #GstCaps, or %NULL if the parameters would lead to
+ * Returns: (transfer full) (nullable): The #GstCaps, or %NULL if the parameters would lead to
* invalid Opus caps.
*
* Since: 1.8
* Creates Opus caps from the given OpusHead @header and comment header
* @comments.
*
- * Returns: The #GstCaps.
+ * Returns: (transfer full) (nullable): The #GstCaps.
*
* Since: 1.8
*/
*
* Creates OpusHead header from the given parameters.
*
- * Returns: The #GstBuffer containing the OpusHead.
+ * Returns: (transfer full) (nullable): The #GstBuffer containing the OpusHead.
*
* Since: 1.8
*/
*
* Returns a localised string describing a source element handling the protocol
* specified in @protocol, for use in error dialogs or other messages to be
- * seen by the user. Should never return NULL unless @protocol is invalid.
+ * seen by the user.
*
* This function is mainly for internal use, applications would typically
* use gst_missing_plugin_message_get_description() to get a description of
* a missing feature from a missing-plugin message.
*
- * Returns: a newly-allocated description string, or NULL on error. Free
+ * Returns: a newly-allocated description string. Free
* string with g_free() when not needed any longer.
*/
gchar *
*
* Returns a localised string describing a sink element handling the protocol
* specified in @protocol, for use in error dialogs or other messages to be
- * seen by the user. Should never return NULL unless @protocol is invalid.
+ * seen by the user.
*
* This function is mainly for internal use, applications would typically
* use gst_missing_plugin_message_get_description() to get a description of
* a missing feature from a missing-plugin message.
*
- * Returns: a newly-allocated description string, or NULL on error. Free
+ * Returns: a newly-allocated description string. Free
* string with g_free() when not needed any longer.
*/
gchar *
*
* Returns a localised string describing an decoder for the format specified
* in @caps, for use in error dialogs or other messages to be seen by the user.
- * Should never return NULL unless @factory_name or @caps are invalid.
*
* This function is mainly for internal use, applications would typically
* use gst_missing_plugin_message_get_description() to get a description of
* a missing feature from a missing-plugin message.
*
- * Returns: a newly-allocated description string, or NULL on error. Free
+ * Returns: a newly-allocated description string. Free
* string with g_free() when not needed any longer.
*/
gchar *
*
* Returns a localised string describing an encoder for the format specified
* in @caps, for use in error dialogs or other messages to be seen by the user.
- * Should never return NULL unless @factory_name or @caps are invalid.
*
* This function is mainly for internal use, applications would typically
* use gst_missing_plugin_message_get_description() to get a description of
* a missing feature from a missing-plugin message.
*
- * Returns: a newly-allocated description string, or NULL on error. Free
+ * Returns: a newly-allocated description string. Free
* string with g_free() when not needed any longer.
*/
gchar *
* @factory_name: the name of the element, e.g. "giosrc"
*
* Returns a localised string describing the given element, for use in
- * error dialogs or other messages to be seen by the user. Should never
- * return NULL unless @factory_name is invalid.
+ * error dialogs or other messages to be seen by the user.
*
* This function is mainly for internal use, applications would typically
* use gst_missing_plugin_message_get_description() to get a description of
* a missing feature from a missing-plugin message.
*
- * Returns: a newly-allocated description string, or NULL on error. Free
+ * Returns: a newly-allocated description string. Free
* string with g_free() when not needed any longer.
*/
gchar *
/**
* gst_pb_utils_add_codec_description_to_tag_list:
* @taglist: a #GstTagList
- * @codec_tag: (allow-none): a GStreamer codec tag such as #GST_TAG_AUDIO_CODEC,
+ * @codec_tag: (nullable): a GStreamer codec tag such as #GST_TAG_AUDIO_CODEC,
* #GST_TAG_VIDEO_CODEC or #GST_TAG_CODEC. If none is specified,
* the function will attempt to detect the appropriate category.
* @caps: the (fixed) #GstCaps for which a codec tag should be added.
* Also see the convenience function
* gst_pb_utils_add_codec_description_to_tag_list().
*
- * Returns: a newly-allocated description string, or NULL on error. Free
+ * Returns: (nullable): a newly-allocated description string, or NULL on error. Free
* string with g_free() when not needed any longer.
*/
gchar *
gchar *
gst_pb_utils_get_file_extension_from_caps (const GstCaps * caps)
{
- return g_strdup (pb_utils_get_file_extension_from_caps (caps));
+ const gchar *extension = pb_utils_get_file_extension_from_caps (caps);
+ return extension ? g_strdup (extension) : NULL;
}
/**
* gst_encoding_profile_get_name:
* @profile: a #GstEncodingProfile
*
- * Returns: the name of the profile, can be %NULL.
+ * Returns: (nullable): the name of the profile, can be %NULL.
*/
const gchar *
gst_encoding_profile_get_name (GstEncodingProfile * profile)
* gst_encoding_profile_get_description:
* @profile: a #GstEncodingProfile
*
- * Returns: the description of the profile, can be %NULL.
+ * Returns: (nullable): the description of the profile, can be %NULL.
*/
const gchar *
gst_encoding_profile_get_description (GstEncodingProfile * profile)
* gst_encoding_profile_get_format:
* @profile: a #GstEncodingProfile
*
- * Returns: (transfer full): the #GstCaps corresponding to the media format used
+ * Returns: (transfer full): (nullable): the #GstCaps corresponding to the media format used
* in the profile. Unref after usage.
*/
GstCaps *
* gst_encoding_profile_get_preset:
* @profile: a #GstEncodingProfile
*
- * Returns: the name of the #GstPreset to be used in the profile.
+ * Returns: (nullable): the name of the #GstPreset to be used in the profile.
* This is the name that has been set when saving the preset.
*/
const gchar *
* gst_encoding_profile_get_preset_name:
* @profile: a #GstEncodingProfile
*
- * Returns: the name of the #GstPreset factory to be used in the profile.
+ * Returns: (nullable): the name of the #GstPreset factory to be used in the profile.
*/
const gchar *
gst_encoding_profile_get_preset_name (GstEncodingProfile * profile)
* gst_encoding_profile_get_restriction:
* @profile: a #GstEncodingProfile
*
- * Returns: (transfer full): The restriction #GstCaps to apply before the encoder
+ * Returns: (transfer full) (nullable): The restriction #GstCaps to apply before the encoder
* that will be used in the profile. The fields present in restriction caps are
* properties of the raw stream (that is before encoding), such as height and
* width for video and depth and sampling rate for audio. Does not apply to
/**
* gst_encoding_profile_set_name:
* @profile: a #GstEncodingProfile
- * @name: (allow-none): the name to set on the profile
+ * @name: (nullable): the name to set on the profile
*
* Set @name as the given name for the @profile. A copy of @name will be made
* internally.
/**
* gst_encoding_profile_set_description:
* @profile: a #GstEncodingProfile
- * @description: (allow-none): the description to set on the profile
+ * @description: (nullable): the description to set on the profile
*
* Set @description as the given description for the @profile. A copy of
* @description will be made internally.
/**
* gst_encoding_profile_set_preset_name:
* @profile: a #GstEncodingProfile
- * @preset_name: (allow-none): The name of the preset to use in this @profile.
+ * @preset_name: (nullable): The name of the preset to use in this @profile.
*
* Sets the name of the #GstPreset's factory to be used in the profile.
*/
/**
* gst_encoding_profile_set_restriction:
* @profile: a #GstEncodingProfile
- * @restriction: (allow-none) (transfer full): the restriction to apply
+ * @restriction: (nullable) (transfer full): the restriction to apply
*
* Set the restriction #GstCaps to apply before the encoder
* that will be used in the profile. See gst_encoding_profile_get_restriction()
/**
* gst_encoding_container_profile_new:
- * @name: (allow-none): The name of the container profile, can be %NULL
- * @description: (allow-none): The description of the container profile,
+ * @name: (nullable): The name of the container profile, can be %NULL
+ * @description: (nullable): The description of the container profile,
* can be %NULL
* @format: (transfer none): The format to use for this profile
- * @preset: (allow-none): The preset to use for this profile.
+ * @preset: (nullable): The preset to use for this profile.
*
* Creates a new #GstEncodingContainerProfile.
*
/**
* gst_encoding_video_profile_new:
* @format: (transfer none): the #GstCaps
- * @preset: (allow-none): the preset(s) to use on the encoder, can be %NULL
- * @restriction: (allow-none): the #GstCaps used to restrict the input to the encoder, can be
+ * @preset: (nullable): the preset(s) to use on the encoder, can be %NULL
+ * @restriction: (nullable): the #GstCaps used to restrict the input to the encoder, can be
* NULL. See gst_encoding_profile_get_restriction() for more details.
* @presence: the number of time this stream must be used. 0 means any number of
* times (including never)
/**
* gst_encoding_audio_profile_new:
* @format: (transfer none): the #GstCaps
- * @preset: (allow-none): the preset(s) to use on the encoder, can be %NULL
- * @restriction: (allow-none): the #GstCaps used to restrict the input to the encoder, can be
+ * @preset: (nullable): the preset(s) to use on the encoder, can be %NULL
+ * @restriction: (nullable): the #GstCaps used to restrict the input to the encoder, can be
* NULL. See gst_encoding_profile_get_restriction() for more details.
* @presence: the number of time this stream must be used. 0 means any number of
* times (including never)
return "video";
if (GST_IS_ENCODING_AUDIO_PROFILE (profile))
return "audio";
+
+ g_assert_not_reached ();
return NULL;
}
* gst_encoding_profile_get_file_extension:
* @profile: a #GstEncodingProfile
*
- * Returns: a suitable file extension for @profile, or NULL.
+ * Returns: (nullable): a suitable file extension for @profile, or NULL.
*/
const gchar *
gst_encoding_profile_get_file_extension (GstEncodingProfile * profile)
/**
* gst_encoding_profile_find:
* @targetname: (transfer none): The name of the target
- * @profilename: (transfer none) (allow-none): The name of the profile, if %NULL
+ * @profilename: (transfer none) (nullable): The name of the profile, if %NULL
* provided, it will default to the encoding profile called `default`.
- * @category: (transfer none) (allow-none): The target category. Can be %NULL
+ * @category: (transfer none) (nullable): The target category. Can be %NULL
*
* Find the #GstEncodingProfile with the specified name and category.
*
- * Returns: (transfer full): The matching #GstEncodingProfile or %NULL.
+ * Returns: (transfer full) (nullable): The matching #GstEncodingProfile or %NULL.
*/
GstEncodingProfile *
gst_encoding_profile_find (const gchar * targetname, const gchar * profilename,
* #GstDiscovererInfo. Streams other than audio or video (eg,
* subtitles), are currently ignored.
*
- * Returns: (transfer full): The new #GstEncodingProfile or %NULL.
+ * Returns: (transfer full) (nullable): The new #GstEncodingProfile or %NULL.
*/
GstEncodingProfile *
gst_encoding_profile_from_discoverer (GstDiscovererInfo * info)
* gst_encoding_target_get_path:
* @target: a #GstEncodingTarget
*
- * Returns: (transfer none): The path to the @target file.
+ * Returns: (transfer none) (nullable) (type filename): The path to the @target file.
*
* Since: 1.18
*/
* @target: a #GstEncodingTarget
* @name: the name of the profile to retrieve
*
- * Returns: (transfer full): The matching #GstEncodingProfile, or %NULL.
+ * Returns: (nullable) (transfer full): The matching #GstEncodingProfile, or %NULL.
*/
GstEncodingProfile *
gst_encoding_target_get_profile (GstEncodingTarget * target, const gchar * name)
* *can* be a application or user specific category if
* needed.
*
- * Returns: (transfer full): The newly created #GstEncodingTarget or %NULL if
+ * Returns: (transfer full) (nullable): The newly created #GstEncodingTarget or %NULL if
* there was an error.
*/
* @name: the name of the #GstEncodingTarget to load (automatically
* converted to lower case internally as capital letters are not
* valid for target names).
- * @category: (allow-none): the name of the target category, like
+ * @category: (nullable): the name of the target category, like
* #GST_ENCODING_CATEGORY_DEVICE. Can be %NULL
* @error: If an error occurred, this field will be filled in.
*
/**
* gst_encoding_list_all_targets:
- * @categoryname: (allow-none): The category, for ex: #GST_ENCODING_CATEGORY_DEVICE.
+ * @categoryname: (nullable): The category, for ex: #GST_ENCODING_CATEGORY_DEVICE.
* Can be %NULL.
*
* List all available #GstEncodingTarget for the specified category, or all categories
* gst_discoverer_stream_info_get_previous:
* @info: a #GstDiscovererStreamInfo
*
- * Returns: (transfer full): the previous #GstDiscovererStreamInfo in a chain.
+ * Returns: (transfer full) (nullable): the previous #GstDiscovererStreamInfo in a chain.
* %NULL for starting points. Unref with #gst_discoverer_stream_info_unref
* after usage.
*/
* gst_discoverer_stream_info_get_next:
* @info: a #GstDiscovererStreamInfo
*
- * Returns: (transfer full): the next #GstDiscovererStreamInfo in a chain. %NULL
+ * Returns: (transfer full) (nullable): the next #GstDiscovererStreamInfo in a chain. %NULL
* for final streams.
* Unref with #gst_discoverer_stream_info_unref after usage.
*/
* gst_discoverer_stream_info_get_caps:
* @info: a #GstDiscovererStreamInfo
*
- * Returns: (transfer full): the #GstCaps of the stream. Unref with
+ * Returns: (transfer full) (nullable): the #GstCaps of the stream. Unref with
* #gst_caps_unref after usage.
*/
GstCaps *
* gst_discoverer_stream_info_get_tags:
* @info: a #GstDiscovererStreamInfo
*
- * Returns: (transfer none): the tags contained in this stream. If you wish to
+ * Returns: (transfer none) (nullable): the tags contained in this stream. If you wish to
* use the tags after the life-time of @info you will need to copy them.
*/
const GstTagList *
* gst_discoverer_stream_info_get_toc:
* @info: a #GstDiscovererStreamInfo
*
- * Returns: (transfer none): the TOC contained in this stream. If you wish to
+ * Returns: (transfer none) (nullable): the TOC contained in this stream. If you wish to
* use the TOC after the life-time of @info you will need to copy it.
*/
const GstToc *
* Deprecated: This functions is deprecated since version 1.4, use
* #gst_discoverer_info_get_missing_elements_installer_details
*
- * Returns: (transfer none): additional information regarding the stream (for
+ * Returns: (transfer none) (nullable): additional information regarding the stream (for
* example codec version, profile, etc..). If you wish to use the #GstStructure
* after the life-time of @info you will need to copy it.
*/
* gst_discoverer_container_info_get_tags:
* @info: a #GstDiscovererStreamInfo
*
- * Returns: (transfer none): tags specific to the given container. If you wish to use
+ * Returns: (transfer none) (nullable): tags specific to the given container. If you wish to use
* the tags after the life-time of @info, you will need to copy them.
*
* Since: 1.20
* gst_discoverer_audio_info_get_language:
* @info: a #GstDiscovererAudioInfo
*
- * Returns: the language of the stream, or NULL if unknown.
+ * Returns: (nullable): the language of the stream, or NULL if unknown.
*/
AUDIO_INFO_ACCESSOR_CODE (language, const gchar *, NULL);
* gst_discoverer_subtitle_info_get_language:
* @info: a #GstDiscovererSubtitleInfo
*
- * Returns: the language of the stream, or NULL if unknown.
+ * Returns: (nullable): the language of the stream, or NULL if unknown.
*/
SUBTITLE_INFO_ACCESSOR_CODE (language, const gchar *, NULL);
* gst_discoverer_info_get_stream_info:
* @info: a #GstDiscovererInfo
*
- * Returns: (transfer full): the structure (or topology) of the URI as a
+ * Returns: (transfer full) (nullable): the structure (or topology) of the URI as a
* #GstDiscovererStreamInfo.
* This structure can be traversed to see the original hierarchy. Unref with
* gst_discoverer_stream_info_unref() after usage.
* Deprecated: This functions is deprecated since version 1.4, use
* #gst_discoverer_info_get_missing_elements_installer_details
*
- * Returns: (transfer none): Miscellaneous information stored as a #GstStructure
+ * Returns: (transfer none) (nullable): Miscellaneous information stored as a #GstStructure
* (for example: information about missing plugins). If you wish to use the
* #GstStructure after the life-time of @info, you will need to copy it.
*/
* gst_discoverer_info_get_tags:
* @info: a #GstDiscovererInfo
*
- * Returns: (transfer none): all tags contained in the URI. If you wish to use
+ * Returns: (transfer none) (nullable): all tags contained in the URI. If you wish to use
* the tags after the life-time of @info, you will need to copy them.
*
* Deprecated: 1.20: Use gst_discoverer_{container,stream}_info_get_tags() instead.
* gst_discoverer_info_get_toc:
* @info: a #GstDiscovererInfo
*
- * Returns: (transfer none): TOC contained in the URI. If you wish to use
+ * Returns: (transfer none) (nullable): TOC contained in the URI. If you wish to use
* the TOC after the life-time of @info, you will need to copy it.
*/
* gst_discoverer_discover_uri:
* @discoverer: A #GstDiscoverer
* @uri: The URI to run on.
- * @err: (out) (allow-none): If an error occurred, this field will be filled in.
+ * @err: (out) (optional): If an error occurred, this field will be filled in.
*
* Synchronously discovers the given @uri.
*
* gst_discoverer_new:
* @timeout: timeout per file, in nanoseconds. Allowed are values between
* one second (#GST_SECOND) and one hour (3600 * #GST_SECOND)
- * @err: a pointer to a #GError. can be %NULL
+ * @err: (optional): a pointer to a #GError. can be %NULL
*
* Creates a new #GstDiscoverer with the provided timeout.
*
* that a source element for a particular URI protocol is missing. This
* function is mainly for use in plugins.
*
- * Returns: (transfer full): a new #GstMessage, or NULL on error
+ * Returns: (transfer full): a new #GstMessage
*/
GstMessage *
gst_missing_uri_source_message_new (GstElement * element,
* that a sink element for a particular URI protocol is missing. This
* function is mainly for use in plugins.
*
- * Returns: (transfer full): a new #GstMessage, or NULL on error
+ * Returns: (transfer full): a new #GstMessage
*/
GstMessage *
gst_missing_uri_sink_message_new (GstElement * element, const gchar * protocol)
* that a certain required element is missing. This function is mainly for
* use in plugins.
*
- * Returns: (transfer full): a new #GstMessage, or NULL on error
+ * Returns: (transfer full): a new #GstMessage
*/
GstMessage *
gst_missing_element_message_new (GstElement * element,
* that a decoder element for a particular set of (fixed) caps is missing.
* This function is mainly for use in plugins.
*
- * Returns: (transfer full): a new #GstMessage, or NULL on error
+ * Returns: (transfer full): a new #GstMessage
*/
GstMessage *
gst_missing_decoder_message_new (GstElement * element,
* that an encoder element for a particular set of (fixed) caps is missing.
* This function is mainly for use in plugins.
*
- * Returns: (transfer full): a new #GstMessage, or NULL on error
+ * Returns: (transfer full): a new #GstMessage
*/
GstMessage *
gst_missing_encoder_message_new (GstElement * element,
* This function is mainly for applications that call external plugin
* installation mechanisms using one of the two above-mentioned functions.
*
- * Returns: a newly-allocated detail string, or NULL on error. Free string
+ * Returns: (nullable): a newly-allocated detail string, or NULL on error. Free string
* with g_free() when not needed any longer.
*/
gchar *
* describing a missing plugin, given a previously collected missing-plugin
* message
*
- * Returns: a newly-allocated description string, or NULL on error. Free
+ * Returns: a newly-allocated description string. Free
* string with g_free() when not needed any longer.
*/
gchar *
* the case where the application knows exactly what kind of plugin it is
* missing.
*
- * Returns: a newly-allocated detail string, or NULL on error. Free string
+ * Returns: (transfer full): a newly-allocated detail string. Free string
* with g_free() when not needed any longer.
*/
gchar *
* the case where the application knows exactly what kind of plugin it is
* missing.
*
- * Returns: a newly-allocated detail string, or NULL on error. Free string
+ * Returns: (transfer full): a newly-allocated detail string. Free string
* with g_free() when not needed any longer.
*/
gchar *
* the case where the application knows exactly what kind of plugin it is
* missing.
*
- * Returns: a newly-allocated detail string, or NULL on error. Free string
+ * Returns: (transfer full): a newly-allocated detail string. Free string
* with g_free() when not needed any longer.
*/
gchar *
* the case where the application knows exactly what kind of plugin it is
* missing.
*
- * Returns: a newly-allocated detail string, or NULL on error. Free string
+ * Returns: (transfer full): a newly-allocated detail string. Free string
* with g_free() when not needed any longer.
*/
gchar *
* the case where the application knows exactly what kind of plugin it is
* missing.
*
- * Returns: a newly-allocated detail string, or NULL on error. Free string
+ * Returns: (transfer full): a newly-allocated detail string. Free string
* with g_free() when not needed any longer.
*/
gchar *
projects / platform / upstream / gstreamer.git / commitdiff