GI.Gst.Structs.Message

Messages are implemented as a subclass of MiniObject with a generic Structure as the content. This allows for writing custom messages without requiring an API change while allowing a wide range of different types of messages.

Messages are posted by objects in the pipeline and are passed to the application using the Bus.

The basic use pattern of posting a message on a Bus is as follows:

C code

 gst_bus_post (bus, gst_message_new_eos());

A Element usually posts messages on the bus provided by the parent container using elementPostMessage.

Exported types

newtype Message

Memory-managed wrapper type.

Constructors

Message (ManagedPtr Message)

Instances

BoxedObject Message

Defined in GI.Gst.Structs.Message

Methods

boxedType :: Message -> IO GType

tag ~ AttrSet => Constructible Message tag

Defined in GI.Gst.Structs.Message

Methods

new :: MonadIO m => (ManagedPtr Message -> Message) -> [AttrOp Message tag] -> m Message

newZeroMessage :: MonadIO m => m Message

Construct a Message struct initialized to zero.

noMessage :: Maybe Message

A convenience alias for Nothing :: Maybe Message.

Methods

addRedirectEntry

messageAddRedirectEntry

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a Message of type MessageTypeRedirect

-> Text

location: location string for the new entry

-> Maybe TagList

tagList: tag list for the new entry

-> Maybe Structure

entryStruct: structure for the new entry

-> m ()

Creates and appends a new entry.

The specified location string is copied. However, ownership over the tag list and structure are transferred to the message.

Since: 1.10

getNumRedirectEntries

messageGetNumRedirectEntries

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a Message of type MessageTypeRedirect

-> m Word64

Returns: the number of entries stored in the message

No description available in the introspection data.

Since: 1.10

getSeqnum

messageGetSeqnum

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A Message.

-> m Word32

Returns: The message's sequence number.

MT safe.

Retrieve the sequence number of a message.

Messages have ever-incrementing sequence numbers, which may also be set explicitly via messageSetSeqnum. Sequence numbers are typically used to indicate that a message corresponds to some other set of messages or events, for example a SEGMENT_DONE message corresponding to a SEEK event. It is considered good practice to make this correspondence when possible, though it is not required.

Note that events and messages share the same sequence number incrementor; two events or messages will never have the same sequence number unless that correspondence was made explicitly.

getStreamStatusObject

messageGetStreamStatusObject

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_STREAM_STATUS.

-> m (Maybe GValue)

Returns: a GValue containing the object that manages the streaming thread. This object is usually of type GstTask but other types can be added in the future. The object remains valid as long as message is valid.

Extracts the object managing the streaming thread from message.

getStructure

messageGetStructure

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: The Message.

-> m (Maybe Structure)

Returns: The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message.

MT safe.

Access the structure of the message.

hasName

messageHasName

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: The Message.

-> Text

name: name to check

-> m Bool

Returns: True if name matches the name of the message structure.

Checks if message has the given name. This function is usually used to check the name of a custom message.

newApplication

messageNewApplication

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> Structure

structure: the structure for the message. The message will take ownership of the structure.

-> m (Maybe Message)

Returns: The new application message.

MT safe.

Create a new application-typed message. GStreamer will never create these messages; they are a gift from us to you. Enjoy.

newAsyncDone

messageNewAsyncDone

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> Word64

runningTime: the desired running_time

-> m Message

Returns: The new async_done message.

MT safe.

The message is posted when elements completed an ASYNC state change. runningTime contains the time of the desired running_time when this elements goes to PLAYING. A value of CLOCK_TIME_NONE for runningTime means that the element has no clock interaction and thus doesn't care about the running_time of the pipeline.

newAsyncStart

messageNewAsyncStart

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> m Message

Returns: The new async_start message.

MT safe.

This message is posted by elements when they start an ASYNC state change.

newBuffering

messageNewBuffering

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> Int32

percent: The buffering percent

-> m (Maybe Message)

Returns: The new buffering message.

