1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gstreamer.Bus; 26 27 private import glib.ConstructionException; 28 private import glib.Source; 29 private import gobject.ObjectG; 30 private import gobject.Signals; 31 private import gstreamer.Message; 32 private import gstreamer.ObjectGst; 33 private import gstreamer.c.functions; 34 public import gstreamer.c.types; 35 public import gstreamerc.gstreamertypes; 36 private import std.algorithm; 37 38 39 /** 40 * The #GstBus is an object responsible for delivering #GstMessage packets in 41 * a first-in first-out way from the streaming threads (see #GstTask) to the 42 * application. 43 * 44 * Since the application typically only wants to deal with delivery of these 45 * messages from one thread, the GstBus will marshall the messages between 46 * different threads. This is important since the actual streaming of media 47 * is done in another thread than the application. 48 * 49 * The GstBus provides support for #GSource based notifications. This makes it 50 * possible to handle the delivery in the glib mainloop. 51 * 52 * The #GSource callback function gst_bus_async_signal_func() can be used to 53 * convert all bus messages into signal emissions. 54 * 55 * A message is posted on the bus with the gst_bus_post() method. With the 56 * gst_bus_peek() and gst_bus_pop() methods one can look at or retrieve a 57 * previously posted message. 58 * 59 * The bus can be polled with the gst_bus_poll() method. This methods blocks 60 * up to the specified timeout value until one of the specified messages types 61 * is posted on the bus. The application can then gst_bus_pop() the messages 62 * from the bus to handle them. 63 * Alternatively the application can register an asynchronous bus function 64 * using gst_bus_add_watch_full() or gst_bus_add_watch(). This function will 65 * install a #GSource in the default glib main loop and will deliver messages 66 * a short while after they have been posted. Note that the main loop should 67 * be running for the asynchronous callbacks. 68 * 69 * It is also possible to get messages from the bus without any thread 70 * marshalling with the gst_bus_set_sync_handler() method. This makes it 71 * possible to react to a message in the same thread that posted the 72 * message on the bus. This should only be used if the application is able 73 * to deal with messages from different threads. 74 * 75 * Every #GstPipeline has one bus. 76 * 77 * Note that a #GstPipeline will set its bus into flushing state when changing 78 * from READY to NULL state. 79 */ 80 public class Bus : ObjectGst 81 { 82 /** the main Gtk struct */ 83 protected GstBus* gstBus; 84 85 /** Get the main Gtk struct */ 86 public GstBus* getBusStruct(bool transferOwnership = false) 87 { 88 if (transferOwnership) 89 ownedRef = false; 90 return gstBus; 91 } 92 93 /** the main Gtk struct as a void* */ 94 protected override void* getStruct() 95 { 96 return cast(void*)gstBus; 97 } 98 99 /** 100 * Sets our main struct and passes it to the parent class. 101 */ 102 public this (GstBus* gstBus, bool ownedRef = false) 103 { 104 this.gstBus = gstBus; 105 super(cast(GstObject*)gstBus, ownedRef); 106 } 107 108 /** 109 * Adds a bus watch to the default main context with the default priority. 110 * This function is used to receive asynchronous messages in the main loop. 111 * The watch can be removed using g_source_remove() or by returning FALSE 112 * from func. 113 * MT safe. 114 * Params: 115 * dlg = A function to call when a message is received. 116 * Returns: 117 * The event source id. 118 */ 119 public uint addWatch( bool delegate(Message) dlg ) 120 { 121 onWatchListener = dlg; 122 return gst_bus_add_watch(gstBus, cast(GstBusFunc)&watchCallBack, cast(void*)this); 123 } 124 125 bool delegate(Message) onWatchListener; 126 127 extern(C) static int watchCallBack(GstBus* bus, GstMessage* msg, Bus bus_d )//gpointer data) 128 { 129 Message msg_d = new Message( msg ); 130 131 return bus_d.onWatchListener( msg_d ); 132 } 133 134 /** 135 * Use this for making an XOverlay. 136 * Sets the synchronous handler on the bus. The function will be called 137 * every time a new message is posted on the bus. Note that the function 138 * will be called in the same thread context as the posting object. This 139 * function is usually only called by the creator of the bus. Applications 140 * should handle messages asynchronously using the gst_bus watch and poll 141 * functions. 142 * You cannot replace an existing sync_handler. You can pass NULL to this 143 * function, which will clear the existing handler. 144 * Params: 145 * dlg = The handler function to install 146 */ 147 public void setSyncHandler( GstBusSyncReply delegate(Message) dlg ) 148 { 149 onSyncHandlerListener = dlg; 150 gst_bus_set_sync_handler(gstBus, cast(GstBusSyncHandler)&syncHandlerCallBack, cast(void*)this, null); 151 } 152 153 GstBusSyncReply delegate(Message) onSyncHandlerListener; 154 155 extern(C) static GstBusSyncReply syncHandlerCallBack(GstBus* bus, GstMessage* msg, Bus bus_d) 156 { 157 Message msg_d = new Message( msg ); 158 159 return bus_d.onSyncHandlerListener( msg_d ); 160 } 161 162 /** 163 */ 164 165 /** */ 166 public static GType getType() 167 { 168 return gst_bus_get_type(); 169 } 170 171 /** 172 * Creates a new #GstBus instance. 173 * 174 * Returns: a new #GstBus instance 175 * 176 * Throws: ConstructionException GTK+ fails to create the object. 177 */ 178 public this() 179 { 180 auto p = gst_bus_new(); 181 182 if(p is null) 183 { 184 throw new ConstructionException("null returned by new"); 185 } 186 187 this(cast(GstBus*) p, true); 188 } 189 190 /** 191 * Adds a bus signal watch to the default main context with the default priority 192 * (%G_PRIORITY_DEFAULT). It is also possible to use a non-default 193 * main context set up using g_main_context_push_thread_default() (before 194 * one had to create a bus watch source and attach it to the desired main 195 * context 'manually'). 196 * 197 * After calling this statement, the bus will emit the "message" signal for each 198 * message posted on the bus. 199 * 200 * This function may be called multiple times. To clean up, the caller is 201 * responsible for calling gst_bus_remove_signal_watch() as many times as this 202 * function is called. 203 * 204 * MT safe. 205 */ 206 public void addSignalWatch() 207 { 208 gst_bus_add_signal_watch(gstBus); 209 } 210 211 /** 212 * Adds a bus signal watch to the default main context with the given @priority 213 * (e.g. %G_PRIORITY_DEFAULT). It is also possible to use a non-default main 214 * context set up using g_main_context_push_thread_default() 215 * (before one had to create a bus watch source and attach it to the desired 216 * main context 'manually'). 217 * 218 * After calling this statement, the bus will emit the "message" signal for each 219 * message posted on the bus when the main loop is running. 220 * 221 * This function may be called multiple times. To clean up, the caller is 222 * responsible for calling gst_bus_remove_signal_watch() as many times as this 223 * function is called. 224 * 225 * There can only be a single bus watch per bus, you must remove any signal 226 * watch before you can set another type of watch. 227 * 228 * MT safe. 229 * 230 * Params: 231 * priority = The priority of the watch. 232 */ 233 public void addSignalWatchFull(int priority) 234 { 235 gst_bus_add_signal_watch_full(gstBus, priority); 236 } 237 238 /** 239 * Adds a bus watch to the default main context with the given @priority (e.g. 240 * %G_PRIORITY_DEFAULT). It is also possible to use a non-default main 241 * context set up using g_main_context_push_thread_default() (before 242 * one had to create a bus watch source and attach it to the desired main 243 * context 'manually'). 244 * 245 * This function is used to receive asynchronous messages in the main loop. 246 * There can only be a single bus watch per bus, you must remove it before you 247 * can set a new one. 248 * 249 * The bus watch will only work if a GLib main loop is being run. 250 * 251 * When @func is called, the message belongs to the caller; if you want to 252 * keep a copy of it, call gst_message_ref() before leaving @func. 253 * 254 * The watch can be removed using gst_bus_remove_watch() or by returning %FALSE 255 * from @func. If the watch was added to the default main context it is also 256 * possible to remove the watch using g_source_remove(). 257 * 258 * The bus watch will take its own reference to the @bus, so it is safe to unref 259 * @bus using gst_object_unref() after setting the bus watch. 260 * 261 * MT safe. 262 * 263 * Params: 264 * priority = The priority of the watch. 265 * func = A function to call when a message is received. 266 * userData = user data passed to @func. 267 * notify = the function to call when the source is removed. 268 * 269 * Returns: The event source id or 0 if @bus already got an event source. 270 */ 271 public uint addWatchFull(int priority, GstBusFunc func, void* userData, GDestroyNotify notify) 272 { 273 return gst_bus_add_watch_full(gstBus, priority, func, userData, notify); 274 } 275 276 /** 277 * A helper #GstBusFunc that can be used to convert all asynchronous messages 278 * into signals. 279 * 280 * Params: 281 * message = the #GstMessage received 282 * data = user data 283 * 284 * Returns: %TRUE 285 */ 286 public bool asyncSignalFunc(Message message, void* data) 287 { 288 return gst_bus_async_signal_func(gstBus, (message is null) ? null : message.getMessageStruct(), data) != 0; 289 } 290 291 /** 292 * Create watch for this bus. The GSource will be dispatched whenever 293 * a message is on the bus. After the GSource is dispatched, the 294 * message is popped off the bus and unreffed. 295 * 296 * Returns: a #GSource that can be added to a mainloop. 297 */ 298 public Source createWatch() 299 { 300 auto p = gst_bus_create_watch(gstBus); 301 302 if(p is null) 303 { 304 return null; 305 } 306 307 return new Source(cast(GSource*) p, true); 308 } 309 310 /** 311 * Instructs GStreamer to stop emitting the "sync-message" signal for this bus. 312 * See gst_bus_enable_sync_message_emission() for more information. 313 * 314 * In the event that multiple pieces of code have called 315 * gst_bus_enable_sync_message_emission(), the sync-message emissions will only 316 * be stopped after all calls to gst_bus_enable_sync_message_emission() were 317 * "cancelled" by calling this function. In this way the semantics are exactly 318 * the same as gst_object_ref() that which calls enable should also call 319 * disable. 320 * 321 * MT safe. 322 */ 323 public void disableSyncMessageEmission() 324 { 325 gst_bus_disable_sync_message_emission(gstBus); 326 } 327 328 /** 329 * Instructs GStreamer to emit the "sync-message" signal after running the bus's 330 * sync handler. This function is here so that code can ensure that they can 331 * synchronously receive messages without having to affect what the bin's sync 332 * handler is. 333 * 334 * This function may be called multiple times. To clean up, the caller is 335 * responsible for calling gst_bus_disable_sync_message_emission() as many times 336 * as this function is called. 337 * 338 * While this function looks similar to gst_bus_add_signal_watch(), it is not 339 * exactly the same -- this function enables <emphasis>synchronous</emphasis> emission of 340 * signals when messages arrive; gst_bus_add_signal_watch() adds an idle callback 341 * to pop messages off the bus <emphasis>asynchronously</emphasis>. The sync-message signal 342 * comes from the thread of whatever object posted the message; the "message" 343 * signal is marshalled to the main thread via the main loop. 344 * 345 * MT safe. 346 */ 347 public void enableSyncMessageEmission() 348 { 349 gst_bus_enable_sync_message_emission(gstBus); 350 } 351 352 /** 353 * Gets the file descriptor from the bus which can be used to get notified about 354 * messages being available with functions like g_poll(), and allows integration 355 * into other event loops based on file descriptors. 356 * Whenever a message is available, the POLLIN / %G_IO_IN event is set. 357 * 358 * Warning: NEVER read or write anything to the returned fd but only use it 359 * for getting notifications via g_poll() or similar and then use the normal 360 * GstBus API, e.g. gst_bus_pop(). 361 * 362 * Params: 363 * fd = A GPollFD to fill 364 * 365 * Since: 1.14 366 */ 367 public void getPollfd(GPollFD* fd) 368 { 369 gst_bus_get_pollfd(gstBus, fd); 370 } 371 372 /** 373 * Check if there are pending messages on the bus that 374 * should be handled. 375 * 376 * Returns: %TRUE if there are messages on the bus to be handled, %FALSE 377 * otherwise. 378 * 379 * MT safe. 380 */ 381 public bool havePending() 382 { 383 return gst_bus_have_pending(gstBus) != 0; 384 } 385 386 /** 387 * Peek the message on the top of the bus' queue. The message will remain 388 * on the bus' message queue. A reference is returned, and needs to be unreffed 389 * by the caller. 390 * 391 * Returns: the #GstMessage that is on the 392 * bus, or %NULL if the bus is empty. 393 * 394 * MT safe. 395 */ 396 public Message peek() 397 { 398 auto p = gst_bus_peek(gstBus); 399 400 if(p is null) 401 { 402 return null; 403 } 404 405 return ObjectG.getDObject!(Message)(cast(GstMessage*) p, true); 406 } 407 408 /** 409 * Poll the bus for messages. Will block while waiting for messages to come. 410 * You can specify a maximum time to poll with the @timeout parameter. If 411 * @timeout is negative, this function will block indefinitely. 412 * 413 * All messages not in @events will be popped off the bus and will be ignored. 414 * It is not possible to use message enums beyond #GST_MESSAGE_EXTENDED in the 415 * @events mask 416 * 417 * Because poll is implemented using the "message" signal enabled by 418 * gst_bus_add_signal_watch(), calling gst_bus_poll() will cause the "message" 419 * signal to be emitted for every message that poll sees. Thus a "message" 420 * signal handler will see the same messages that this function sees -- neither 421 * will steal messages from the other. 422 * 423 * This function will run a main loop from the default main context when 424 * polling. 425 * 426 * You should never use this function, since it is pure evil. This is 427 * especially true for GUI applications based on Gtk+ or Qt, but also for any 428 * other non-trivial application that uses the GLib main loop. As this function 429 * runs a GLib main loop, any callback attached to the default GLib main 430 * context may be invoked. This could be timeouts, GUI events, I/O events etc.; 431 * even if gst_bus_poll() is called with a 0 timeout. Any of these callbacks 432 * may do things you do not expect, e.g. destroy the main application window or 433 * some other resource; change other application state; display a dialog and 434 * run another main loop until the user clicks it away. In short, using this 435 * function may add a lot of complexity to your code through unexpected 436 * re-entrancy and unexpected changes to your application's state. 437 * 438 * For 0 timeouts use gst_bus_pop_filtered() instead of this function; for 439 * other short timeouts use gst_bus_timed_pop_filtered(); everything else is 440 * better handled by setting up an asynchronous bus watch and doing things 441 * from there. 442 * 443 * Params: 444 * events = a mask of #GstMessageType, representing the set of message types to 445 * poll for (note special handling of extended message types below) 446 * timeout = the poll timeout, as a #GstClockTime, or #GST_CLOCK_TIME_NONE to poll 447 * indefinitely. 448 * 449 * Returns: the message that was received, 450 * or %NULL if the poll timed out. The message is taken from the 451 * bus and needs to be unreffed with gst_message_unref() after 452 * usage. 453 */ 454 public Message poll(GstMessageType events, GstClockTime timeout) 455 { 456 auto p = gst_bus_poll(gstBus, events, timeout); 457 458 if(p is null) 459 { 460 return null; 461 } 462 463 return ObjectG.getDObject!(Message)(cast(GstMessage*) p, true); 464 } 465 466 /** 467 * Get a message from the bus. 468 * 469 * Returns: the #GstMessage that is on the 470 * bus, or %NULL if the bus is empty. The message is taken from 471 * the bus and needs to be unreffed with gst_message_unref() after 472 * usage. 473 * 474 * MT safe. 475 */ 476 public Message pop() 477 { 478 auto p = gst_bus_pop(gstBus); 479 480 if(p is null) 481 { 482 return null; 483 } 484 485 return ObjectG.getDObject!(Message)(cast(GstMessage*) p, true); 486 } 487 488 /** 489 * Get a message matching @type from the bus. Will discard all messages on 490 * the bus that do not match @type and that have been posted before the first 491 * message that does match @type. If there is no message matching @type on 492 * the bus, all messages will be discarded. It is not possible to use message 493 * enums beyond #GST_MESSAGE_EXTENDED in the @events mask. 494 * 495 * Params: 496 * types = message types to take into account 497 * 498 * Returns: the next #GstMessage matching 499 * @type that is on the bus, or %NULL if the bus is empty or there 500 * is no message matching @type. The message is taken from the bus 501 * and needs to be unreffed with gst_message_unref() after usage. 502 * 503 * MT safe. 504 */ 505 public Message popFiltered(GstMessageType types) 506 { 507 auto p = gst_bus_pop_filtered(gstBus, types); 508 509 if(p is null) 510 { 511 return null; 512 } 513 514 return ObjectG.getDObject!(Message)(cast(GstMessage*) p, true); 515 } 516 517 /** 518 * Post a message on the given bus. Ownership of the message 519 * is taken by the bus. 520 * 521 * Params: 522 * message = the #GstMessage to post 523 * 524 * Returns: %TRUE if the message could be posted, %FALSE if the bus is flushing. 525 * 526 * MT safe. 527 */ 528 public bool post(Message message) 529 { 530 return gst_bus_post(gstBus, (message is null) ? null : message.getMessageStruct()) != 0; 531 } 532 533 /** 534 * Removes a signal watch previously added with gst_bus_add_signal_watch(). 535 * 536 * MT safe. 537 */ 538 public void removeSignalWatch() 539 { 540 gst_bus_remove_signal_watch(gstBus); 541 } 542 543 /** 544 * Removes an installed bus watch from @bus. 545 * 546 * Returns: %TRUE on success or %FALSE if @bus has no event source. 547 * 548 * Since: 1.6 549 */ 550 public bool removeWatch() 551 { 552 return gst_bus_remove_watch(gstBus) != 0; 553 } 554 555 /** 556 * If @flushing, flush out and unref any messages queued in the bus. Releases 557 * references to the message origin objects. Will flush future messages until 558 * gst_bus_set_flushing() sets @flushing to %FALSE. 559 * 560 * MT safe. 561 * 562 * Params: 563 * flushing = whether or not to flush the bus 564 */ 565 public void setFlushing(bool flushing) 566 { 567 gst_bus_set_flushing(gstBus, flushing); 568 } 569 570 /** 571 * A helper GstBusSyncHandler that can be used to convert all synchronous 572 * messages into signals. 573 * 574 * Params: 575 * message = the #GstMessage received 576 * data = user data 577 * 578 * Returns: GST_BUS_PASS 579 */ 580 public GstBusSyncReply syncSignalHandler(Message message, void* data) 581 { 582 return gst_bus_sync_signal_handler(gstBus, (message is null) ? null : message.getMessageStruct(), data); 583 } 584 585 /** 586 * Get a message from the bus, waiting up to the specified timeout. 587 * 588 * If @timeout is 0, this function behaves like gst_bus_pop(). If @timeout is 589 * #GST_CLOCK_TIME_NONE, this function will block forever until a message was 590 * posted on the bus. 591 * 592 * Params: 593 * timeout = a timeout 594 * 595 * Returns: the #GstMessage that is on the 596 * bus after the specified timeout or %NULL if the bus is empty 597 * after the timeout expired. The message is taken from the bus 598 * and needs to be unreffed with gst_message_unref() after usage. 599 * 600 * MT safe. 601 */ 602 public Message timedPop(GstClockTime timeout) 603 { 604 auto p = gst_bus_timed_pop(gstBus, timeout); 605 606 if(p is null) 607 { 608 return null; 609 } 610 611 return ObjectG.getDObject!(Message)(cast(GstMessage*) p, true); 612 } 613 614 /** 615 * Get a message from the bus whose type matches the message type mask @types, 616 * waiting up to the specified timeout (and discarding any messages that do not 617 * match the mask provided). 618 * 619 * If @timeout is 0, this function behaves like gst_bus_pop_filtered(). If 620 * @timeout is #GST_CLOCK_TIME_NONE, this function will block forever until a 621 * matching message was posted on the bus. 622 * 623 * Params: 624 * timeout = a timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever 625 * types = message types to take into account, GST_MESSAGE_ANY for any type 626 * 627 * Returns: a #GstMessage matching the 628 * filter in @types, or %NULL if no matching message was found on 629 * the bus until the timeout expired. The message is taken from 630 * the bus and needs to be unreffed with gst_message_unref() after 631 * usage. 632 * 633 * MT safe. 634 */ 635 public Message timedPopFiltered(GstClockTime timeout, GstMessageType types) 636 { 637 auto p = gst_bus_timed_pop_filtered(gstBus, timeout, types); 638 639 if(p is null) 640 { 641 return null; 642 } 643 644 return ObjectG.getDObject!(Message)(cast(GstMessage*) p, true); 645 } 646 647 /** 648 * A message has been posted on the bus. This signal is emitted from a 649 * GSource added to the mainloop. this signal will only be emitted when 650 * there is a mainloop running. 651 * 652 * Params: 653 * message = the message that has been posted asynchronously 654 */ 655 gulong addOnMessage(void delegate(Message, Bus) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 656 { 657 return Signals.connect(this, "message", dlg, connectFlags ^ ConnectFlags.SWAPPED); 658 } 659 660 /** 661 * A message has been posted on the bus. This signal is emitted from the 662 * thread that posted the message so one has to be careful with locking. 663 * 664 * This signal will not be emitted by default, you have to call 665 * gst_bus_enable_sync_message_emission() before. 666 * 667 * Params: 668 * message = the message that has been posted synchronously 669 */ 670 gulong addOnSyncMessage(void delegate(Message, Bus) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0) 671 { 672 return Signals.connect(this, "sync-message", dlg, connectFlags ^ ConnectFlags.SWAPPED); 673 } 674 }