1 /* GStreamer 2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu> 3 * 2000,2004 Wim Taymans <wim@fluendo.com> 4 * 5 * gstelement.h: Header for GstElement 6 * 7 * This library is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Library General Public 9 * License as published by the Free Software Foundation; either 10 * version 2 of the License, or (at your option) any later version. 11 * 12 * This library is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Library General Public License for more details. 16 * 17 * You should have received a copy of the GNU Library General Public 18 * License along with this library; if not, write to the 19 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 20 * Boston, MA 02110-1301, USA. 21 */ 22 23 24 #ifndef __GST_ELEMENT_H__ 25 #define __GST_ELEMENT_H__ 26 27 #include <glib.h> 28 29 G_BEGIN_DECLS 30 31 /** 32 * _GST_ELEMENT_REGISTER_DEFINE_BEGIN: (attributes doc.skip=true) 33 */ 34 #define _GST_ELEMENT_REGISTER_DEFINE_BEGIN(element) \ 35 G_BEGIN_DECLS \ 36 gboolean G_PASTE (gst_element_register_, element) (GstPlugin * plugin) \ 37 { \ 38 { 39 40 /** 41 * _GST_ELEMENT_REGISTER_DEFINE_END: (attributes doc.skip=true) 42 */ 43 #define _GST_ELEMENT_REGISTER_DEFINE_END(element_name, rank, type) \ 44 } \ 45 return gst_element_register (plugin, element_name, rank, type); \ 46 } \ 47 G_END_DECLS 48 49 /** 50 * GST_ELEMENT_REGISTER_DEFINE_CUSTOM: 51 * @element: The element name in lower case, with words separated by '_'. 52 * Used to generate `gst_element_register_*(GstPlugin* plugin)`. 53 * @register_func: pointer to a method with the format: `gboolean register_func (GstPlugin* plugin);` 54 * 55 * A convenience macro to define the entry point of an 56 * element `gst_element_register_*(GstPlugin* plugin)` which uses 57 * register_func as the main registration method for the element. 58 * As an example, you may define the element named "streamer-filter" 59 * with the namespace `my` as following using `element_register_custom`: 60 * 61 * ``` 62 * GST_ELEMENT_REGISTER_DEFINE_CUSTOM (my_element, element_register_custom) 63 * ``` 64 * 65 * Since: 1.20 66 */ 67 #define GST_ELEMENT_REGISTER_DEFINE_CUSTOM(element, register_func) \ 68 G_BEGIN_DECLS \ 69 gboolean G_PASTE (gst_element_register_, element) (GstPlugin * plugin) \ 70 { \ 71 return register_func (plugin); \ 72 } \ 73 G_END_DECLS 74 75 /** 76 * GST_ELEMENT_REGISTER_DEFINE: 77 * @e: The element name in lower case, with words separated by '_'. 78 * Used to generate `gst_element_register_*(GstPlugin* plugin)`. 79 * @e_n: The public name of the element 80 * @r: The #GstRank of the element (higher rank means more importance when autoplugging, see #GstRank) 81 * @t: The #GType of the element. 82 * 83 * A convenience macro to define the entry point of an 84 * element `gst_element_register_*(GstPlugin* plugin)`. 85 * As an example, you may define the element named "streamer-filter" 86 * with the namespace `my` as following: 87 * 88 * ``` 89 * GST_ELEMENT_REGISTER_REGISTER_DEFINE (stream_filter, "stream-filter", GST_RANK_PRIMARY, MY_TYPE_STREAM_FILTER) 90 * ``` 91 * 92 * Since: 1.20 93 */ 94 #define GST_ELEMENT_REGISTER_DEFINE(e, e_n, r, t) _GST_ELEMENT_REGISTER_DEFINE_BEGIN(e) _GST_ELEMENT_REGISTER_DEFINE_END(e_n, r, t) 95 96 /** 97 * GST_ELEMENT_REGISTER_DEFINE_WITH_CODE: 98 * @e: The element name in lower case, with words separated by '_'. 99 * Used to generate `gst_element_register_*(GstPlugin* plugin)`. 100 * @e_n: The public name of the element 101 * @r: The #GstRank of the element (higher rank means more importance when autoplugging, see #GstRank) 102 * @t: The #GType of the element. 103 * @_c_: Custom code that gets inserted in the gst_element_register_*() function. 104 * 105 * A convenience macro to define the entry point of an 106 * element `gst_element_register_*(GstPlugin* plugin)` executing code 107 * before gst_element_register in `gst_element_register_*(GstPlugin* plugin)`. 108 109 * As an example, you may define the element named "stream-filter" 110 * with the namespace `my` as following: 111 * 112 * ``` 113 * #define _pre_register_init \ 114 * my_stream_filter_pre_register (plugin); 115 * GST_ELEMENT_REGISTER_DEFINE_WITH_CODE (stream_filter, "stream-filter", GST_RANK_PRIMARY, MY_TYPE_STREAM_FILTER, _pre_register_init) 116 * ``` 117 * 118 * Since: 1.20 119 */ 120 #define GST_ELEMENT_REGISTER_DEFINE_WITH_CODE(e, e_n, r, t, _c_) _GST_ELEMENT_REGISTER_DEFINE_BEGIN(e) {_c_;} _GST_ELEMENT_REGISTER_DEFINE_END(e_n, r, t) 121 122 /** 123 * GST_ELEMENT_REGISTER_DECLARE: 124 * @element: The element name in lower case, with words separated by '_'. 125 * 126 * This macro can be used to declare a new element. 127 * It has to be used in combination with #GST_ELEMENT_REGISTER_DEFINE macros 128 * and must be placed outside any block to declare the element registration 129 * function. 130 * As an example, you may declare the element named "stream-filter" 131 * with the namespace `my` as following: 132 * 133 * ``` 134 * GST_ELEMENT_REGISTER_DECLARE (stream_filter) 135 * ``` 136 * 137 * Since: 1.20 138 */ 139 #define GST_ELEMENT_REGISTER_DECLARE(element) \ 140 G_BEGIN_DECLS \ 141 gboolean G_PASTE(gst_element_register_, element) (GstPlugin * plugin); \ 142 G_END_DECLS 143 144 /** 145 * GST_ELEMENT_REGISTER: 146 * @element: The element name in lower case, with words separated by '_'. 147 * @plugin: The #GstPlugin where to register the element. 148 * 149 * This macro can be used to register an element into a #GstPlugin. 150 * This method will be usually called in the plugin init function 151 * but can also be called with a NULL plugin, 152 * for example with a static registration of the element. 153 * It has to be used in combination with #GST_ELEMENT_REGISTER_DECLARE. 154 * 155 * ``` 156 * GstPlugin* plugin; 157 * 158 * ... 159 * 160 * GST_ELEMENT_REGISTER (stream_filter, plugin); 161 * ``` 162 * 163 * Since: 1.20 164 */ 165 #define GST_ELEMENT_REGISTER(element, plugin) G_PASTE(gst_element_register_, element) (plugin) 166 167 /* gstelement.h and gstelementfactory.h include each other */ 168 typedef struct _GstElement GstElement; 169 typedef struct _GstElementClass GstElementClass; 170 171 /* gstmessage.h needs State */ 172 /** 173 * GstState: 174 * @GST_STATE_VOID_PENDING: no pending state. 175 * @GST_STATE_NULL : the NULL state or initial state of an element. 176 * @GST_STATE_READY : the element is ready to go to PAUSED. 177 * @GST_STATE_PAUSED : the element is PAUSED, it is ready to accept and 178 * process data. Sink elements however only accept one 179 * buffer and then block. 180 * @GST_STATE_PLAYING : the element is PLAYING, the #GstClock is running and 181 * the data is flowing. 182 * 183 * The possible states an element can be in. States can be changed using 184 * gst_element_set_state() and checked using gst_element_get_state(). 185 */ 186 typedef enum { 187 GST_STATE_VOID_PENDING = 0, 188 GST_STATE_NULL = 1, 189 GST_STATE_READY = 2, 190 GST_STATE_PAUSED = 3, 191 GST_STATE_PLAYING = 4 192 } GstState; 193 194 #define GST_TYPE_ELEMENT (gst_element_get_type ()) 195 #define GST_IS_ELEMENT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_ELEMENT)) 196 #define GST_IS_ELEMENT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_ELEMENT)) 197 #define GST_ELEMENT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_ELEMENT, GstElementClass)) 198 #define GST_ELEMENT(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_ELEMENT, GstElement)) 199 #define GST_ELEMENT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_ELEMENT, GstElementClass)) 200 #define GST_ELEMENT_CAST(obj) ((GstElement*)(obj)) 201 202 /** 203 * GstStateChangeReturn: 204 * @GST_STATE_CHANGE_FAILURE : the state change failed 205 * @GST_STATE_CHANGE_SUCCESS : the state change succeeded 206 * @GST_STATE_CHANGE_ASYNC : the state change will happen asynchronously 207 * @GST_STATE_CHANGE_NO_PREROLL: the state change succeeded but the element 208 * cannot produce data in %GST_STATE_PAUSED. 209 * This typically happens with live sources. 210 * 211 * The possible return values from a state change function such as 212 * gst_element_set_state(). Only @GST_STATE_CHANGE_FAILURE is a real failure. 213 */ 214 typedef enum { 215 GST_STATE_CHANGE_FAILURE = 0, 216 GST_STATE_CHANGE_SUCCESS = 1, 217 GST_STATE_CHANGE_ASYNC = 2, 218 GST_STATE_CHANGE_NO_PREROLL = 3 219 } GstStateChangeReturn; 220 221 #include <gst/gstconfig.h> 222 #include <gst/gstobject.h> 223 #include <gst/gstpad.h> 224 #include <gst/gstbus.h> 225 #include <gst/gstclock.h> 226 #include <gst/gstelementfactory.h> 227 #include <gst/gstplugin.h> 228 #include <gst/gstpluginfeature.h> 229 #include <gst/gstiterator.h> 230 #include <gst/gstmessage.h> 231 #include <gst/gstquery.h> 232 #include <gst/gsttaglist.h> 233 #include <gst/gstcontext.h> 234 235 /* NOTE: this probably should be done with an #ifdef to decide 236 * whether to safe-cast or to just do the non-checking cast. 237 */ 238 239 /** 240 * GST_STATE: 241 * @elem: a #GstElement to return state for. 242 * 243 * This macro returns the current #GstState of the element. 244 */ 245 #define GST_STATE(elem) (GST_ELEMENT_CAST(elem)->current_state) 246 247 /** 248 * GST_STATE_NEXT: 249 * @elem: a #GstElement to return the next state for. 250 * 251 * This macro returns the next #GstState of the element. 252 */ 253 #define GST_STATE_NEXT(elem) (GST_ELEMENT_CAST(elem)->next_state) 254 255 /** 256 * GST_STATE_PENDING: 257 * @elem: a #GstElement to return the pending state for. 258 * 259 * This macro returns the currently pending #GstState of the element. 260 */ 261 #define GST_STATE_PENDING(elem) (GST_ELEMENT_CAST(elem)->pending_state) 262 263 /** 264 * GST_STATE_TARGET: 265 * @elem: a #GstElement to return the target state for. 266 * 267 * This macro returns the target #GstState of the element. 268 */ 269 #define GST_STATE_TARGET(elem) (GST_ELEMENT_CAST(elem)->target_state) 270 271 /** 272 * GST_STATE_RETURN: 273 * @elem: a #GstElement to return the last state result for. 274 * 275 * This macro returns the last #GstStateChangeReturn value. 276 */ 277 #define GST_STATE_RETURN(elem) (GST_ELEMENT_CAST(elem)->last_return) 278 279 #define __GST_SIGN(val) ((val) < 0 ? -1 : ((val) > 0 ? 1 : 0)) 280 /** 281 * GST_STATE_GET_NEXT: 282 * @cur: A starting #GstState 283 * @pending: A target #GstState 284 * 285 * Given a current state @cur and a target state @pending, calculate the next (intermediate) 286 * #GstState. 287 */ 288 #define GST_STATE_GET_NEXT(cur,pending) ((GstState)((cur) + __GST_SIGN ((gint)(pending) - (gint)(cur)))) 289 /** 290 * GST_STATE_TRANSITION: 291 * @cur: A current state 292 * @next: A next state 293 * 294 * Given a current state @cur and a next state @next, calculate the associated 295 * #GstStateChange transition. 296 */ 297 #define GST_STATE_TRANSITION(cur,next) ((GstStateChange)(((cur)<<3)|(next))) 298 /** 299 * GST_STATE_TRANSITION_CURRENT: 300 * @trans: A #GstStateChange 301 * 302 * Given a state transition @trans, extract the current #GstState. 303 */ 304 #define GST_STATE_TRANSITION_CURRENT(trans) ((GstState)((trans)>>3)) 305 /** 306 * GST_STATE_TRANSITION_NEXT: 307 * @trans: A #GstStateChange 308 * 309 * Given a state transition @trans, extract the next #GstState. 310 */ 311 #define GST_STATE_TRANSITION_NEXT(trans) ((GstState)((trans)&0x7)) 312 313 /** 314 * GstStateChange: 315 * @GST_STATE_CHANGE_NULL_TO_READY : state change from NULL to READY. 316 * * The element must check if the resources it needs are available. Device 317 * sinks and -sources typically try to probe the device to constrain their 318 * caps. 319 * * The element opens the device (in case feature need to be probed). 320 * @GST_STATE_CHANGE_READY_TO_PAUSED : state change from READY to PAUSED. 321 * * The element pads are activated in order to receive data in PAUSED. 322 * Streaming threads are started. 323 * * Some elements might need to return %GST_STATE_CHANGE_ASYNC and complete 324 * the state change when they have enough information. It is a requirement 325 * for sinks to return %GST_STATE_CHANGE_ASYNC and complete the state change 326 * when they receive the first buffer or %GST_EVENT_EOS (preroll). 327 * Sinks also block the dataflow when in PAUSED. 328 * * A pipeline resets the running_time to 0. 329 * * Live sources return %GST_STATE_CHANGE_NO_PREROLL and don't generate data. 330 * @GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING. 331 * * Most elements ignore this state change. 332 * * The pipeline selects a #GstClock and distributes this to all the children 333 * before setting them to PLAYING. This means that it is only allowed to 334 * synchronize on the #GstClock in the PLAYING state. 335 * * The pipeline uses the #GstClock and the running_time to calculate the 336 * base_time. The base_time is distributed to all children when performing 337 * the state change. 338 * * Sink elements stop blocking on the preroll buffer or event and start 339 * rendering the data. 340 * * Sinks can post %GST_MESSAGE_EOS in the PLAYING state. It is not allowed 341 * to post %GST_MESSAGE_EOS when not in the PLAYING state. 342 * * While streaming in PAUSED or PLAYING elements can create and remove 343 * sometimes pads. 344 * * Live sources start generating data and return %GST_STATE_CHANGE_SUCCESS. 345 * @GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED. 346 * * Most elements ignore this state change. 347 * * The pipeline calculates the running_time based on the last selected 348 * #GstClock and the base_time. It stores this information to continue 349 * playback when going back to the PLAYING state. 350 * * Sinks unblock any #GstClock wait calls. 351 * * When a sink does not have a pending buffer to play, it returns 352 * #GST_STATE_CHANGE_ASYNC from this state change and completes the state 353 * change when it receives a new buffer or an %GST_EVENT_EOS. 354 * * Any queued %GST_MESSAGE_EOS items are removed since they will be reposted 355 * when going back to the PLAYING state. The EOS messages are queued in 356 * #GstBin containers. 357 * * Live sources stop generating data and return %GST_STATE_CHANGE_NO_PREROLL. 358 * @GST_STATE_CHANGE_PAUSED_TO_READY : state change from PAUSED to READY. 359 * * Sinks unblock any waits in the preroll. 360 * * Elements unblock any waits on devices 361 * * Chain or get_range functions return %GST_FLOW_FLUSHING. 362 * * The element pads are deactivated so that streaming becomes impossible and 363 * all streaming threads are stopped. 364 * * The sink forgets all negotiated formats 365 * * Elements remove all sometimes pads 366 * @GST_STATE_CHANGE_READY_TO_NULL : state change from READY to NULL. 367 * * Elements close devices 368 * * Elements reset any internal state. 369 * @GST_STATE_CHANGE_NULL_TO_NULL : state change from NULL to NULL. (Since: 1.14) 370 * @GST_STATE_CHANGE_READY_TO_READY : state change from READY to READY, 371 * This might happen when going to PAUSED asynchronously failed, in that case 372 * elements should make sure they are in a proper, coherent READY state. (Since: 1.14) 373 * @GST_STATE_CHANGE_PAUSED_TO_PAUSED : state change from PAUSED to PAUSED. 374 * This might happen when elements were in PLAYING state and 'lost state', 375 * they should make sure to go back to real 'PAUSED' state (prerolling for example). (Since: 1.14) 376 * @GST_STATE_CHANGE_PLAYING_TO_PLAYING : state change from PLAYING to PLAYING. (Since: 1.14) 377 * 378 * These are the different state changes an element goes through. 379 * %GST_STATE_NULL ⇒ %GST_STATE_PLAYING is called an upwards state change 380 * and %GST_STATE_PLAYING ⇒ %GST_STATE_NULL a downwards state change. 381 */ 382 typedef enum /*< flags=0 >*/ 383 { 384 GST_STATE_CHANGE_NULL_TO_READY = (GST_STATE_NULL<<3) | GST_STATE_READY, 385 GST_STATE_CHANGE_READY_TO_PAUSED = (GST_STATE_READY<<3) | GST_STATE_PAUSED, 386 GST_STATE_CHANGE_PAUSED_TO_PLAYING = (GST_STATE_PAUSED<<3) | GST_STATE_PLAYING, 387 GST_STATE_CHANGE_PLAYING_TO_PAUSED = (GST_STATE_PLAYING<<3) | GST_STATE_PAUSED, 388 GST_STATE_CHANGE_PAUSED_TO_READY = (GST_STATE_PAUSED<<3) | GST_STATE_READY, 389 GST_STATE_CHANGE_READY_TO_NULL = (GST_STATE_READY<<3) | GST_STATE_NULL, 390 GST_STATE_CHANGE_NULL_TO_NULL = (GST_STATE_NULL<<3) | GST_STATE_NULL, 391 GST_STATE_CHANGE_READY_TO_READY = (GST_STATE_READY<<3) | GST_STATE_READY, 392 GST_STATE_CHANGE_PAUSED_TO_PAUSED = (GST_STATE_PAUSED<<3) | GST_STATE_PAUSED, 393 GST_STATE_CHANGE_PLAYING_TO_PLAYING = (GST_STATE_PLAYING<<3) | GST_STATE_PLAYING 394 } GstStateChange; 395 396 /** 397 * GstElementFlags: 398 * @GST_ELEMENT_FLAG_LOCKED_STATE: ignore state changes from parent 399 * @GST_ELEMENT_FLAG_SINK: the element is a sink 400 * @GST_ELEMENT_FLAG_SOURCE: the element is a source. 401 * @GST_ELEMENT_FLAG_PROVIDE_CLOCK: the element can provide a clock 402 * @GST_ELEMENT_FLAG_REQUIRE_CLOCK: the element requires a clock 403 * @GST_ELEMENT_FLAG_INDEXABLE: the element can use an index 404 * @GST_ELEMENT_FLAG_LAST: offset to define more flags 405 * 406 * The standard flags that an element may have. 407 */ 408 typedef enum 409 { 410 GST_ELEMENT_FLAG_LOCKED_STATE = (GST_OBJECT_FLAG_LAST << 0), 411 GST_ELEMENT_FLAG_SINK = (GST_OBJECT_FLAG_LAST << 1), 412 GST_ELEMENT_FLAG_SOURCE = (GST_OBJECT_FLAG_LAST << 2), 413 GST_ELEMENT_FLAG_PROVIDE_CLOCK = (GST_OBJECT_FLAG_LAST << 3), 414 GST_ELEMENT_FLAG_REQUIRE_CLOCK = (GST_OBJECT_FLAG_LAST << 4), 415 GST_ELEMENT_FLAG_INDEXABLE = (GST_OBJECT_FLAG_LAST << 5), 416 /* padding */ 417 GST_ELEMENT_FLAG_LAST = (GST_OBJECT_FLAG_LAST << 10) 418 } GstElementFlags; 419 420 /** 421 * GST_ELEMENT_IS_LOCKED_STATE: 422 * @elem: A #GstElement to query 423 * 424 * Check if the element is in the locked state and therefore will ignore state 425 * changes from its parent object. 426 */ 427 #define GST_ELEMENT_IS_LOCKED_STATE(elem) (GST_OBJECT_FLAG_IS_SET(elem,GST_ELEMENT_FLAG_LOCKED_STATE)) 428 429 /** 430 * GST_ELEMENT_NAME: 431 * @elem: A #GstElement to query 432 * 433 * Gets the name of this element. This is not thread-safe by default 434 * (i.e. you will have to make sure the object lock is taken yourself). 435 * If in doubt use gst_element_get_name() instead. 436 */ 437 #define GST_ELEMENT_NAME(elem) (GST_OBJECT_NAME(elem)) 438 439 /** 440 * GST_ELEMENT_PARENT: 441 * @elem: A #GstElement to query 442 * 443 * Get the parent object of this element. This is not thread-safe by default 444 * (i.e. you will have to make sure the object lock is taken yourself). 445 * If in doubt use gst_object_get_parent() instead. 446 */ 447 #define GST_ELEMENT_PARENT(elem) (GST_ELEMENT_CAST(GST_OBJECT_PARENT(elem))) 448 449 /** 450 * GST_ELEMENT_BUS: 451 * @elem: A #GstElement to query 452 * 453 * Get the message bus of this element. This is not thread-safe by default 454 * (i.e. you will have to make sure the object lock is taken yourself). 455 * If in doubt use gst_element_get_bus() instead. 456 */ 457 #define GST_ELEMENT_BUS(elem) (GST_ELEMENT_CAST(elem)->bus) 458 459 /** 460 * GST_ELEMENT_CLOCK: 461 * @elem: A #GstElement to query 462 * 463 * Get the clock of this element.This is not thread-safe by default 464 * (i.e. you will have to make sure it is safe yourself). 465 * If in doubt use gst_element_get_clock() instead. 466 */ 467 #define GST_ELEMENT_CLOCK(elem) (GST_ELEMENT_CAST(elem)->clock) 468 469 /** 470 * GST_ELEMENT_PADS: 471 * @elem: A #GstElement to query 472 * 473 * Get the pads of this elements. 474 */ 475 #define GST_ELEMENT_PADS(elem) (GST_ELEMENT_CAST(elem)->pads) 476 477 /** 478 * GST_ELEMENT_START_TIME: 479 * @elem: a #GstElement to return the start time for. 480 * 481 * This macro returns the start_time of the @elem. The start_time is the 482 * running_time of the pipeline when the element went to PAUSED. 483 */ 484 #define GST_ELEMENT_START_TIME(elem) (GST_ELEMENT_CAST(elem)->start_time) 485 486 GST_API 487 GstStructure *gst_make_element_message_details (const char *name, ...) G_GNUC_NULL_TERMINATED; 488 489 #define GST_ELEMENT_MESSAGE_MAKE_DETAILS(args) gst_make_element_message_details args 490 491 /** 492 * GST_ELEMENT_FLOW_ERROR: 493 * @el: the element that generates the error 494 * @flow_return: the GstFlowReturn leading to that ERROR message 495 * 496 * Utility function that elements can use in case they encountered a fatal 497 * data processing error due to wrong flow processing. 498 * 499 * Since: 1.10 500 */ 501 #define GST_ELEMENT_FLOW_ERROR(el,flow_return) \ 502 G_STMT_START { \ 503 GST_ELEMENT_ERROR_WITH_DETAILS (el, STREAM, FAILED, \ 504 ("Internal data stream error."), \ 505 ("streaming stopped, reason %s (%d)", gst_flow_get_name (flow_return), flow_return), \ 506 ("flow-return", G_TYPE_INT, flow_return, NULL));\ 507 } G_STMT_END 508 509 /** 510 * GST_ELEMENT_ERROR_WITH_DETAILS: 511 * @el: the element that generates the error 512 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) 513 * @code: error code defined for that domain (see [GstGError](gsterror)) 514 * @text: the message to display (format string and args enclosed in 515 parentheses) 516 * @debug: debugging information for the message (format string and args 517 enclosed in parentheses) 518 * @args: optional name, type, value triplets, which will be stored 519 * in the associated GstStructure. NULL terminator required. 520 * Must be enclosed within parentheses. 521 * 522 * Utility function that elements can use in case they encountered a fatal 523 * data processing error. The pipeline will post an error message and the 524 * application will be requested to stop further media processing. 525 * 526 * Since: 1.10 527 */ 528 #define GST_ELEMENT_ERROR_WITH_DETAILS(el,domain,code,text,debug,args) \ 529 G_STMT_START { \ 530 gchar *__txt = _gst_element_error_printf text; \ 531 gchar *__dbg = _gst_element_error_printf debug; \ 532 if (__txt) \ 533 GST_WARNING_OBJECT (el, "error: %s", __txt); \ 534 if (__dbg) \ 535 GST_WARNING_OBJECT (el, "error: %s", __dbg); \ 536 gst_element_message_full_with_details (GST_ELEMENT(el), \ 537 GST_MESSAGE_ERROR, GST_ ## domain ## _ERROR, \ 538 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 539 GST_FUNCTION, __LINE__, GST_ELEMENT_MESSAGE_MAKE_DETAILS(args)); \ 540 } G_STMT_END 541 542 /** 543 * GST_ELEMENT_ERROR: 544 * @el: the element that generates the error 545 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) 546 * @code: error code defined for that domain (see [GstGError](gsterror)) 547 * @text: the message to display (format string and args enclosed in 548 parentheses) 549 * @debug: debugging information for the message (format string and args 550 enclosed in parentheses) 551 * 552 * Utility function that elements can use in case they encountered a fatal 553 * data processing error. The pipeline will post an error message and the 554 * application will be requested to stop further media processing. 555 */ 556 #define GST_ELEMENT_ERROR(el,domain,code,text,debug) \ 557 G_STMT_START { \ 558 gchar *__txt = _gst_element_error_printf text; \ 559 gchar *__dbg = _gst_element_error_printf debug; \ 560 if (__txt) \ 561 GST_WARNING_OBJECT (el, "error: %s", __txt); \ 562 if (__dbg) \ 563 GST_WARNING_OBJECT (el, "error: %s", __dbg); \ 564 gst_element_message_full (GST_ELEMENT(el), \ 565 GST_MESSAGE_ERROR, GST_ ## domain ## _ERROR, \ 566 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 567 GST_FUNCTION, __LINE__); \ 568 } G_STMT_END 569 570 /** 571 * GST_ELEMENT_WARNING_WITH_DETAILS: 572 * @el: the element that generates the warning 573 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) 574 * @code: error code defined for that domain (see [GstGError](gsterror)) 575 * @text: the message to display (format string and args enclosed in 576 parentheses) 577 * @debug: debugging information for the message (format string and args 578 enclosed in parentheses) 579 * @args: optional name, type, value triplets, which will be stored 580 * in the associated GstStructure. NULL terminator required. 581 * Must be enclosed within parentheses. 582 * 583 * Utility function that elements can use in case they encountered a non-fatal 584 * data processing problem. The pipeline will post a warning message and the 585 * application will be informed. 586 * 587 * Since: 1.10 588 */ 589 #define GST_ELEMENT_WARNING_WITH_DETAILS(el, domain, code, text, debug, args)\ 590 G_STMT_START { \ 591 gchar *__txt = _gst_element_error_printf text; \ 592 gchar *__dbg = _gst_element_error_printf debug; \ 593 if (__txt) \ 594 GST_WARNING_OBJECT (el, "warning: %s", __txt); \ 595 if (__dbg) \ 596 GST_WARNING_OBJECT (el, "warning: %s", __dbg); \ 597 gst_element_message_full_with_details (GST_ELEMENT(el), \ 598 GST_MESSAGE_WARNING, GST_ ## domain ## _ERROR, \ 599 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 600 GST_FUNCTION, __LINE__, GST_ELEMENT_MESSAGE_MAKE_DETAILS(args)); \ 601 } G_STMT_END 602 603 /** 604 * GST_ELEMENT_WARNING: 605 * @el: the element that generates the warning 606 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) 607 * @code: error code defined for that domain (see [GstGError](gsterror)) 608 * @text: the message to display (format string and args enclosed in 609 parentheses) 610 * @debug: debugging information for the message (format string and args 611 enclosed in parentheses) 612 * 613 * Utility function that elements can use in case they encountered a non-fatal 614 * data processing problem. The pipeline will post a warning message and the 615 * application will be informed. 616 */ 617 #define GST_ELEMENT_WARNING(el, domain, code, text, debug) \ 618 G_STMT_START { \ 619 gchar *__txt = _gst_element_error_printf text; \ 620 gchar *__dbg = _gst_element_error_printf debug; \ 621 if (__txt) \ 622 GST_WARNING_OBJECT (el, "warning: %s", __txt); \ 623 if (__dbg) \ 624 GST_WARNING_OBJECT (el, "warning: %s", __dbg); \ 625 gst_element_message_full (GST_ELEMENT(el), \ 626 GST_MESSAGE_WARNING, GST_ ## domain ## _ERROR, \ 627 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 628 GST_FUNCTION, __LINE__); \ 629 } G_STMT_END 630 631 /** 632 * GST_ELEMENT_INFO_WITH_DETAILS: 633 * @el: the element that generates the information 634 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) 635 * @code: error code defined for that domain (see [GstGError](gsterror)) 636 * @text: the message to display (format string and args enclosed in 637 parentheses) 638 * @debug: debugging information for the message (format string and args 639 enclosed in parentheses) 640 * @args: optional name, type, value triplets, which will be stored 641 * in the associated GstStructure. NULL terminator required. 642 * Must be enclosed within parentheses. 643 * 644 * Utility function that elements can use in case they want to inform 645 * the application of something noteworthy that is not an error. 646 * The pipeline will post a info message and the 647 * application will be informed. 648 * Optional name, type, value triplets may be supplied, and will be stored 649 * in the associated GstStructure. NULL terminator required. 650 * 651 * Since: 1.10 652 */ 653 #define GST_ELEMENT_INFO_WITH_DETAILS(el, domain, code, text, debug, args) \ 654 G_STMT_START { \ 655 gchar *__txt = _gst_element_error_printf text; \ 656 gchar *__dbg = _gst_element_error_printf debug; \ 657 if (__txt) \ 658 GST_INFO_OBJECT (el, "info: %s", __txt); \ 659 if (__dbg) \ 660 GST_INFO_OBJECT (el, "info: %s", __dbg); \ 661 gst_element_message_full_with_details (GST_ELEMENT(el), \ 662 GST_MESSAGE_INFO, GST_ ## domain ## _ERROR, \ 663 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 664 GST_FUNCTION, __LINE__, GST_ELEMENT_MESSAGE_MAKE_DETAILS(args)); \ 665 } G_STMT_END 666 667 /** 668 * GST_ELEMENT_INFO: 669 * @el: the element that generates the information 670 * @domain: like CORE, LIBRARY, RESOURCE or STREAM (see [GstGError](gsterror)) 671 * @code: error code defined for that domain (see [GstGError](gsterror)) 672 * @text: the message to display (format string and args enclosed in 673 parentheses) 674 * @debug: debugging information for the message (format string and args 675 enclosed in parentheses) 676 * 677 * Utility function that elements can use in case they want to inform 678 * the application of something noteworthy that is not an error. 679 * The pipeline will post a info message and the 680 * application will be informed. 681 */ 682 #define GST_ELEMENT_INFO(el, domain, code, text, debug) \ 683 G_STMT_START { \ 684 gchar *__txt = _gst_element_error_printf text; \ 685 gchar *__dbg = _gst_element_error_printf debug; \ 686 if (__txt) \ 687 GST_INFO_OBJECT (el, "info: %s", __txt); \ 688 if (__dbg) \ 689 GST_INFO_OBJECT (el, "info: %s", __dbg); \ 690 gst_element_message_full (GST_ELEMENT(el), \ 691 GST_MESSAGE_INFO, GST_ ## domain ## _ERROR, \ 692 GST_ ## domain ## _ERROR_ ## code, __txt, __dbg, __FILE__, \ 693 GST_FUNCTION, __LINE__); \ 694 } G_STMT_END 695 696 /* the state change mutexes and conds */ 697 /** 698 * GST_STATE_GET_LOCK: 699 * @elem: a #GstElement 700 * 701 * Get a reference to the state lock of @elem. 702 * This lock is used by the core. It is taken while getting or setting 703 * the state, during state changes, and while finalizing. 704 */ 705 #define GST_STATE_GET_LOCK(elem) (&(GST_ELEMENT_CAST(elem)->state_lock)) 706 /** 707 * GST_STATE_GET_COND: 708 * @elem: a #GstElement 709 * 710 * Get the conditional used to signal the completion of a state change. 711 */ 712 #define GST_STATE_GET_COND(elem) (&GST_ELEMENT_CAST(elem)->state_cond) 713 714 #define GST_STATE_LOCK(elem) g_rec_mutex_lock(GST_STATE_GET_LOCK(elem)) 715 #define GST_STATE_TRYLOCK(elem) g_rec_mutex_trylock(GST_STATE_GET_LOCK(elem)) 716 #define GST_STATE_UNLOCK(elem) g_rec_mutex_unlock(GST_STATE_GET_LOCK(elem)) 717 #define GST_STATE_WAIT(elem) g_cond_wait (GST_STATE_GET_COND (elem), \ 718 GST_OBJECT_GET_LOCK (elem)) 719 #define GST_STATE_WAIT_UNTIL(elem, end_time) g_cond_wait_until (GST_STATE_GET_COND (elem), \ 720 GST_OBJECT_GET_LOCK (elem), end_time) 721 #define GST_STATE_SIGNAL(elem) g_cond_signal (GST_STATE_GET_COND (elem)); 722 #define GST_STATE_BROADCAST(elem) g_cond_broadcast (GST_STATE_GET_COND (elem)); 723 724 /** 725 * GstElement: 726 * @state_lock: Used to serialize execution of gst_element_set_state() 727 * @state_cond: Used to signal completion of a state change 728 * @state_cookie: Used to detect concurrent execution of 729 * gst_element_set_state() and gst_element_get_state() 730 * @target_state: the target state of an element as set by the application 731 * @current_state: the current state of an element 732 * @next_state: the next state of an element, can be #GST_STATE_VOID_PENDING if 733 * the element is in the correct state. 734 * @pending_state: the final state the element should go to, can be 735 * #GST_STATE_VOID_PENDING if the element is in the correct state 736 * @last_return: the last return value of an element state change 737 * @bus: the bus of the element. This bus is provided to the element by the 738 * parent element or the application. A #GstPipeline has a bus of its own. 739 * @clock: the clock of the element. This clock is usually provided to the 740 * element by the toplevel #GstPipeline. 741 * @base_time: the time of the clock right before the element is set to 742 * PLAYING. Subtracting @base_time from the current clock time in the PLAYING 743 * state will yield the running_time against the clock. 744 * @start_time: the running_time of the last PAUSED state 745 * @numpads: number of pads of the element, includes both source and sink pads. 746 * @pads: (element-type Gst.Pad): list of pads 747 * @numsrcpads: number of source pads of the element. 748 * @srcpads: (element-type Gst.Pad): list of source pads 749 * @numsinkpads: number of sink pads of the element. 750 * @sinkpads: (element-type Gst.Pad): list of sink pads 751 * @pads_cookie: updated whenever the a pad is added or removed 752 * @contexts: (element-type Gst.Context): list of contexts 753 * 754 * GStreamer element abstract base class. 755 */ 756 struct _GstElement 757 { 758 GstObject object; 759 760 /*< public >*/ /* with LOCK */ 761 GRecMutex state_lock; 762 763 /* element state */ 764 GCond state_cond; 765 guint32 state_cookie; 766 GstState target_state; 767 GstState current_state; 768 GstState next_state; 769 GstState pending_state; 770 GstStateChangeReturn last_return; 771 772 GstBus *bus; 773 774 /* allocated clock */ 775 GstClock *clock; 776 GstClockTimeDiff base_time; /* NULL/READY: 0 - PAUSED: current time - PLAYING: difference to clock */ 777 GstClockTime start_time; 778 779 /* element pads, these lists can only be iterated while holding 780 * the LOCK or checking the cookie after each LOCK. */ 781 guint16 numpads; 782 GList *pads; 783 guint16 numsrcpads; 784 GList *srcpads; 785 guint16 numsinkpads; 786 GList *sinkpads; 787 guint32 pads_cookie; 788 789 /* with object LOCK */ 790 GList *contexts; 791 792 /*< private >*/ 793 gpointer _gst_reserved[GST_PADDING-1]; 794 }; 795 796 /** 797 * GstElementClass: 798 * @parent_class: the parent class structure 799 * @metadata: metadata for elements of this class 800 * @elementfactory: the #GstElementFactory that creates these elements 801 * @padtemplates: a #GList of #GstPadTemplate 802 * @numpadtemplates: the number of padtemplates 803 * @pad_templ_cookie: changed whenever the padtemplates change 804 * @request_new_pad: called when a new pad is requested 805 * @release_pad: called when a request pad is to be released 806 * @get_state: get the state of the element 807 * @set_state: set a new state on the element 808 * @change_state: called by @set_state to perform an incremental state change 809 * @set_bus: set a #GstBus on the element 810 * @provide_clock: gets the #GstClock provided by the element 811 * @set_clock: set the #GstClock on the element 812 * @send_event: send a #GstEvent to the element 813 * @query: perform a #GstQuery on the element 814 * @state_changed: called immediately after a new state was set. 815 * @post_message: called when a message is posted on the element. Chain up to 816 * the parent class' handler to have it posted on the bus. 817 * @set_context: set a #GstContext on the element 818 * 819 * GStreamer element class. Override the vmethods to implement the element 820 * functionality. 821 */ 822 struct _GstElementClass 823 { 824 GstObjectClass parent_class; 825 826 /*< public >*/ 827 /* the element metadata */ 828 gpointer metadata; 829 830 /* factory that the element was created from */ 831 GstElementFactory *elementfactory; 832 833 /* templates for our pads */ 834 GList *padtemplates; 835 gint numpadtemplates; 836 guint32 pad_templ_cookie; 837 838 /*< private >*/ 839 /* signal callbacks */ 840 void (*pad_added) (GstElement *element, GstPad *pad); 841 void (*pad_removed) (GstElement *element, GstPad *pad); 842 void (*no_more_pads) (GstElement *element); 843 844 /*< public >*/ 845 /* virtual methods for subclasses */ 846 847 /* request/release pads */ 848 /* FIXME 2.0 harmonize naming with gst_element_request_pad */ 849 GstPad* (*request_new_pad) (GstElement *element, GstPadTemplate *templ, 850 const gchar* name, const GstCaps *caps); 851 852 void (*release_pad) (GstElement *element, GstPad *pad); 853 854 /* state changes */ 855 GstStateChangeReturn (*get_state) (GstElement * element, GstState * state, 856 GstState * pending, GstClockTime timeout); 857 GstStateChangeReturn (*set_state) (GstElement *element, GstState state); 858 GstStateChangeReturn (*change_state) (GstElement *element, GstStateChange transition); 859 void (*state_changed) (GstElement *element, GstState oldstate, 860 GstState newstate, GstState pending); 861 862 /* bus */ 863 void (*set_bus) (GstElement * element, GstBus * bus); 864 865 /* set/get clocks */ 866 GstClock* (*provide_clock) (GstElement *element); 867 gboolean (*set_clock) (GstElement *element, GstClock *clock); 868 869 /* query functions */ 870 gboolean (*send_event) (GstElement *element, GstEvent *event); 871 872 gboolean (*query) (GstElement *element, GstQuery *query); 873 874 gboolean (*post_message) (GstElement *element, GstMessage *message); 875 876 void (*set_context) (GstElement *element, GstContext *context); 877 878 /*< private >*/ 879 gpointer _gst_reserved[GST_PADDING_LARGE-2]; 880 }; 881 882 /* element class pad templates */ 883 884 GST_API 885 void gst_element_class_add_pad_template (GstElementClass *klass, GstPadTemplate *templ); 886 887 GST_API 888 void gst_element_class_add_static_pad_template (GstElementClass *klass, GstStaticPadTemplate *static_templ); 889 890 GST_API 891 void gst_element_class_add_static_pad_template_with_gtype (GstElementClass *klass, 892 GstStaticPadTemplate *static_templ, 893 GType pad_type); 894 895 GST_API 896 GstPadTemplate* gst_element_class_get_pad_template (GstElementClass *element_class, const gchar *name); 897 898 GST_API 899 GList* gst_element_class_get_pad_template_list (GstElementClass *element_class); 900 901 /* element class meta data */ 902 903 GST_API 904 void gst_element_class_set_metadata (GstElementClass *klass, 905 const gchar *longname, 906 const gchar *classification, 907 const gchar *description, 908 const gchar *author); 909 GST_API 910 void gst_element_class_set_static_metadata (GstElementClass *klass, 911 const gchar *longname, 912 const gchar *classification, 913 const gchar *description, 914 const gchar *author); 915 GST_API 916 void gst_element_class_add_metadata (GstElementClass * klass, 917 const gchar * key, const gchar * value); 918 GST_API 919 void gst_element_class_add_static_metadata (GstElementClass * klass, 920 const gchar * key, const gchar * value); 921 GST_API 922 const gchar * gst_element_class_get_metadata (GstElementClass * klass, 923 const gchar * key); 924 925 926 /* element instance */ 927 928 GST_API 929 GType gst_element_get_type (void); 930 931 /* basic name and parentage stuff from GstObject */ 932 933 /** 934 * gst_element_get_name: 935 * @elem: a #GstElement to get the name of @elem. 936 * 937 * Returns a copy of the name of @elem. 938 * Caller should g_free() the return value after usage. 939 * For a nameless element, this returns %NULL, which you can safely g_free() 940 * as well. 941 * 942 * Returns: (transfer full) (nullable): the name of @elem. g_free() 943 * after usage. MT safe. 944 * 945 */ 946 #define gst_element_get_name(elem) gst_object_get_name(GST_OBJECT_CAST(elem)) 947 948 /** 949 * gst_element_set_name: 950 * @elem: a #GstElement to set the name of. 951 * @name: the new name 952 * 953 * Sets the name of the element, getting rid of the old name if there was one. 954 */ 955 #define gst_element_set_name(elem,name) gst_object_set_name(GST_OBJECT_CAST(elem),name) 956 957 /** 958 * gst_element_get_parent: 959 * @elem: a #GstElement to get the parent of. 960 * 961 * Get the parent of an element. 962 * 963 * Returns: (transfer full): the parent of an element. 964 */ 965 #define gst_element_get_parent(elem) gst_object_get_parent(GST_OBJECT_CAST(elem)) 966 967 /** 968 * gst_element_set_parent: 969 * @elem: a #GstElement to set the parent of. 970 * @parent: the new parent #GstObject of the element. 971 * 972 * Sets the parent of an element. 973 */ 974 #define gst_element_set_parent(elem,parent) gst_object_set_parent(GST_OBJECT_CAST(elem),parent) 975 976 /* clocking */ 977 978 GST_API 979 GstClock* gst_element_provide_clock (GstElement *element); 980 981 GST_API 982 GstClock* gst_element_get_clock (GstElement *element); 983 984 GST_API 985 gboolean gst_element_set_clock (GstElement *element, GstClock *clock); 986 987 GST_API 988 void gst_element_set_base_time (GstElement *element, GstClockTime time); 989 990 GST_API 991 GstClockTime gst_element_get_base_time (GstElement *element); 992 993 GST_API 994 void gst_element_set_start_time (GstElement *element, GstClockTime time); 995 996 GST_API 997 GstClockTime gst_element_get_start_time (GstElement *element); 998 999 GST_API 1000 GstClockTime gst_element_get_current_running_time (GstElement *element); 1001 1002 GST_API 1003 GstClockTime gst_element_get_current_clock_time (GstElement *element); 1004 1005 /* bus */ 1006 1007 GST_API 1008 void gst_element_set_bus (GstElement * element, GstBus * bus); 1009 1010 GST_API 1011 GstBus * gst_element_get_bus (GstElement * element); 1012 1013 /* context */ 1014 1015 GST_API 1016 void gst_element_set_context (GstElement * element, GstContext * context); 1017 1018 GST_API 1019 GList * gst_element_get_contexts (GstElement * element); 1020 1021 GST_API 1022 GstContext * gst_element_get_context (GstElement * element, const gchar * context_type); 1023 1024 GST_API 1025 GstContext * gst_element_get_context_unlocked (GstElement * element, const gchar * context_type); 1026 1027 /* pad management */ 1028 1029 GST_API 1030 gboolean gst_element_add_pad (GstElement *element, GstPad *pad); 1031 1032 GST_API 1033 gboolean gst_element_remove_pad (GstElement *element, GstPad *pad); 1034 1035 GST_API 1036 void gst_element_no_more_pads (GstElement *element); 1037 1038 GST_API 1039 GstPad* gst_element_get_static_pad (GstElement *element, const gchar *name); 1040 1041 GST_API G_DEPRECATED_FOR(gst_element_request_pad_simple) 1042 GstPad* gst_element_get_request_pad (GstElement *element, const gchar *name); 1043 1044 GST_API 1045 GstPad* gst_element_request_pad_simple (GstElement *element, const gchar *name); 1046 1047 GST_API 1048 GstPad* gst_element_request_pad (GstElement *element, GstPadTemplate *templ, 1049 const gchar * name, const GstCaps *caps); 1050 GST_API 1051 void gst_element_release_request_pad (GstElement *element, GstPad *pad); 1052 1053 GST_API 1054 GstIterator * gst_element_iterate_pads (GstElement * element); 1055 1056 GST_API 1057 GstIterator * gst_element_iterate_src_pads (GstElement * element); 1058 1059 GST_API 1060 GstIterator * gst_element_iterate_sink_pads (GstElement * element); 1061 1062 /** 1063 * GstElementForeachPadFunc: 1064 * @element: the #GstElement 1065 * @pad: a #GstPad 1066 * @user_data: user data passed to the foreach function 1067 * 1068 * Function called for each pad when using gst_element_foreach_sink_pad(), 1069 * gst_element_foreach_src_pad(), or gst_element_foreach_pad(). 1070 * 1071 * Returns: %FALSE to stop iterating pads, %TRUE to continue 1072 * 1073 * Since: 1.14 1074 */ 1075 typedef gboolean (*GstElementForeachPadFunc) (GstElement * element, 1076 GstPad * pad, 1077 gpointer user_data); 1078 1079 GST_API 1080 gboolean gst_element_foreach_sink_pad (GstElement * element, 1081 GstElementForeachPadFunc func, 1082 gpointer user_data); 1083 GST_API 1084 gboolean gst_element_foreach_src_pad (GstElement * element, 1085 GstElementForeachPadFunc func, 1086 gpointer user_data); 1087 GST_API 1088 gboolean gst_element_foreach_pad (GstElement * element, 1089 GstElementForeachPadFunc func, 1090 gpointer user_data); 1091 /* event/query/format stuff */ 1092 1093 GST_API 1094 gboolean gst_element_send_event (GstElement *element, GstEvent *event); 1095 1096 GST_API 1097 gboolean gst_element_seek (GstElement *element, gdouble rate, 1098 GstFormat format, GstSeekFlags flags, 1099 GstSeekType start_type, gint64 start, 1100 GstSeekType stop_type, gint64 stop); 1101 GST_API 1102 gboolean gst_element_query (GstElement *element, GstQuery *query); 1103 1104 /* messages */ 1105 1106 GST_API 1107 gboolean gst_element_post_message (GstElement * element, GstMessage * message); 1108 1109 /* error handling */ 1110 /* gcc versions < 3.3 warn about NULL being passed as format to printf */ 1111 #if (!defined(__GNUC__) || (__GNUC__ < 3) || (__GNUC__ == 3 && __GNUC_MINOR__ < 3)) 1112 GST_API 1113 gchar * _gst_element_error_printf (const gchar *format, ...); 1114 #else 1115 GST_API 1116 gchar * _gst_element_error_printf (const gchar *format, ...) G_GNUC_PRINTF (1, 2); 1117 #endif 1118 1119 GST_API 1120 void gst_element_message_full (GstElement * element, GstMessageType type, 1121 GQuark domain, gint code, gchar * text, 1122 gchar * debug, const gchar * file, 1123 const gchar * function, gint line); 1124 GST_API 1125 void gst_element_message_full_with_details (GstElement * element, GstMessageType type, 1126 GQuark domain, gint code, gchar * text, 1127 gchar * debug, const gchar * file, 1128 const gchar * function, gint line, 1129 GstStructure * structure); 1130 1131 /* state management */ 1132 1133 GST_API 1134 gboolean gst_element_is_locked_state (GstElement *element); 1135 1136 GST_API 1137 gboolean gst_element_set_locked_state (GstElement *element, gboolean locked_state); 1138 1139 GST_API 1140 gboolean gst_element_sync_state_with_parent (GstElement *element); 1141 1142 GST_API 1143 GstStateChangeReturn gst_element_get_state (GstElement * element, 1144 GstState * state, 1145 GstState * pending, 1146 GstClockTime timeout); 1147 GST_API 1148 GstStateChangeReturn gst_element_set_state (GstElement *element, GstState state); 1149 1150 GST_API 1151 void gst_element_abort_state (GstElement * element); 1152 1153 GST_API 1154 GstStateChangeReturn gst_element_change_state (GstElement * element, 1155 GstStateChange transition); 1156 1157 GST_API 1158 GstStateChangeReturn gst_element_continue_state (GstElement * element, 1159 GstStateChangeReturn ret); 1160 GST_API 1161 void gst_element_lost_state (GstElement * element); 1162 1163 1164 /** 1165 * GstElementCallAsyncFunc: 1166 * @element: The #GstElement this function has been called against 1167 * @user_data: Data passed in the function where that callback has been passed 1168 * 1169 * Callback prototype used in #gst_element_call_async 1170 */ 1171 typedef void (*GstElementCallAsyncFunc) (GstElement * element, 1172 gpointer user_data); 1173 GST_API 1174 void gst_element_call_async (GstElement * element, 1175 GstElementCallAsyncFunc func, gpointer user_data, 1176 GDestroyNotify destroy_notify); 1177 1178 /* factory management */ 1179 1180 GST_API 1181 GstElementFactory* gst_element_get_factory (GstElement *element); 1182 1183 /* utility functions */ 1184 1185 GST_API 1186 gulong gst_element_add_property_notify_watch (GstElement * element, 1187 const gchar * property_name, 1188 gboolean include_value); 1189 GST_API 1190 gulong gst_element_add_property_deep_notify_watch (GstElement * element, 1191 const gchar * property_name, 1192 gboolean include_value); 1193 GST_API 1194 void gst_element_remove_property_notify_watch (GstElement * element, 1195 gulong watch_id); 1196 1197 GST_API 1198 GstPadTemplate* gst_element_get_pad_template (GstElement *element, const gchar *name); 1199 1200 GST_API 1201 GList* gst_element_get_pad_template_list (GstElement *element); 1202 GST_API 1203 const gchar * gst_element_get_metadata (GstElement * element, const gchar * key); 1204 1205 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstElement, gst_object_unref) 1206 1207 G_END_DECLS 1208 1209 #endif /* __GST_ELEMENT_H__ */ 1210