Create a new buffering message. This message can be posted by an element that needs to buffer data before it can continue processing. percent should be a value between 0 and 100. A value of 100 means that the buffering completed.

When percent is < 100 the application should PAUSE a PLAYING pipeline. When percent is 100, the application can set the pipeline (back) to PLAYING. The application must be prepared to receive BUFFERING messages in the PREROLLING state and may only set the pipeline to PLAYING after receiving a message with percent set to 100, which can happen after the pipeline completed prerolling.

MT safe.

newClockLost

messageNewClockLost

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsClock b)

=> Maybe a

src: The object originating the message.

-> b

clock: the clock that was lost

-> m Message

Returns: The new clock lost message.

MT safe.

Create a clock lost message. This message is posted whenever the clock is not valid anymore.

If this message is posted by the pipeline, the pipeline will select a new clock again when it goes to PLAYING. It might therefore be needed to set the pipeline to PAUSED and PLAYING again.

newClockProvide

messageNewClockProvide

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsClock b)

=> Maybe a

src: The object originating the message.

-> b

clock: the clock it provides

-> Bool

ready: True if the sender can provide a clock

-> m Message

Returns: the new provide clock message.

MT safe.

Create a clock provide message. This message is posted whenever an element is ready to provide a clock or lost its ability to provide a clock (maybe because it paused or became EOS).

This message is mainly used internally to manage the clock selection.

newCustom

messageNewCustom

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> [MessageType]

type: The MessageType to distinguish messages

-> Maybe a

src: The object originating the message.

-> Maybe Structure

structure: the structure for the message. The message will take ownership of the structure.

-> m (Maybe Message)

Returns: The new message.

MT safe.

Create a new custom-typed message. This can be used for anything not handled by other message-specific functions to pass a message to the app. The structure field can be Nothing.

newDeviceAdded

messageNewDeviceAdded

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsDevice b)

=> a

src: The Object that created the message

-> b

device: The new Device

-> m Message

Returns: a newly allocated Message

Creates a new device-added message. The device-added message is produced by DeviceProvider or a DeviceMonitor. They announce the appearance of monitored devices.

Since: 1.4

newDeviceRemoved

messageNewDeviceRemoved

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsDevice b)

=> a

src: The Object that created the message

-> b

device: The removed Device

-> m Message

Returns: a newly allocated Message

Creates a new device-removed message. The device-removed message is produced by DeviceProvider or a DeviceMonitor. They announce the disappearance of monitored devices.

Since: 1.4

newDurationChanged

messageNewDurationChanged

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> m Message

Returns: The new duration-changed message.

MT safe.

Create a new duration changed message. This message is posted by elements that know the duration of a stream when the duration changes. This message is received by bins and is used to calculate the total duration of a pipeline.

newElement

messageNewElement

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> Structure

structure: The structure for the message. The message will take ownership of the structure.

-> m (Maybe Message)

Returns: The new element message.

MT safe.

Create a new element-specific message. This is meant as a generic way of allowing one-way communication from an element to an application, for example "the firewire cable was unplugged". The format of the message should be documented in the element's documentation. The structure field can be Nothing.

newEos

messageNewEos

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> m Message

Returns: The new eos message.

MT safe.

Create a new eos message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the EOS message to the application if all sinks have posted an EOS message.

newError

messageNewError

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> GError

error: The GError for this message.

-> Text

debug: A debugging string.

-> m Message

Returns: the new error message.

MT safe.

Create a new error message. The message will copy error and debug. This message is posted by element when a fatal event occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline.

newErrorWithDetails

messageNewErrorWithDetails

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> GError

error: The GError for this message.

-> Text

debug: A debugging string.

-> Structure

details: (allow-none): A GstStructure with details

-> m (Maybe Message)

Returns: the new error message.

Create a new error message. The message will copy error and debug. This message is posted by element when a fatal event occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline.

Since: 1.10

newHaveContext

messageNewHaveContext

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> Context

context: the context

-> m Message

Returns: The new have-context message.

MT safe.

This message is posted when an element has a new local Context.

Since: 1.2

newInfo

messageNewInfo

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> GError

error: The GError for this message.

-> Text

debug: A debugging string.

-> m Message

Returns: the new info message.

MT safe.

Create a new info message. The message will make copies of error and debug.

newInfoWithDetails

messageNewInfoWithDetails

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> GError

error: The GError for this message.

-> Text

debug: A debugging string.

-> Structure

details: (allow-none): A GstStructure with details

-> m (Maybe Message)

Returns: the new warning message.

Create a new info message. The message will make copies of error and debug.

Since: 1.10

newLatency

messageNewLatency

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> m Message

Returns: The new latency message.

MT safe.

This message can be posted by elements when their latency requirements have changed.

newNeedContext

messageNewNeedContext

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> Text

contextType: The context type that is needed

-> m Message

Returns: The new need-context message.

MT safe.

This message is posted when an element needs a specific Context.

Since: 1.2

newNewClock

messageNewNewClock

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsClock b)

=> Maybe a

src: The object originating the message.

-> b

clock: the new selected clock

-> m Message

Returns: The new new clock message.

MT safe.

Create a new clock message. This message is posted whenever the pipeline selects a new clock for the pipeline.

newProgress

messageNewProgress

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: The object originating the message.

-> ProgressType

type: a ProgressType

-> Text

code: a progress code

-> Text

text: free, user visible text describing the progress

-> m (Maybe Message)

Returns: The new qos message.

Progress messages are posted by elements when they use an asynchronous task to perform actions triggered by a state change.

code contains a well defined string describing the action. text should contain a user visible string detailing the current action.

newPropertyNotify

messageNewPropertyNotify

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: The Object whose property changed (may or may not be a Element)

-> Text

propertyName: name of the property that changed

-> Maybe GValue

val: new property value, or Nothing

-> m Message

Returns: a newly allocated Message

No description available in the introspection data.

Since: 1.10

newQos

messageNewQos

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: The object originating the message.

-> Bool

live: if the message was generated by a live element

-> Word64

runningTime: the running time of the buffer that generated the message

-> Word64

streamTime: the stream time of the buffer that generated the message

-> Word64

timestamp: the timestamps of the buffer that generated the message

-> Word64

duration: the duration of the buffer that generated the message

-> m Message

Returns: The new qos message.

MT safe.

A QOS message is posted on the bus whenever an element decides to drop a buffer because of QoS reasons or whenever it changes its processing strategy because of QoS reasons (quality adjustments such as processing at lower accuracy).

This message can be posted by an element that performs synchronisation against the clock (live) or it could be dropped by an element that performs QoS because of QOS events received from a downstream element (!live).

runningTime, streamTime, timestamp, duration should be set to the respective running-time, stream-time, timestamp and duration of the (dropped) buffer that generated the QoS event. Values can be left to GST_CLOCK_TIME_NONE when unknown.

newRedirect

messageNewRedirect

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: The Object whose property changed (may or may not be a Element)

-> Text

location: location string for the new entry

-> Maybe TagList

tagList: tag list for the new entry

-> Maybe Structure

entryStruct: structure for the new entry

-> m Message

Returns: a newly allocated Message

Creates a new redirect message and adds a new entry to it. Redirect messages are posted when an element detects that the actual data has to be retrieved from a different location. This is useful if such a redirection cannot be handled inside a source element, for example when HTTP 302/303 redirects return a non-HTTP URL.

The redirect message can hold multiple entries. The first one is added when the redirect message is created, with the given location, tag_list, entry_struct arguments. Use messageAddRedirectEntry to add more entries.

Each entry has a location, a tag list, and a structure. All of these are optional. The tag list and structure are useful for additional metadata, such as bitrate statistics for the given location.

By default, message recipients should treat entries in the order they are stored. The recipient should therefore try entry 0 first, and if this entry is not acceptable or working, try entry 1 etc. Senders must make sure that they add entries in this order. However, recipients are free to ignore the order and pick an entry that is "best" for them. One example would be a recipient that scans the entries for the one with the highest bitrate tag.

The specified location string is copied. However, ownership over the tag list and structure are transferred to the message.

Since: 1.10

newRequestState

messageNewRequestState

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> State

state: The new requested state

-> m Message

Returns: the new request state message.

MT safe.

This message can be posted by elements when they want to have their state changed. A typical use case would be an audio server that wants to pause the pipeline because a higher priority stream is being played.

newResetTime

messageNewResetTime

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> Word64

runningTime: the requested running-time

-> m Message

Returns: The new reset_time message.

MT safe.

This message is posted when the pipeline running-time should be reset to runningTime, like after a flushing seek.

newSegmentDone

messageNewSegmentDone

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> Format

format: The format of the position being done

-> Int64

position: The position of the segment being done

-> m Message

Returns: the new segment done message.

MT safe.

Create a new segment done message. This message is posted by elements that finish playback of a segment as a result of a segment seek. This message is received by the application after all elements that posted a segment_start have posted the segment_done.

newSegmentStart

messageNewSegmentStart

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> Format

format: The format of the position being played

-> Int64

position: The position of the segment being played

-> m Message

Returns: the new segment start message.

MT safe.

Create a new segment message. This message is posted by elements that start playback of a segment as a result of a segment seek. This message is not received by the application but is used for maintenance reasons in container elements.

newStateChanged

messageNewStateChanged

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> State

oldstate: the previous state

-> State

newstate: the new (current) state

-> State

pending: the pending (target) state

-> m Message

Returns: the new state change message.

MT safe.

Create a state change message. This message is posted whenever an element changed its state.

newStateDirty

messageNewStateDirty

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message

-> m Message

Returns: the new state dirty message.

MT safe.

Create a state dirty message. This message is posted whenever an element changed its state asynchronously and is used internally to update the states of container objects.

newStepDone

messageNewStepDone

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: The object originating the message.

-> Format

format: the format of amount

-> Word64

amount: the amount of stepped data

-> Double

rate: the rate of the stepped amount

-> Bool

flush: is this an flushing step

-> Bool

intermediate: is this an intermediate step

-> Word64

duration: the duration of the data

-> Bool

eos: the step caused EOS

-> m Message

Returns: the new step_done message.

MT safe.

This message is posted by elements when they complete a part, when intermediate set to True, or a complete step operation.

duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped amount of media in format format.

newStepStart

messageNewStepStart

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: The object originating the message.

-> Bool

active: if the step is active or queued

-> Format

format: the format of amount

-> Word64

amount: the amount of stepped data

-> Double

rate: the rate of the stepped amount

-> Bool

flush: is this an flushing step

-> Bool

intermediate: is this an intermediate step

-> m Message

Returns: The new step_start message.

MT safe.

This message is posted by elements when they accept or activate a new step event for amount in format.

active is set to False when the element accepted the new step event and has queued it for execution in the streaming threads.

active is set to True when the element has activated the step operation and is now ready to start executing the step in the streaming thread. After this message is emitted, the application can queue a new step operation in the element.

newStreamCollection

messageNewStreamCollection

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsStreamCollection b)

=> a

src: The Object that created the message

-> b

collection: The StreamCollection

-> m Message

Returns: a newly allocated Message

Creates a new stream-collection message. The message is used to announce new StreamCollection

Since: 1.10

newStreamStart

messageNewStreamStart

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> m Message

Returns: The new stream_start message.

MT safe.

Create a new stream_start message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the STREAM_START message to the application if all sinks have posted an STREAM_START message.

newStreamStatus

messageNewStreamStatus

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsElement b)

=> a

src: The object originating the message.

-> StreamStatusType

type: The stream status type.

-> b

owner: the owner element of src.

-> m Message

Returns: the new stream status message.

MT safe.

Create a new stream status message. This message is posted when a streaming thread is created/destroyed or when the state changed.

newStreamsSelected

messageNewStreamsSelected

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsStreamCollection b)

=> a

src: The Object that created the message

-> b

collection: The StreamCollection

-> m Message

Returns: a newly allocated Message

Creates a new steams-selected message. The message is used to announce that an array of streams has been selected. This is generally in response to a GST_EVENT_SELECT_STREAMS event, or when an element (such as decodebin3) makes an initial selection of streams.

The message also contains the StreamCollection to which the various streams belong to.

Users of messageNewStreamsSelected can add the selected streams with messageStreamsSelectedAdd.

Since: 1.10

newStructureChange

messageNewStructureChange

Arguments

:: (HasCallStack, MonadIO m, IsObject a, IsElement b)

=> Maybe a

src: The object originating the message.

-> StructureChangeType

type: The change type.

-> b

owner: The owner element of src.

-> Bool

busy: Whether the structure change is busy.

-> m Message

Returns: the new structure change message.

MT safe.

Create a new structure change message. This message is posted when the structure of a pipeline is in the process of being changed, for example when pads are linked or unlinked.

src should be the sinkpad that unlinked or linked.

newTag

messageNewTag

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> TagList

tagList: the tag list for the message.

-> m Message

Returns: the new tag message.

MT safe.

Create a new tag message. The message will take ownership of the tag list. The message is posted by elements that discovered a new taglist.

newToc

messageNewToc

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: the object originating the message.

-> Toc

toc: Toc structure for the message.

-> Bool

updated: whether TOC was updated or not.

-> m Message

Returns: a new TOC message.

MT safe.

Create a new TOC message. The message is posted by elements that discovered or updated a TOC.

newWarning

messageNewWarning

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> GError

error: The GError for this message.

-> Text

debug: A debugging string.

-> m Message

Returns: the new warning message.

MT safe.

Create a new warning message. The message will make copies of error and debug.

newWarningWithDetails

messageNewWarningWithDetails

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> Maybe a

src: The object originating the message.

-> GError

error: The GError for this message.

-> Text

debug: A debugging string.

-> Structure

details: (allow-none): A GstStructure with details

-> m (Maybe Message)

Returns: the new warning message.

Create a new warning message. The message will make copies of error and debug.

Since: 1.10

parseAsyncDone

messageParseAsyncDone

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_ASYNC_DONE.

-> m Word64

Extract the running_time from the async_done message.

MT safe.

parseBuffering

messageParseBuffering

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_BUFFERING.

-> m Int32

Extracts the buffering percent from the GstMessage. see also messageNewBuffering.

MT safe.

parseBufferingStats

messageParseBufferingStats

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_BUFFERING.

-> m (BufferingMode, Int32, Int32, Int64)

Extracts the buffering stats values from message.

parseClockLost

messageParseClockLost

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_CLOCK_LOST.

-> m Clock

Extracts the lost clock from the GstMessage. The clock object returned remains valid until the message is freed.

MT safe.

parseClockProvide

messageParseClockProvide

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_CLOCK_PROVIDE.

-> m (Clock, Bool)

Extracts the clock and ready flag from the GstMessage. The clock object returned remains valid until the message is freed.

MT safe.

parseContextType

messageParseContextType

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a GST_MESSAGE_NEED_CONTEXT type message

-> m (Bool, Text)

Returns: a Bool indicating if the parsing succeeded.

Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message.

Since: 1.2

parseDeviceAdded

messageParseDeviceAdded

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a Message of type MessageTypeDeviceAdded

-> m Device

Parses a device-added message. The device-added message is produced by DeviceProvider or a DeviceMonitor. It announces the appearance of monitored devices.

Since: 1.4

parseDeviceRemoved

messageParseDeviceRemoved

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a Message of type MessageTypeDeviceRemoved

-> m Device

Parses a device-removed message. The device-removed message is produced by DeviceProvider or a DeviceMonitor. It announces the disappearance of monitored devices.

Since: 1.4

parseError

messageParseError

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_ERROR.

-> m (GError, Text)

Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done.

Typical usage of this function might be:

C code

 ...
 switch (GST_MESSAGE_TYPE (msg)) {
   case GST_MESSAGE_ERROR: {
     GError *err = NULL;
     gchar *dbg_info = NULL;

     gst_message_parse_error (msg, &err, &dbg_info);
     g_printerr ("ERROR from element %s: %s\n",
         GST_OBJECT_NAME (msg->src), err->message);
     g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none");
     g_error_free (err);
     g_free (dbg_info);
     break;
   }
   ...
 }
 ...

MT safe.

parseErrorDetails

messageParseErrorDetails

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: The message object

-> m Structure

Returns the optional details structure, may be NULL if none. The returned structure must not be freed.

Since: 1.10

parseGroupId

messageParseGroupId

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_STREAM_START.

-> m (Bool, Word32)

Returns: True if the message had a group id set, False otherwise

MT safe.

Extract the group from the STREAM_START message.

Since: 1.2

parseHaveContext

messageParseHaveContext

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_HAVE_CONTEXT.

-> m Context

Extract the context from the HAVE_CONTEXT message.

MT safe.

Since: 1.2

parseInfo

messageParseInfo

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_INFO.

-> m (GError, Text)

Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done.

MT safe.

parseInfoDetails

messageParseInfoDetails

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: The message object

-> m Structure

Returns the optional details structure, may be NULL if none The returned structure must not be freed.

Since: 1.10

parseNewClock

messageParseNewClock

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_NEW_CLOCK.

-> m Clock

Extracts the new clock from the GstMessage. The clock object returned remains valid until the message is freed.

MT safe.

parseProgress

messageParseProgress

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_PROGRESS.

-> m (ProgressType, Text, Text)

Parses the progress type, code and text.

parsePropertyNotify

messageParsePropertyNotify

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a Message of type MessageTypePropertyNotify

-> m (Object, Text, GValue)

Parses a property-notify message. These will be posted on the bus only when set up with elementAddPropertyNotifyWatch or elementAddPropertyDeepNotifyWatch.

Since: 1.10

parseQos

messageParseQos

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_QOS.

-> m (Bool, Word64, Word64, Word64, Word64)

Extract the timestamps and live status from the QoS message.

The returned values give the running_time, stream_time, timestamp and duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown values.

MT safe.

parseQosStats

messageParseQosStats

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_QOS.

-> m (Format, Word64, Word64)

Extract the QoS stats representing the history of the current continuous pipeline playback period.

When format is gSTFORMATUNDEFINED both dropped and processed are invalid. Values of -1 for either processed or dropped mean unknown values.

MT safe.

parseQosValues

messageParseQosValues

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_QOS.

-> m (Int64, Double, Int32)

Extract the QoS values that have been calculated/analysed from the QoS data

MT safe.

parseRedirectEntry

messageParseRedirectEntry

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a Message of type MessageTypeRedirect

-> Word64

entryIndex: index of the entry to parse

-> m (Text, TagList, Structure)

Parses the location and/or structure from the entry with the given index. The index must be between 0 and messageGetNumRedirectEntries - 1. Returned pointers are valid for as long as this message exists.

Since: 1.10

parseRequestState

messageParseRequestState

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_REQUEST_STATE.

-> m State

Extract the requested state from the request_state message.

MT safe.

parseResetTime

messageParseResetTime

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_RESET_TIME.

-> m Word64

Extract the running-time from the RESET_TIME message.

MT safe.

parseSegmentDone

messageParseSegmentDone

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_SEGMENT_DONE.

-> m (Format, Int64)

Extracts the position and format from the segment done message.

MT safe.

parseSegmentStart

messageParseSegmentStart

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_SEGMENT_START.

-> m (Format, Int64)

Extracts the position and format from the segment start message.

MT safe.

parseStateChanged

messageParseStateChanged

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a valid Message of type GST_MESSAGE_STATE_CHANGED

-> m (State, State, State)

Extracts the old and new states from the GstMessage.

Typical usage of this function might be:

C code

 ...
 switch (GST_MESSAGE_TYPE (msg)) {
   case GST_MESSAGE_STATE_CHANGED: {
     GstState old_state, new_state;

     gst_message_parse_state_changed (msg, &old_state, &new_state, NULL);
     g_print ("Element %s changed state from %s to %s.\n",
         GST_OBJECT_NAME (msg->src),
         gst_element_state_get_name (old_state),
         gst_element_state_get_name (new_state));
     break;
   }
   ...
 }
 ...

MT safe.

parseStepDone

messageParseStepDone

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_STEP_DONE.

-> m (Format, Word64, Double, Bool, Bool, Word64, Bool)

Extract the values the step_done message.

MT safe.

parseStepStart

messageParseStepStart

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_STEP_DONE.

-> m (Bool, Format, Word64, Double, Bool, Bool)

Extract the values from step_start message.

MT safe.

parseStreamCollection

messageParseStreamCollection

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a Message of type MessageTypeStreamCollection

-> m StreamCollection

Parses a stream-collection message.

Since: 1.10

parseStreamStatus

messageParseStreamStatus

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_STREAM_STATUS.

-> m (StreamStatusType, Element)

Extracts the stream status type and owner the GstMessage. The returned owner remains valid for as long as the reference to message is valid and should thus not be unreffed.

MT safe.

parseStreamsSelected

messageParseStreamsSelected

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a Message of type MessageTypeStreamsSelected

-> m StreamCollection

Parses a streams-selected message.

Since: 1.10

parseStructureChange

messageParseStructureChange

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_STRUCTURE_CHANGE.

-> m (StructureChangeType, Element, Bool)

Extracts the change type and completion status from the GstMessage.

MT safe.

parseTag

messageParseTag

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_TAG.

-> m TagList

Extracts the tag list from the GstMessage. The tag list returned in the output argument is a copy; the caller must free it when done.

Typical usage of this function might be:

C code

 ...
 switch (GST_MESSAGE_TYPE (msg)) {
   case GST_MESSAGE_TAG: {
     GstTagList *tags = NULL;

     gst_message_parse_tag (msg, &tags);
     g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src));
     handle_tags (tags);
     gst_tag_list_unref (tags);
     break;
   }
   ...
 }
 ...

MT safe.

parseToc

messageParseToc

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a valid Message of type GST_MESSAGE_TOC.

-> m (Toc, Bool)

Extract the TOC from the Message. The TOC returned in the output argument is a copy; the caller must free it with gst_toc_unref() when done.

MT safe.

parseWarning

messageParseWarning

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_WARNING.

-> m (GError, Text)

Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done.

MT safe.

parseWarningDetails

messageParseWarningDetails

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: The message object

-> m Structure

Returns the optional details structure, may be NULL if none The returned structure must not be freed.

Since: 1.10

setBufferingStats

messageSetBufferingStats

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_BUFFERING.

-> BufferingMode

mode: a buffering mode

-> Int32

avgIn: the average input rate

-> Int32

avgOut: the average output rate

-> Int64

bufferingLeft: amount of buffering time left in milliseconds

-> m ()

Configures the buffering stats values in message.

setGroupId

messageSetGroupId

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: the message

-> Word32

groupId: the group id

-> m ()

Sets the group id on the stream-start message.

All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the same group id but different stream ids. The group id should change each time the stream is started, resulting in different group ids each time a file is played for example.

MT safe.

Since: 1.2

setQosStats

messageSetQosStats

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_QOS.

-> Format

format: Units of the 'processed' and 'dropped' fields. Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT (samples).

-> Word64

processed: Total number of units correctly processed since the last state change to READY or a flushing operation.

-> Word64

dropped: Total number of units dropped since the last state change to READY or a flushing operation.

-> m ()

Set the QoS stats representing the history of the current continuous pipeline playback period.

When format is gSTFORMATUNDEFINED both dropped and processed are invalid. Values of -1 for either processed or dropped mean unknown values.

MT safe.

setQosValues

messageSetQosValues

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_QOS.

-> Int64

jitter: The difference of the running-time against the deadline.

-> Double

proportion: Long term prediction of the ideal rate relative to normal rate to get optimal quality.

-> Int32

quality: An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000.

-> m ()

Set the QoS values that have been calculated/analysed from the QoS data

MT safe.

setSeqnum

messageSetSeqnum

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A Message.

-> Word32

seqnum: A sequence number.

-> m ()

Set the sequence number of a message.

This function might be called by the creator of a message to indicate that the message relates to other messages or events. See messageGetSeqnum for more information.

MT safe.

setStreamStatusObject

messageSetStreamStatusObject

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A valid Message of type GST_MESSAGE_STREAM_STATUS.

-> GValue

object: the object controlling the streaming

-> m ()

Configures the object handling the streaming thread. This is usually a GstTask object but other objects might be added in the future.

streamsSelectedAdd

messageStreamsSelectedAdd

Arguments

:: (HasCallStack, MonadIO m, IsStream a)

=> Message

message: a Message of type MessageTypeStreamsSelected

-> a

stream: a Stream to add to message

-> m ()

Adds the stream to the message.

Since: 1.10

streamsSelectedGetSize

messageStreamsSelectedGetSize

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a Message of type MessageTypeStreamsSelected

-> m Word32

Returns: The number of streams contained within.

Returns the number of streams contained in the message.

Since: 1.10

streamsSelectedGetStream

messageStreamsSelectedGetStream

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: a Message of type MessageTypeStreamsSelected

-> Word32

idx: Index of the stream to retrieve

-> m (Maybe Stream)

Returns: A Stream

Retrieves the Stream with index index from the message.

Since: 1.10

writableStructure

messageWritableStructure

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: The Message.

-> m Structure

Returns: The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message. This function checks if message is writable and will never return Nothing.

MT safe.

Get a writable version of the structure.

Since: 1.14

Properties

miniObject

the parent structure

getMessageMiniObject :: MonadIO m => Message -> m MiniObject

Get the value of the “mini_object” field. When overloading is enabled, this is equivalent to

get message #miniObject

seqnum

the sequence number of the message

getMessageSeqnum :: MonadIO m => Message -> m Word32

Get the value of the “seqnum” field. When overloading is enabled, this is equivalent to

get message #seqnum

setMessageSeqnum :: MonadIO m => Message -> Word32 -> m ()

Set the value of the “seqnum” field. When overloading is enabled, this is equivalent to

set message [ #seqnum := value ]

src

the src of the message

clearMessageSrc :: MonadIO m => Message -> m ()

Set the value of the “src” field to Nothing. When overloading is enabled, this is equivalent to

clear #src

getMessageSrc :: MonadIO m => Message -> m (Maybe Object)

Get the value of the “src” field. When overloading is enabled, this is equivalent to

get message #src

setMessageSrc :: MonadIO m => Message -> Ptr Object -> m ()

Set the value of the “src” field. When overloading is enabled, this is equivalent to

set message [ #src := value ]

timestamp

the timestamp of the message

getMessageTimestamp :: MonadIO m => Message -> m Word64

Get the value of the “timestamp” field. When overloading is enabled, this is equivalent to

get message #timestamp

setMessageTimestamp :: MonadIO m => Message -> Word64 -> m ()

Set the value of the “timestamp” field. When overloading is enabled, this is equivalent to

set message [ #timestamp := value ]

type

the MessageType of the message

getMessageType :: MonadIO m => Message -> m [MessageType]

Get the value of the “type” field. When overloading is enabled, this is equivalent to

get message #type

setMessageType :: MonadIO m => Message -> [MessageType] -> m ()

Set the value of the “type” field. When overloading is enabled, this is equivalent to

set message [ #type := value ]